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

# list

> Summary list of every agent your organization can access.

`Agents.alist` returns a list of summary objects (`AgentsListItem`) for every agent visible to the configured organization. Each item carries enough metadata for display (id, name, icon, status, instructions, access scope) and a `.aload()` shortcut to fetch the full `Agent`.

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

agents = Agents()
items = await agents.alist()

for item in items:
    print(f"{item.id}\t{item.status.value}\t{item.name}")
```

### Parameters

None.

### Returns `list[AgentsListItem]`

`AgentsListItem` is a lightweight summary: not the full `Agent`. Notable fields:

| Field             | Type                | Description                                              |
| ----------------- | ------------------- | -------------------------------------------------------- |
| `id`              | `str`               | Agent ID.                                                |
| `name`            | `str`               | Display name.                                            |
| `icon`            | `str`               | Emoji or icon identifier.                                |
| `instructions`    | `AgentInstructions` | `role`, `goal`, `general` text.                          |
| `status`          | `AgentStatus`       | `DRAFT`, `ACTIVE`, or `INACTIVE`.                        |
| `organization_id` | `str`               | Owning organization.                                     |
| `created_at`      | `datetime`          | Creation timestamp.                                      |
| `description`     | `str \| None`       | Agent description.                                       |
| `access_scope`    | `AgentAccessScope`  | `Personal` or `Organizational`.                          |
| `created_by`      | `str \| None`       | Creator user id.                                         |
| `type`            | `AgentType \| None` | `Manager`, `Regular`, `A2A`, `Curl`, or `Orchestration`. |

To load the full agent (graph, tools, model config, …) call `.aload()` on the item, or pass `item.id` to `agents.aget()`.

## Examples

### Filter active agents

```python theme={"dark"}
items = await agents.alist()
active = [i for i in items if i.status.value == "ACTIVE"]
```

### Load all in parallel

```python theme={"dark"}
import asyncio

items = await agents.alist()
full = await asyncio.gather(*(item.aload() for item in items))
```

For a large org this can be heavy: prefer loading only the agents you'll actually use.

### Sync version

```python theme={"dark"}
items = agents.list()
```

Same return type; blocks until the list is fetched.

## Errors

`alist` raises [`ModuleException`](/developers/sdk-reference/error-handling) on failure:

| Status | Cause                            |
| ------ | -------------------------------- |
| 401    | Missing or invalid `api_key`.    |
| 403    | Wrong `organization_id`.         |
| 500    | Server error or network failure. |