# Agent

The built-in agent.

The built-in agent.

## startAgentTask

`POST /v1/agent/tasks`

Give the built-in agent a task on one or more devices

Request body: `application/json` (`AgentTaskRequest`).

| Field | Type | What it is |
|---|---|---|
| `instruction` | string |  |
| `deviceIds` | array of string |  |
| `model` | string | Provider/model id, such as "anthropic:claude-sonnet-5" or "local:ui-tars". |
| `maxSteps` | integer |  |
| `budgetUsd` | number |  |
| `policyProfile` | string |  |

| Response | Means |
|---|---|
| 202 | Task started. `AgentTask` |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

MCP tools on this operation: [`run_agent_task`](/reference/mcp/run-agent-task/).

## getAgentTask

`GET /v1/agent/tasks/{taskId}`

Task status, steps and cost so far

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `taskId` | path | yes | string |  |

| Response | Means |
|---|---|
| 200 | Task. `AgentTask` |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

MCP tools on this operation: [`get_agent_task`](/reference/mcp/get-agent-task/).

## cancelAgentTask

`DELETE /v1/agent/tasks/{taskId}`

Stop the task

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `taskId` | path | yes | string |  |

| Response | Means |
|---|---|
| 204 | Stopped. |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

## steerAgentTask

`POST /v1/agent/tasks/{taskId}/messages`

Add guidance to a running task

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `taskId` | path | yes | string |  |

Request body: `application/json`.

| Field | Type | What it is |
|---|---|---|
| `text` | string |  |

| Response | Means |
|---|---|
| 202 | Queued for the next step. |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

## takeOver

`POST /v1/agent/tasks/{taskId}/takeover`

Pause the agent at the next step boundary and give input to the person

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `taskId` | path | yes | string |  |

| Response | Means |
|---|---|
| 200 | The person has control. `AgentTask` |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |

## handBack

`POST /v1/agent/tasks/{taskId}/handback`

Return control to the agent with an optional note

| Parameter | In | Required | Type | What it is |
|---|---|---|---|---|
| `taskId` | path | yes | string |  |

Request body: `application/json`.

| Field | Type | What it is |
|---|---|---|
| `note` | string |  |

| Response | Means |
|---|---|
| 200 | The agent resumed. `AgentTask` |
| 4XX | Error (RFC 9457). |
| 5XX | Error (RFC 9457). |