> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2.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 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

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

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:

```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](https://agno-v2.mintlify.site/reference/agents/session.md) and [TeamSession reference](https://agno-v2.mintlify.site/reference/teams/session.md) 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()`:

```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 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.

```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"),
    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
from agno.db.sqlite import SqliteDb

team = Team(
    model=OpenAIResponses(id="gpt-5.2"),
    members=[...],
    db=SqliteDb(db_file="tmp/team.db"),
    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

> [!WARNING]
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.