Kern

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
Tip

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, Kern automatically manages sessions for you:

1from kern.workflow import Workflow
2from kern.db.sqlite import SqliteDb
3
4workflow = Workflow(
5    name="Research Pipeline",
6    db=SqliteDb(db_file="workflows.db"),
7    steps=[...],
8)
9
10# Each run creates or updates the workflow session
11result = workflow.run(input="AI trends", session_id="session_123")

Each time you run the workflow, Kern:

  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:

1@dataclass
2class WorkflowSession:
3    session_id: str           # Unique session identifier
4    user_id: str | None       # User who owns this session
5    workflow_id: str | None   # Which workflow this belongs to
6    workflow_name: str | None # Name of the workflow
7    
8    # List of all workflow runs (executions)
9    runs: List[WorkflowRunOutput] | None
10    
11    # Session-specific data
12    session_data: Dict | None    # Includes session_name, session_state
13    workflow_data: Dict | None   # Workflow configuration
14    metadata: Dict | None        # Custom metadata
15    
16    created_at: int | None    # Unix timestamp
17    updated_at: int | None    # Unix timestamp
Note

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:

FeatureAgent/Team SessionsWorkflow Sessions
What's storedMessages and conversation turnsComplete workflow runs with step results
History typeMessage-based (chat history)Run-based (execution history)
SummariesSupported with enable_session_summariesNot supported (stores complete runs)
History formatMessages in LLM contextPrevious run results prepended to step inputs

Database Options

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

1from kern.db.sqlite import SqliteDb
2
3# Quick start - SQLite
4workflow = Workflow(
5    name="Research Pipeline",
6    db=SqliteDb(db_file="workflows.db"),
7    steps=[...],
8)
database

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, Kern formats prior run results and prepends them to each step input so future executions can build on that context.

Enable history for your steps

1from kern.workflow import Workflow
2from kern.db.sqlite import SqliteDb
3
4workflow = Workflow(
5    name="Content Pipeline",
6    db=SqliteDb(db_file="workflows.db"),
7    steps=[...],
8    add_workflow_history_to_steps=True,  # Include previous runs
9    num_history_runs=5,                  # Limit how many runs to load
10)
✓

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

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

1<workflow_history_context>
2[Workflow Run-1]
3User input: Create a blog post about AI
4Workflow output: [Full output from run]
5
6[Workflow Run-2]
7User input: Write about machine learning
8Workflow output: [Full output from run]
9</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

1from kern.workflow import Workflow
2from kern.db.sqlite import SqliteDb
3
4workflow = Workflow(
5    name="Research Pipeline",
6    db=SqliteDb(db_file="workflows.db"),
7    steps=[...],
8)
9
10workflow.run(input="Analyze AI trends", session_id="session_123")
11workflow.set_session_name(session_id="session_123", session_name="AI Trends Analysis Q4 2024")
12
13# Retrieve the name
14name = workflow.get_session_name(session_id="session_123")
15print(name)  # "AI Trends Analysis Q4 2024"

Auto-Generation

Workflow sessions can auto-generate timestamp-based names:

1workflow = Workflow(
2    name="Research Pipeline",
3    description="Automated research and analysis pipeline",
4    db=SqliteDb(db_file="workflows.db"),
5    steps=[...],
6)
7
8workflow.run(input="Research topic", session_id="session_123")
9workflow.set_session_name(session_id="session_123", autogenerate=True)
10
11name = workflow.get_session_name(session_id="session_123")
12print(name)  # "Automated research and analysis pipel - 2024-11-19 14:30"

Next Steps

Now that you understand workflow sessions, explore these features:

clock-rotate-left

Workflow History

Enable workflows to learn from previous runs

database

Session State

Share data between workflow steps across runs

tag

Session Management

Manage session names, IDs, and organization

comments

Conversational Workflows

Make workflows interactive with WorkflowAgent

chart-line

Metrics

Track workflow performance and usage

database

Database Setup

Configure databases for session storage

Developer Resources