Workflow Sessions

Track multi-step workflow executions with session history.

Workflow sessions track the execution history of your workflows. Unlike agent or team sessions that store conversation messages, workflow sessions store complete workflow runs, where each run represents a full execution of all your workflow steps from input to final output.

Think of it this way:

• Agent/Team sessions = conversation history (messages back and forth)
• Workflow sessions = execution history (complete pipeline runs with results)

When to Use Workflow Sessions

Use workflow sessions when you need to:

• Track workflow execution history across multiple runs
• Share state between steps in a workflow (like passing data between pipeline stages)
• Enable workflows to learn from previous runs by accessing past inputs and outputs
• Persist workflow results for analysis and debugging
• Maintain context across multiple workflow executions

In most cases it is recommended to add session persistence to your workflow.

How Workflow Sessions Work

When you create a workflow with a database, Agno automatically manages sessions for you:

from agno.workflow import Workflow
from agno.db.sqlite import SqliteDb

workflow = Workflow(
    name="Research Pipeline",
    db=SqliteDb(db_file="workflows.db"),
    steps=[...],
)

# Each run creates or updates the workflow session
result = workflow.run(input="AI trends", session_id="session_123")

Each time you run the workflow, Agno:

1. Creates a unique run_id for this execution
2. Stores the input, output, and all step results
3. Updates the session with the new run
4. Makes the history available for future runs

Workflow Session Structure

A workflow session stores:

@dataclass
class WorkflowSession:
    session_id: str           # Unique session identifier
    user_id: str | None       # User who owns this session
    workflow_id: str | None   # Which workflow this belongs to
    workflow_name: str | None # Name of the workflow
    
    # List of all workflow runs (executions)
    runs: List[WorkflowRunOutput] | None
    
    # Session-specific data
    session_data: Dict | None    # Includes session_name, session_state
    workflow_data: Dict | None   # Workflow configuration
    metadata: Dict | None        # Custom metadata
    
    created_at: int | None    # Unix timestamp
    updated_at: int | None    # Unix timestamp

Unlike agent sessions, workflow sessions don’t have a summary field. Workflows store complete run results instead of creating summaries.

What Gets Stored

Each workflow run stores:

• Input: The data passed to workflow.run()
• Output: The final result from the workflow
• Step results: Output from each step in the pipeline
• Session Data: Execution time, status, metrics
• Session state: Shared data between steps (if used)

Key Differences from Agent/Team Sessions

If you’re familiar with agent or team sessions, here are the main differences:

Feature	Agent/Team Sessions	Workflow Sessions
What’s stored	Messages and conversation turns	Complete workflow runs with step results
History type	Message-based (chat history)	Run-based (execution history)
Summaries	Supported with enable_session_summaries	Not supported (stores complete runs)
History format	Messages in LLM context	Previous run results prepended to step inputs

Database Options

Workflow sessions require a database to persist execution history. Agno supports multiple database types:

from agno.db.sqlite import SqliteDb

# Quick start - SQLite
workflow = Workflow(
    name="Research Pipeline",
    db=SqliteDb(db_file="workflows.db"),
    steps=[...],
)

Database Configuration Guide

See all supported databases, connection options, and production recommendations

Workflow History

Workflow history lets workflow steps access results from previous runs. When enabled, Agno formats prior run results and prepends them to each step input so future executions can build on that context.

Enable history for your steps

from agno.workflow import Workflow
from agno.db.sqlite import SqliteDb

workflow = Workflow(
    name="Content Pipeline",
    db=SqliteDb(db_file="workflows.db"),
    steps=[...],
    add_workflow_history_to_steps=True,  # Include previous runs
    num_history_runs=5,                  # Limit how many runs to load
)

Why it helps:

• Access previous runs instead of repeating work
• Reference past decisions to keep outputs consistent
• Maintain context across multi-run workflows
• Build on prior results for richer analysis

History format

Agno wraps past runs in a structured XML block before inserting it into each step input:

<workflow_history_context>
[Workflow Run-1]
User input: Create a blog post about AI
Workflow output: [Full output from run]

[Workflow Run-2]
User input: Write about machine learning
Workflow output: [Full output from run]
</workflow_history_context>

See the workflow history implementation guide for advanced controls, per-step overrides, and programmatic access patterns.

Session Naming

Give your workflow sessions meaningful names for easier identification:

Manual Naming

from agno.workflow import Workflow
from agno.db.sqlite import SqliteDb

workflow = Workflow(
    name="Research Pipeline",
    db=SqliteDb(db_file="workflows.db"),
    steps=[...],
)

workflow.run(input="Analyze AI trends", session_id="session_123")
workflow.set_session_name(session_id="session_123", session_name="AI Trends Analysis Q4 2024")

# Retrieve the name
name = workflow.get_session_name(session_id="session_123")
print(name)  # "AI Trends Analysis Q4 2024"

Auto-Generation

Workflow sessions can auto-generate timestamp-based names:

workflow = Workflow(
    name="Research Pipeline",
    description="Automated research and analysis pipeline",
    db=SqliteDb(db_file="workflows.db"),
    steps=[...],
)

workflow.run(input="Research topic", session_id="session_123")
workflow.set_session_name(session_id="session_123", autogenerate=True)

name = workflow.get_session_name(session_id="session_123")
print(name)  # "Automated research and analysis pipel - 2024-11-19 14:30"

Next Steps

Now that you understand workflow sessions, explore these features:

Workflow History

Enable workflows to learn from previous runs

Session State

Share data between workflow steps across runs

Session Management

Manage session names, IDs, and organization

Conversational Workflows

Make workflows interactive with WorkflowAgent

Metrics

Track workflow performance and usage

Database Setup

Configure databases for session storage

Developer Resources

• View the Workflow schema
• View the WorkflowSession schema
• Browse workflow session examples