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

# create

> Create a new task for an agent.

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

```python theme={"dark"}
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`](/developers/sdk-reference/agents/create-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.              |

See [`Agent.acreate_task`](/developers/sdk-reference/agents/create-task) for parameter details and examples.

### Returns `Task`

The created task. Starts in `Pending`. See [`Task`](/developers/sdk-reference/tasks/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).                                  |

Both produce identical results; pick the one that matches what you have on hand.

## Sync version

```python theme={"dark"}
task = tasks.create(agent_id="agent-123", prompt="Hello!")
```

## Errors

Raises [`ModuleException`](/developers/sdk-reference/error-handling). 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.                                                     |