State Management

Setup

Install the example dependencies and set the key for the OpenAI model:

pip install agno openai sqlalchemy
export OPENAI_API_KEY="your-api-key"

State is data that persists across multiple runs within a session, enabling agents, teams, and workflows to maintain context and remember information.

Common use cases include managing user-specific data like shopping lists, todo lists, preferences, or any information that needs to persist across interactions. State is managed through session_state, which can be accessed and updated in tools, then persisted when a configured database stores the completed run.

How State Works

State in Agno follows this pattern:

1. Initialize - Set default session_state when creating agents, teams, or workflows
2. Access - Tools access state via run_context.session_state
3. Update - Run completion stores modifications in the configured database
4. Load - Subsequent runs in the same session retrieve the stored state

Basic Example

Here's a simple agent that maintains a shopping list:

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.run import RunContext

def add_item(run_context: RunContext, item: str) -> str:
    """Add an item to the shopping list."""
    run_context.session_state["shopping_list"].append(item)
    return f"Added {item}"

agent = Agent(
    db=SqliteDb(db_file="tmp/state.db"),
    session_state={"shopping_list": []},  # Default state
    tools=[add_item],
    instructions="Shopping list: {shopping_list}",  # State in instructions
)

agent.print_response("Add milk and eggs")
print(agent.get_session_state())  # {'shopping_list': ['milk', 'eggs']}

Learn more

Developer Resources

• Agent schema
• Team schema
• Workflow schema
• RunContext schema