Persisting Sessions

Store session data in a database for multi-turn conversations

To enable sessions across multiple runs, you need to configure a database. Once configured, Agno automatically stores conversation history, session state, and run metadata. Paused runs persist their status and requirements so they can be continued later.

Database selection, connection strings, credentials management, and operational guidance live in the Database overview. Reuse that setup here—this page only adds the session-specific considerations.

Quick Start

Once you have a db object (Postgres, SQLite, DynamoDB, …) configured per the storage docs, persistence is enabled simply by passing it to your Agent, Team, or Workflow:

db = PostgresDb(db_url="postgresql+psycopg://...")

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,                 # Enables persistence
    session_id="user_123", # Same ID = same conversation
)

Supported Databases

Nothing new lives here—simply reuse the database drivers and guidance from /basics/storage:

• PostgreSQL (recommended) – Production-grade, supports custom session_table names for isolating workloads.
• SQLite – Great for local development; swap the file path just as you would elsewhere.
• InMemoryDb – Useful for tests or demos only. Data disappears when the process exits.

If you need to tune indexing, retention, or connection pools, do that in the shared storage layer so every feature (sessions, memories, knowledge, etc.) benefits from the same configuration.

Session IDs

Sessions are identified by session_id. Use the same ID to continue a conversation:

# First run
agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    session_id="conversation_123",
)
agent.run("My name is Alice")

# Later run with same session_id
agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
    session_id="conversation_123",  # Same ID
    add_history_to_context=True,     # Enable history
)
agent.run("What's my name?")  # Agent remembers "Alice"

Need custom naming conventions, caching, or UI-friendly labels? Continue with the Session Management guide.

What Gets Stored

When you configure a database, Agno automatically stores:

• ✅ Messages - User inputs and agent responses
• ✅ Run metadata - Timestamps, token usage, model info
• ✅ Session state - Custom key-value data
• ✅ Tool calls - Tool usage and results (optional)
• ✅ Media - Images, audio, files (optional)

See Storage Control to customize what gets saved.

Multi-User Sessions

Use user_id to track different users:

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=db,
)

# Specify the user_id and session_id on run to start or continue the conversation
agent.print_response("Hello!", session_id="session_456", user_id="[e-mail]")

Session Storage Schema

When you configure a database, Agno stores sessions in a structured format. Here’s what gets saved for each session:

Field	Type	Description
session_id	str	Unique identifier for this conversation thread
session_type	str	Type of session (agent, team, or workflow)
agent_id	str	The agent ID (if this is an agent session)
team_id	str	The team ID (if this is a team session)
workflow_id	str	The workflow ID (if this is a workflow session)
user_id	str	The user this session belongs to
session_data	dict	Session-specific data and state
agent_data	dict	Agent configuration and metadata
team_data	dict	Team configuration and metadata
workflow_data	dict	Workflow configuration and metadata
metadata	dict	Additional custom metadata
runs	list	All the runs (interactions) in this session
summary	dict	The session summary (if enabled)
created_at	int	Unix timestamp when session was created
updated_at	int	Unix timestamp of last update

Want to visualize your sessions? Check out the AgentOS UI sessions page for a beautiful interface to view and manage all your conversation threads.

Guides

Now that you have persistence configured, explore what you can do with sessions:

• Storage Control - Optimize what gets saved
• History Management - Control conversation history
• Session Summaries - Condense long conversations
• Session Management - Naming, caching, and more