> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> Inspect and manage user sessions stored against the agent's database.

Agents using the Agno framework with `agno_settings.session_storage = True` persist their session history to a Postgres database managed by the platform. The SDK exposes that database via `Agent.aget_db()` plus a small set of helpers for session CRUD.

<Note>
  Sessions are only available for Agno agents with session storage enabled. Calling these methods on other agents raises `NotImplementedError` (wrong framework) or `LookupError` (storage disabled). The Agno extras must be installed: `pip install xpander-sdk[agno]`.
</Note>

## `aget_db`

Returns the Agno Postgres client backing the agent's session storage.

```python theme={"dark"}
db = await agent.aget_db()                  # async client (AsyncPostgresDb)
db_sync = await agent.aget_db(async_db=False)  # sync client (PostgresDb)
```

### Parameters

| Parameter  | Type   | Default | Description                                                |
| ---------- | ------ | ------- | ---------------------------------------------------------- |
| `async_db` | `bool` | `True`  | When `False`, returns the synchronous `PostgresDb` client. |

### Returns

`agno.db.postgres.AsyncPostgresDb` (or `PostgresDb` if `async_db=False`). The client is namespaced to the agent's schema, so different agents don't share a session table.

The connection URI is fetched (and cached) via `agent.aget_connection_string()` on the first call.

### Sync version

```python theme={"dark"}
db = agent.get_db()                # equivalent to aget_db(async_db=False)
```

## `aget_user_sessions`

Load all sessions for a given end-user.

```python theme={"dark"}
sessions = await agent.aget_user_sessions(user_id="user_42")
for s in sessions:
    print(s.session_id, s.created_at)
```

### Parameters

| Parameter | Type  | Required | Description                                                          |
| --------- | ----- | -------- | -------------------------------------------------------------------- |
| `user_id` | `str` | Yes      | End-user identifier (matches `user_details.id` from `acreate_task`). |

### Returns

A list of session records. The exact type comes from Agno's `db.get_sessions(...)`: fields include `session_id`, `user_id`, `agent_id` (or `team_id` for Team mode), and timestamps. The query caps results at 50 sessions per call.

For Team agents (`agent.is_a_team == True`), this returns `SessionType.TEAM` records; otherwise `SessionType.AGENT`.

### Sync version

```python theme={"dark"}
sessions = agent.get_user_sessions(user_id="user_42")
```

## `aget_session`

Load a single session by ID.

```python theme={"dark"}
session = await agent.aget_session(session_id="sess_456")
```

### Parameters

| Parameter    | Type  | Required | Description         |
| ------------ | ----- | -------- | ------------------- |
| `session_id` | `str` | Yes      | Session identifier. |

### Returns

The session record, or `None` if it doesn't exist.

### Sync version

```python theme={"dark"}
session = agent.get_session(session_id="sess_456")
```

## `adelete_session`

Delete a session.

```python theme={"dark"}
await agent.adelete_session(session_id="sess_456")
```

### Parameters

| Parameter    | Type  | Required | Description        |
| ------------ | ----- | -------- | ------------------ |
| `session_id` | `str` | Yes      | Session to delete. |

### Sync version

```python theme={"dark"}
agent.delete_session(session_id="sess_456")
```

## Errors

All session methods raise:

* `NotImplementedError`: agent isn't using Agno.
* `LookupError`: Agno is configured but `agno_settings.session_storage` is `False`.
* `ImportError`: Agno extras not installed (run `pip install xpander-sdk[agno]`).
* `ValueError`: connection URI couldn't be resolved.

## Patterns

### Inspect recent sessions for a user

```python theme={"dark"}
sessions = await agent.aget_user_sessions(user_id="user_42")

for s in sorted(sessions, key=lambda x: x.created_at, reverse=True)[:5]:
    print(f"{s.session_id}: {s.created_at}")
```

### Wipe all sessions for a user

```python theme={"dark"}
sessions = await agent.aget_user_sessions(user_id="user_42")
for s in sessions:
    await agent.adelete_session(session_id=s.session_id)
```

`aget_user_sessions` returns at most 50 records per call, so loop until empty for users with many sessions.

### Drop into the Agno DB directly

```python theme={"dark"}
db = await agent.aget_db()

# Now use any AsyncPostgresDb method: read messages, custom queries, etc.
session = await db.get_session(session_id="sess_456", session_type=...)
```

Use this when the four convenience methods don't cover what you need; the Agno DB client has a richer API.