Xagent Docs
Get started

Running Tasks

A task is one run of an agent against a goal. Use a runtime key (scoped to a single agent) to create and track tasks.

App API alternative

This guide uses the versioned Workspace SDK (POST /v1/chat/tasks), the recommended surface for integrations. The web app also exposes POST /api/chat/task/create (JWT auth, a broader/less stable contract) — see the Chat / Tasks API.

Create a Task

Send the agent id and the first user message. The server validates that the request's agent_id matches the agent bound to your runtime key, and that message.content is non-empty.

Request:

POST /v1/chat/tasks
{
  "agent_id": 42,
  "message": { "role": "user", "content": "Summarize the EV battery market." },
  "metadata": { "request_id": "req_0c1d", "source": "sdk" }
}

Response (202 Accepted):

{
  "task_id": 101,
  "agent_id": 42,
  "status": "running",
  "created_at": "2026-06-23T12:00:00Z",
  "run_id": "run_9f2c1a",
  "state_version": 1,
  "control_state": "running"
}

The task is created and queued for background execution. task_id is an integer; poll the endpoints below to watch it move from running to completed or failed.

Track Progress

Fetch task details and the step-by-step plan as the agent works:

GET /v1/chat/tasks/{task_id}          # task info & status
GET /v1/chat/tasks/{task_id}/steps    # planned/executed steps

A task moves through its lifecycle from running to a terminal state (completed or failed). Steps reflect the Plan → Execute → Reflect loop.

Retrieve Output & Files

When a task finishes, collect its output and any generated files. In the full app these are available via the chat task endpoints:

GET /api/chat/task/{task_id}
GET /api/chat/task/{task_id}/status
GET /api/chat/workspace/{task_id}/files
GET /api/chat/workspace/{task_id}/output

Tip

Pass metadata on task creation to correlate runs with your own systems — request ids, user references, or campaign tags.

Next Steps