Session management controls how sessions are identified, named, read, and cached.
Session IDs
Every session has a unique identifier (session_id) that tracks conversations across multiple runs:
- Auto-generated: If not provided, Agno generates a UUID automatically
- Manual: You can provide your own session IDs for custom tracking
- Per-user: Combine with
user_id to track multiple users’ sessions
Access to Messages & Chat History
You can access the messages in a session using the get_messages method:
By default, get_messages() skips paused, cancelled, and error runs plus messages already tagged as history. Agent sessions also skip regenerated runs. Team sessions skip member messages. Pass skip_statuses=[], skip_history_messages=False, and, for teams, skip_member_messages=False to include those records.
For a simpler list of only user and assistant messages, you can use the get_chat_history method:
See the detailed AgentSession reference and TeamSession reference for more information.
Session Naming
Session names are human-readable labels that make it easier to identify and manage conversations. Use them for inbox-style UIs, support queues, or linking a conversation back to an external ticket.
Manual Naming
Set custom names using set_session_name():
Tips:
- Treat the session ID as the source of truth; names are just metadata for humans
- Rename conversations whenever the topic shifts. There’s no limit on how often you call the method
- Need guardrails or naming policies? Wrap
set_session_name in your own helper before exposing it to end-users
Auto-generated Names
Let the AI generate meaningful names from conversation content:
Calling set_session_name(autogenerate=True) asks the model to read the messages in the session and generate a short (5 words max) label. The method returns the updated session object. Use get_session_name() to retrieve the generated name.
Best Practices:
- Delay generation until the conversation has meaningful context (e.g., after 2–3 messages)
- Provide a fallback: wrap the call in your own helper that falls back to a human-entered name or a ticket ID if the generation fails
- Batch jobs: loop over session IDs from your database and call
set_session_name(..., autogenerate=True) once for each. Use aset_session_name in async code
- Costs: Each generation is an extra call to the agent’s or team’s model. Run it out-of-band if you’re cost sensitive
Session Caching
Session caching stores the session object in memory to improve performance. cache_session=True keeps the hydrated session object in memory after the first database read, avoiding extra queries for subsequent runs.
When It Helps
- Many sequential turns in the same session (support chats, copilots, etc.)
- Latency-sensitive deployments where every DB round trip matters
- Resource-heavy databases (remote Postgres, serverless drivers) where connection setup dominates
The cache belongs to one Agent or Team instance. Other workers and processes do not share it, and external session updates are not visible through the cached object. Use cache_session only when one long-lived instance owns the session. Leave it disabled for horizontally scaled or shared-session deployments.
