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.acreate creates a new task. It’s equivalent to Agent.acreate_task but accepts agent_id directly, so you don’t need to load the Agent first. Use this when you only have an agent ID and want to skip the extra round-trip.
from xpander_sdk import Tasks
tasks = Tasks()
task = await tasks.acreate(
agent_id="agent-123",
prompt="Summarize the latest sales report",
file_urls=["https://example.com/sales.csv"],
)
print(task.id, task.status.value)
Parameters
Identical to Agent.acreate_task, with agent_id required up front:
| Parameter | Type | Required | Default | Description |
|---|
agent_id | str | Yes | – | Agent to invoke. |
existing_task_id | str | No | None | Continue an existing task. |
prompt | str | No | "" | Natural-language input. |
file_urls | list[str] | No | [] | URLs of files to attach. |
user_details | User | No | None | End-user context. |
agent_version | str | No | None | Pin a specific agent version. |
tool_call_payload_extension | dict | No | None | Extra fields merged into every tool-call payload. |
source | str | No | None | Origin tag. |
worker_id | str | No | None | Pin to a specific worker. |
run_locally | bool | No | False | Mark as locally executed. |
output_format | OutputFormat | No | None | Output format. |
output_schema | dict | No | None | JSON schema. |
events_streaming | bool | No | False | Enables task.aevents(). |
additional_context | str | No | None | Extra context appended to system prompt. |
instructions_override | str | No | None | Extra instructions for this run. |
test_run_node_id | str | No | None | (Internal) Test workflow node. |
user_oidc_token | str | No | None | OIDC token for connector pre-auth. |
expected_output | str | No | None | Expected output description. |
mcp_servers | list[MCPServerDetails] | No | [] | Per-task MCP servers. |
triggering_agent_id | str | No | None | Triggering agent ID. |
title | str | No | None | Display title. |
think_mode | ThinkMode | No | Default | Default or Harder. |
disable_attachment_injection | bool | No | False | Skip auto-injection of human-readable file content. |
return_metrics | bool | No | False | Return metrics (Workflow → Agent only). |
user_tokens | dict | No | None | Pre-computed user tokens for MCP auth. |
Agent.acreate_task for parameter details and examples.
Returns Task
The created task. Starts in Pending. See Task.
When to use this vs. Agent.acreate_task
| Use | When |
|---|
Tasks().acreate(agent_id=..., ...) | You only have an agent_id (e.g. from a webhook or env var). One fewer round-trip than loading the agent first. |
Agent.acreate_task(...) | You already have the loaded Agent (e.g. inspecting its tools or graph first). |
Sync version
task = tasks.create(agent_id="agent-123", prompt="Hello!")
Errors
Raises ModuleException. Common statuses:
| Status | Cause |
|---|
| 400 | Invalid input (bad output schema, malformed mcp_servers, etc.). |
| 401 / 403 | Auth failure. |
| 404 | Agent doesn’t exist. |
| 500 | Server error. |
