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

# get

> Load a single agent by ID, with full configuration and tools.

`Agents.aget` loads one agent's complete configuration: instructions, model settings, the execution graph, all attached tools, knowledge-base links, and framework settings. Use this whenever you need to actually invoke an agent or inspect its config in code.

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

agents = Agents()
agent = await agents.aget("agent-123")
print(agent.name, agent.model_provider, agent.model_name)
```

### Parameters

| Parameter  | Type  | Required | Default                                       | Description                          |
| ---------- | ----- | -------- | --------------------------------------------- | ------------------------------------ |
| `agent_id` | `str` | No¹      | `Configuration.agent_id` → `XPANDER_AGENT_ID` | Agent to load.                       |
| `version`  | `int` | No       | `None`                                        | Specific version. Latest if omitted. |

¹ The method falls back to `Configuration.agent_id` and then `XPANDER_AGENT_ID`. If none of those are set, you'll hit a 404 from the cloud.

### Returns `Agent`

A full `Agent` instance. See [`Agent` class reference](/developers/sdk-reference/agents/agent) for attributes (instructions, framework, graph, deployment\_type, tools, knowledge\_bases, agno\_settings, etc.).

## Examples

### Latest version

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

### Pinned version

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

The version corresponds to deployment snapshots in the Workbench. Pin a version in production to avoid surprises when someone edits the agent.

### Use a default agent ID

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

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

This is the pattern used inside `@on_task` handlers: you don't usually pass an agent ID explicitly because the runtime injects it.

### Sync version

```python theme={"dark"}
agent = agents.get("agent-123")
```

Same parameters; blocks until the agent is loaded.

## What gets loaded

When you call `aget`, the SDK:

1. Fetches the agent record (`GET /agents/:id`).
2. Builds the `AgentGraph` from the graph items returned in the response.
3. Initializes a `ToolsRepository` populated with the agent's tools.
4. If any local tools (Python `@register_tool` functions) need syncing to the platform's graph, kicks off a background `sync_local_tools` task: non-blocking.

You can read `agent.graph` to inspect the tool/connector wiring, `agent.tools.list` for all tools, `agent.knowledge_bases` for KB links, and `agent.mcp_servers` for the configured MCP servers.

## Errors

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

| Status | Cause                                              |
| ------ | -------------------------------------------------- |
| 404    | Agent not found, or wrong organization.            |
| 403    | Agent exists but isn't accessible to your account. |
| 500    | Server error or network failure.                   |