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

<CodeGroup>
  ```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")
  ```
</CodeGroup>

## Access to Messages & Chat History

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

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

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:

<CodeGroup>
  ```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")
  ```
</CodeGroup>

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

<CodeGroup>
  ```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")
  ```
</CodeGroup>

**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:

<CodeGroup>
  ```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"
  ```
</CodeGroup>

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.

<CodeGroup>
  ```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")
  ```
</CodeGroup>

### 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.
</Warning>