Sessions
Group related runs under a stable session ID, with database-backed history and state.
Before running the examples, create and activate a virtual environment:
uv pip install agno openai sqlalchemy
export OPENAI_API_KEY="your-api-key"Customer-facing agents use sessions to keep each conversation thread separate and continue it across requests. A stable session_id groups related runs, while user_id associates the thread with the person using your product.
from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIResponses
agent = Agent(
model=OpenAIResponses(id="gpt-5.4-mini"),
db=SqliteDb(db_file="tmp/support.db"),
add_history_to_context=True,
num_history_runs=3,
)
agent.print_response(
"My order number is ORD-123.",
user_id="customer-42",
session_id="support-thread-7",
)
agent.print_response(
"Which order are we discussing?",
user_id="customer-42",
session_id="support-thread-7",
)The database stores both runs under support-thread-7. On the second run, add_history_to_context=True loads messages from the same session into the model context.
IDs and Persistence
| Value | Purpose | Generation |
|---|---|---|
run_id | Identifies one execution | Agno generates a new value for every run unless you provide one |
session_id | Groups related runs into one thread | Agno generates one when the Agent instance first runs without a supplied value, then reuses it on that instance |
user_id | Associates a run and session with a user | Your application supplies it, or the agent uses its configured default |
An ID labels a run or thread. A configured database provides durable storage.
Persistence and Model Context
Session storage and chat history serve separate purposes:
| Configuration | Effect |
|---|---|
db=... | Persists session records, runs, state, and stored messages |
add_history_to_context=True | Adds messages from previous runs in the session to the next model request |
num_history_runs=N | Limits history by run count |
num_history_messages=N | Limits history by message count |
session_state={...} | Stores application state with the session |
add_history_to_context defaults to False. Configure it when the model needs conversational continuity. See Chat History for message selection and storage controls.
Multi-User Applications
Use IDs from your application instead of sharing one generated session across customers:
| Product concept | Agno value |
|---|---|
| Account or customer | user_id |
| Chat thread, ticket, or workspace conversation | session_id |
| One request and response cycle | run_id |
A user can have multiple session IDs, such as separate support tickets or chat tabs. Reuse a session ID only for runs that belong to the same thread.
Workflow Sessions
Agent and team sessions store conversational runs and messages. Workflow sessions track pipeline executions with their inputs, outputs, and state. See Workflow Sessions for workflow-specific behavior.