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.
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.
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].
aget_db
Returns the Agno Postgres client backing the agent’s session storage.
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
db = agent.get_db() # equivalent to aget_db(async_db=False)
aget_user_sessions
Load all sessions for a given end-user.
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
sessions = agent.get_user_sessions(user_id="user_42")
aget_session
Load a single session by ID.
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
session = agent.get_session(session_id="sess_456")
adelete_session
Delete a session.
await agent.adelete_session(session_id="sess_456")
Parameters
| Parameter | Type | Required | Description |
|---|
session_id | str | Yes | Session to delete. |
Sync version
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
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
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
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=...)
