
How Workflow Session State Works
1. State Initialization
Initialize session state when creating a workflow. The session state can start empty or with predefined data that all workflow components can access and modify.2. Access and Modify State Data
All workflow components - agents, teams, and functions - can read from and write to the shared session state. This enables persistent data flow and coordination across the entire workflow execution. From tools, you can access the session state viarun_context.session_state.
Example: Shopping List Management
3. run_context as a parameter for custom python functions step in workflow
You can add the run_context parameter to the Python functions you use as custom steps.
The run_context object will be automatically injected when running the function.
You can use it to read and modify the session state, via run_context.session_state.
Example: a custom Python function step reading and writing workflow session state through
run_context.run_context parameter is also injected into the evaluator and selector functions of the Condition and Router steps:
Accepting a
session_state dict parameter directly in custom step functions, evaluators, and selectors is deprecated. Accept run_context: RunContext and use run_context.session_state instead.Key Benefits
Persistent State Management- Data persists across all workflow steps and components
- Enables complex, stateful workflows with memory
- Keeps shared state available throughout workflow execution
- Agents, teams, and functions share the same state object
- Enables sophisticated collaboration patterns
- Coordinates state across workflow execution
- Use any Python data structure (dictionaries, lists, objects)
- Structure data to match your workflow requirements
- Access and modify state through standard Python operations
The
run_context object, containing the session state, is automatically passed to all agents and teams within a
workflow. Components collaborate and share data without manual state management.Useful Links
Agent Examples
See how agents interact with shared session state
Team Examples
Learn how teams coordinate using shared state
