> ## 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

> List, load, and interact with agents stored in the xpander.ai platform.

The `Agents` module is your gateway to agents stored on the platform. Use it to discover what agents exist, load a specific one, and from there create tasks, invoke tools, attach knowledge bases, and inspect sessions.

```python theme={"dark"}
from xpander_sdk import Agents

agents = Agents()
all_agents = await agents.alist()
agent = await agents.aget("agent-123")
task = await agent.acreate_task(prompt="Hello!")
```

## Constructor

```python theme={"dark"}
Agents(configuration: Optional[Configuration] = None)
```

| Parameter       | Type            | Default | Description                                |
| --------------- | --------------- | ------- | ------------------------------------------ |
| `configuration` | `Configuration` | `None`  | SDK configuration. Falls back to env vars. |

## Module methods

| Method                                                    | Returns                | What it does                                     |
| --------------------------------------------------------- | ---------------------- | ------------------------------------------------ |
| [`alist` / `list`](/developers/sdk-reference/agents/list) | `list[AgentsListItem]` | Summary list of every agent your org can access. |
| [`aget` / `get`](/developers/sdk-reference/agents/get)    | `Agent`                | Load one agent fully (config + graph + tools).   |

## `Agent` instance methods

Once you've loaded an `Agent`, use its instance methods for the actual work:

| Method                                                                                                         | What it does                                                                        |
| -------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| [`acreate_task` / `create_task`](/developers/sdk-reference/agents/create-task)                                 | Create a new task and run it.                                                       |
| [`ainvoke_tool` / `invoke_tool`](/developers/sdk-reference/agents/invoke-tool)                                 | Invoke a single tool bound to this agent.                                           |
| [`aget_knowledge_bases` / `get_knowledge_bases`](/developers/sdk-reference/agents/knowledge-bases)             | Load all knowledge bases attached to the agent.                                     |
| [`attach_knowledge_base`](/developers/sdk-reference/agents/knowledge-bases#attach_knowledge_base)              | Link a knowledge base to the agent (in-memory only).                                |
| [`knowledge_bases_retriever`](/developers/sdk-reference/agents/knowledge-bases#knowledge_bases_retriever)      | Returns a `search(query, num_documents)` callable for use as a framework retriever. |
| [`aget_db` / `get_db`](/developers/sdk-reference/agents/sessions)                                              | Returns the Agno PG client backing the agent's session storage.                     |
| [`aget_user_sessions` / `get_user_sessions`](/developers/sdk-reference/agents/sessions)                        | All sessions for a given end-user.                                                  |
| [`aget_session` / `get_session`](/developers/sdk-reference/agents/sessions)                                    | Load a single session.                                                              |
| [`adelete_session` / `delete_session`](/developers/sdk-reference/agents/sessions)                              | Delete a session.                                                                   |
| [`aget_streaming_spec` / `get_streaming_spec`](/developers/sdk-reference/agents/agent#streaming-spec)          | Get the deployed agent's streaming URL + auth key.                                  |
| [`aget_connection_string` / `get_connection_string`](/developers/sdk-reference/agents/agent#connection-string) | Get the agent's DB connection details.                                              |

See the [`Agent` class reference](/developers/sdk-reference/agents/agent) for attribute documentation.

## Quick patterns

### Find and load

```python theme={"dark"}
all_agents = await agents.alist()
for item in all_agents:
    print(item.id, item.name, item.status)

agent = await all_agents[0].aload()           # AgentsListItem.aload returns the full Agent
# equivalent to: await agents.aget(all_agents[0].id)
```

### Pin to a specific version

```python theme={"dark"}
agent = await agents.aget("agent-123", version=4)
```

Versioning is opt-in. Without `version`, you get the latest.

### Default agent via env var

```bash theme={"dark"}
export XPANDER_AGENT_ID="agent-123"
```

```python theme={"dark"}
agent = await agents.aget()   # uses XPANDER_AGENT_ID
```

This works because `Agents.aget()` falls back to `Configuration.agent_id` and then to `XPANDER_AGENT_ID`.