Tasks and runs
Create a task, follow its events live, steer it, answer its questions, pause, resume, retry or cancel it, and understand what the harness keeps.
On this page
A task gives an agent a goal. It keeps going until it is done: it survives restarts, waits for people when it needs them and stops at its budget. Each attempt at a task, and each sub-agent it starts, is a run.
Create a task
hexel harness task create "Audit the api repo" --agent auditor@prod \
--input repo=acme/api --budget-usd 5 --follow| Field | Description |
|---|---|
goal | What the agent should do. Up to 64 KiB. |
agent | name (its prod channel), name@channel or name@v<n>. |
inputs | Optional JSON object, up to 256 KiB. The agent receives it with the goal. |
budget | Optional limits: see Budgets and estimates. |
sandbox_template | Optional. The sandbox template for the task's computer. |
after, inputs_from, checkin | Optional. See Task chains. |
A task belongs to the person who created it, in the workspace and environment of the request. Members see and act on their own tasks; Admins and Owners (harness:task:admin) on everyone's.
States
| State | Meaning |
|---|---|
queued | Admitted and waiting for the runtime to start it. |
running | The agent is working. |
waiting | The agent waits; waiting_reason says on what (below). |
paused | Paused by a person. A paused task holds no capacity. |
succeeded | Done. Its outputs hold the result. |
failed | Ended without success; end_reason says why. |
budget_exhausted | Stopped at its budget. Resume it with a new budget. |
cancelled | Cancelled by a person. |
waiting_reason | The task waits for |
|---|---|
question | An answer to the agent's question. |
approval | A Titan approval of one of its actions (Approvals and autonomy). |
dependency | The tasks it starts after (Task chains). |
parked | An answer, for more than an hour (below). |
fork_worker | A runtime that can start a forked run. |
Parking. A run that has waited an hour for an answer, with nothing in flight, is parked: it holds no runtime capacity and shows waiting_reason: parked. An answer or a steer wakes it, and it continues where it was. With nothing arriving, it is looked at again after 6 hours and parked again if it still waits. A parked task can be paused or cancelled.
Follow a task
A task's events stream as Server-Sent Events: first the stored events, then live ones until the task ends, then an end event.
hexel harness tail -f tsk_123 # follow until it ends
hexel harness tail tsk_123 --only message,tool # only some event types
hexel harness tail tsk_123 --after 120 # pick up after event 120curl -N https://api.hexelstudio.com/v1/harness/tasks/tsk_123/events \
-H "Authorization: Bearer $ACCESS_TOKEN" \
-H "X-Workspace-Id: $WORKSPACE_ID" -H "X-Environment-Id: $ENVIRONMENT_ID"- Each SSE event's
event:is its type anddata:the event envelope. Events lists every type. - To resume after a dropped connection, send
Last-Event-IDor?after=<event id>. The SDKs do this for you. ?types=filters by type,?run=narrows a task's stream to one run, and?follow=falsereturns the history and stops.GET /harness/runs/{id}/eventsstreams one run.
Steer a task and answer it
hexel harness steer tsk_123 "Skip the vendored code" # read at the agent's next step
hexel harness steer tsk_123 "Stop and summarise now" --now # interrupts what it is doing
hexel harness answer call_456 "api and web" # answer a question
hexel harness answer call_456 --decline # decline to answerThe agent asks with ask_user; the question arrives as a question.asked event and in GET /harness/tasks/{id}. Through the API, steer with POST /harness/tasks/{id}/messages {"text": "...", "mode": "queue" | "now"} and answer with POST /harness/questions/{id}/answer {"answer": "..."} (null declines). A finished task takes no steer or answer.
Control a task
| Command | API | What it does |
|---|---|---|
hexel harness task pause | POST /tasks/{id}/pause | The agent stops after its current step. |
hexel harness task resume | POST /tasks/{id}/resume | Continue a paused task, or one out of budget with a new budget (--budget-usd). |
hexel harness task retry | POST /tasks/{id}/retry | Start a failed, cancelled or out-of-budget task again. |
hexel harness task cancel | POST /tasks/{id}/cancel | Cancel it. |
hexel harness task delete | DELETE /tasks/{id} | Delete it and everything under it; its running agent is stopped. See Data retention. |
Resume and retry are admitted like a new task: they are checked against your plan, balance and limits.
Runs
hexel harness task runs tsk_123 # attempts and sub-agents
hexel harness run get run_789 # one run, with what Titan knows of its sessionA retry starts a new attempt, a new root run. A sub-agent the agent starts is a child run with its own events. GET /harness/runs/{id} includes the run's Titan governance state: its Titan session and lifecycle.
Content and history
The harness's control plane stores metadata: ids, states, costs, sizes and keyed digests (hmac-sha256:...). The content of an event (message text, tool arguments and results, questions and answers) stays in the runtime that ran the task.
- Live. An open stream receives the content as it happens, in
event.contentchunks that carry no id and are not stored. The SDKs and the CLI join them for you. At most 1 MiB is relayed per event. - History. Events read back later (
?after=,Last-Event-ID,?follow=false) carry metadata only: each content field is replaced by its digest and size. - Task fields. A task's
outputsshow{digest, size}. Once a task has succeeded, itsgoalandinputsare emptied and their digests stay; a failed or cancelled task keeps them so that it can be retried. - Commands. Steers, answers and decision reasons lose their content once applied or once the task ends.
Follow a task while it runs if you need its content, or have the agent export what matters as an artifact.