> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-agui.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# 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. Runs can pause for human-in-the-loop requirements and continue after those requirements are resolved.
## 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
```python Agent theme={null}
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")
```
```python Team theme={null}
from agno.team import Team
from agno.models.openai import OpenAIResponses
from agno.db.sqlite import SqliteDb
team = Team(
model=OpenAIResponses(id="gpt-5.2"),
members=[...],
db=SqliteDb(db_file="tmp/team.db"),
)
# Use your own session ID
team.run("Hello", session_id="user_123_session_789")
```
## Access to Messages & Chat History
You can access the messages in a session using the `get_messages` method:
```python Agent theme={null}
session = agent.get_session(session_id="session_123")
messages = session.get_messages()
```
```python Team theme={null}
session = team.get_session(session_id="session_456")
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:
```python Agent theme={null}
messages = agent.get_chat_history(session_id="session_123")
```
```python Team theme={null}
messages = team.get_chat_history(session_id="session_456")
```
See the detailed [AgentSession reference](/reference/agents/session) and [TeamSession reference](/reference/teams/session) 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()`:
```python Agent theme={null}
agent.set_session_name(session_id="session_001", session_name="Product Launch Planning")
name = agent.get_session_name(session_id="session_001")
```
```python Team theme={null}
team.set_session_name(session_id="session_001", session_name="Product Launch Planning")
name = team.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:
```python Agent theme={null}
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"
```
```python Team theme={null}
session = team.set_session_name(
session_id="session_456",
autogenerate=True,
)
# Access the generated name
name = team.get_session_name(session_id="session_456")
print(name) # e.g. "Product Launch Strategy"
```
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.
```python Agent theme={null}
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")
```
```python Team theme={null}
from agno.team import Team
from agno.models.openai import OpenAIResponses
team = Team(
model=OpenAIResponses(id="gpt-5.2"),
session_id="team_session",
cache_session=True, # Enable in-memory caching
)
# First run loads from database and caches
team.run("First message")
# Subsequent runs use cached session (faster)
team.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.