Session Management

Before running the examples, create and activate a virtual environment:

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

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

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")

The access and naming fragments below continue the session created in the matching Agent or Team tab. An arbitrary ID can return no session; handle that result before reading its messages.

Access to Messages & Chat History

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

session = agent.get_session(session_id="user_123_session_456")
messages = session.get_messages() if session else []

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:

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

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():

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

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:

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

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.

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"),
    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