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.
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.
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
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 | list[TasksListItem] | Tasks for a given agent, optionally filtered. |
alist_user_tasks / list_user_tasks | list[TasksListItem] | Tasks for a given end-user across all agents. |
aget / get | Task | Load a full task by id. |
acreate / create | Task | Create a new task. (Same as Agent.acreate_task, but accepts agent_id directly.) |
aupdate / update | Task | Patch task fields (status, result, payload extension). |
astop / 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 | Persist local mutations back to the platform. |
aset_status / set_status | Set status (and optionally result) and save in one call. |
astop / stop | Terminate this task. |
areload / reload | Re-fetch the latest task state from the platform. |
aevents / events | Stream TaskUpdateEvents via SSE. |
aget_activity_log / get_activity_log | Full message / tool-call / reasoning thread. |
areport_metrics / report_metrics | Push token counts and other metrics back to the platform. |
get_files / get_images / get_human_readable_files / to_message | Convenience helpers for Agno integration. |
Task class reference.
Lifecycle
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. |
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.
