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

# Backend

> The Backend module bridges your code and a stored agent configuration.

The `Backend` module is the bridge between your code and an agent stored in the xpander.ai platform. It does three things:

1. **Resolves runtime arguments** for your AI framework: `aget_args(agent_id=...)` returns kwargs you can spread directly into Agno (or another supported framework's) agent constructor.
2. **Invokes agents directly**: `ainvoke_agent(agent_id=..., prompt=...)` is shorthand for "load the agent, create a task." Useful when you don't need framework-level control.
3. **Reports externally executed runs**: `areport_external_task(...)` lets you log a run that happened outside the platform (e.g. in a queue worker or another runtime) so it shows up in the same task history and metrics as platform-managed runs.

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

backend = Backend()
```

## Constructor

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

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

When called without arguments, the module reads `XPANDER_API_KEY`, `XPANDER_ORGANIZATION_ID`, and `XPANDER_BASE_URL` from the environment.

## Methods

| Method                                                                                                     | What it does                                                                                                  |
| ---------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| [`ainvoke_agent` / `invoke_agent`](/developers/sdk-reference/backend/invoke-agent)                         | Load an agent and create a task in one call. Returns a `Task`.                                                |
| [`aget_args` / `get_args`](/developers/sdk-reference/backend/get-args)                                     | Resolve framework-specific kwargs (model, system prompt, tools, memory, …) from a stored agent configuration. |
| [`areport_external_task` / `report_external_task`](/developers/sdk-reference/backend/report-external-task) | Record an external execution (run outside the platform) so it appears in task history.                        |

## Typical pattern

```python theme={"dark"}
from xpander_sdk import Backend, on_task
from xpander_sdk.modules.tasks.sub_modules.task import Task
from agno.agent import Agent as AgnoAgent

backend = Backend()

@on_task
async def handler(task: Task) -> Task:
    args = await backend.aget_args(
        agent_id=task.agent_id,
        agent_version=task.agent_version,
        task=task,
    )
    agno_agent = AgnoAgent(**args)
    result = await agno_agent.arun(input=task.to_message())
    task.result = result.content
    return task
```

`@on_task` listens for incoming task events from the platform; the handler resolves framework args for the *current* task, builds an Agno agent, runs it, and stores the result on the task. The platform records status, metrics, and tool calls automatically.

## Environment variable shortcut

Set `XPANDER_AGENT_ID` and you can omit `agent_id` from every Backend call:

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

```python theme={"dark"}
backend = Backend()
args = await backend.aget_args()                     # uses XPANDER_AGENT_ID
task = await backend.ainvoke_agent(prompt="Hello")   # same
```

Explicit arguments always override the env var.