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

# Tasks

> Create, list, update, stop, and stream task executions.

The `Tasks` module manages the full lifecycle of task executions: the unit of work an agent does in response to a prompt. List existing tasks, load a specific one, create new ones, patch their state, or terminate them.

```python theme={"dark"}
from xpander_sdk import Tasks, AgentExecutionStatus

tasks = Tasks()

# List
items = await tasks.alist(agent_id="agent-123")

# Load
task = await tasks.aget(task_id="task_xyz")

# Create
task = await tasks.acreate(agent_id="agent-123", prompt="Hello!")

# Update
await tasks.aupdate(task_id=task.id, status=AgentExecutionStatus.Completed, result="done")

# Stop
await tasks.astop(task_id=task.id)
```

## Constructor

```python theme={"dark"}
Tasks(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/tasks/list)                                        | `list[TasksListItem]` | Tasks for a given agent, optionally filtered.                                       |
| [`alist_user_tasks` / `list_user_tasks`](/developers/sdk-reference/tasks/list#tasks-for-a-user) | `list[TasksListItem]` | Tasks for a given end-user across all agents.                                       |
| [`aget` / `get`](/developers/sdk-reference/tasks/get)                                           | `Task`                | Load a full task by id.                                                             |
| [`acreate` / `create`](/developers/sdk-reference/tasks/create)                                  | `Task`                | Create a new task. (Same as `Agent.acreate_task`, but accepts `agent_id` directly.) |
| [`aupdate` / `update`](/developers/sdk-reference/tasks/update)                                  | `Task`                | Patch task fields (status, result, payload extension).                              |
| [`astop` / `stop`](/developers/sdk-reference/tasks/stop)                                        | `Task`                | Terminate a running task.                                                           |

## `Task` instance methods

The `Task` object returned by these calls has its own set of methods for runtime control:

| Method                                                                                                                      | What it does                                              |
| --------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| [`asave` / `save`](/developers/sdk-reference/tasks/task#save)                                                               | Persist local mutations back to the platform.             |
| [`aset_status` / `set_status`](/developers/sdk-reference/tasks/task#set_status)                                             | Set status (and optionally result) and save in one call.  |
| [`astop` / `stop`](/developers/sdk-reference/tasks/task#stop)                                                               | Terminate this task.                                      |
| [`areload` / `reload`](/developers/sdk-reference/tasks/task#reload)                                                         | Re-fetch the latest task state from the platform.         |
| [`aevents` / `events`](/developers/sdk-reference/tasks/events)                                                              | Stream `TaskUpdateEvent`s via SSE.                        |
| [`aget_activity_log` / `get_activity_log`](/developers/sdk-reference/tasks/activity-log)                                    | Full message / tool-call / reasoning thread.              |
| [`areport_metrics` / `report_metrics`](/developers/sdk-reference/tasks/report-metrics)                                      | Push token counts and other metrics back to the platform. |
| [`get_files` / `get_images` / `get_human_readable_files` / `to_message`](/developers/sdk-reference/tasks/task#agno-helpers) | Convenience helpers for Agno integration.                 |

For the full attribute list, see the [`Task` class reference](/developers/sdk-reference/tasks/task).

## Lifecycle

```text theme={"dark"}
Pending  →  Executing  →  Completed
                ↓             ↓
              Paused        Failed
                ↓             ↓
              Error         Stopped
```

| Status      | Meaning                                                     |
| ----------- | ----------------------------------------------------------- |
| `Pending`   | Created but not yet picked up by a worker.                  |
| `Executing` | Worker is running the task.                                 |
| `Paused`    | Worker paused (HITL approval, deep-planning question).      |
| `Completed` | Finished successfully.                                      |
| `Error`     | Worker raised an exception.                                 |
| `Failed`    | Task didn't complete successfully (lower-level than Error). |
| `Stopped`   | Manually terminated.                                        |

The `AgentExecutionStatus` enum (used everywhere status appears) has these values: `Pending`, `Executing`, `Paused`, `Error`, `Failed`, `Completed`, `Stopped`. String values are lowercase.

## Class-level method

`Task.areport_external_task(...)` is a `@classmethod` that records an externally-executed run without going through `Backend`. It mirrors `Backend.areport_external_task` and exists for cases where you don't have a `Backend` instance handy. See [`report_external_task`](/developers/sdk-reference/tasks/report-external-task).