Session Management

Manage session identifiers, names, and performance optimization

Session management in Agno gives you control over how sessions are identified, named, and cached for optimal performance.

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

Agent

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    db=SqliteDb(db_file="tmp/agent.db"),
)

# Use your own session ID
agent.run("Hello", session_id="user_123_session_456")

Access to Messages & Chat History

You can access the messages in a session using the get_messages method:

Agent

session = agent.get_session(session_id="session_123")
messages = session.get_messages()

This gives you all messages for all runs in the session, including tool calls and system messages.

For a simpler list of only user and assistant messages, you can use the get_chat_history method:

Agent

messages = agent.get_chat_history(session_id="session_123")

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—perfect for inbox-style UIs, support queues, or linking a conversation back to an external ticket.

Manual Naming

Set custom names using set_session_name():

Agent

agent.set_session_name(session_id="session_001", session_name="Product Launch Planning")
name = agent.get_session_name(session_id="session_001")

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:

Agent

session = agent.set_session_name(
    session_id="session_123",
    autogenerate=True,
)
# Access the generated name
name = agent.get_session_name(session_id="session_123")
print(name)  # e.g. "E-commerce API Planning"

Calling set_session_name(autogenerate=True) asks the model to read the first few messages in the session and generate a short (≤5 words) 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. The API is synchronous, so plan around model latency
• Costs: Each generation is an extra model call. Use cheaper models via session_summary_manager or 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.

Agent

from agno.agent import Agent
from agno.models.openai import OpenAIResponses

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    session_id="my_session",
    cache_session=True,  # Enable in-memory caching
)

# First run loads from database and caches
agent.run("First message")

# Subsequent runs use cached session (faster)
agent.run("Second message")

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

This is only for development and testing purposes. It is not recommended for production use.