Skip to main content
A task is a goal you hand to Autumn. It gets its own sandbox and agent, plans an approach, works the web, and writes output rows. It keeps running in the cloud after your request returns.
1

You send a prompt or task spec

A goal in plain language, or a structured spec carrying a schema, rules, and input rows.
2

Autumn writes a plan

The agent turns the goal into task.json — the approach it intends to take, before it spends anything.
3

A sandbox and agent start

The task gets its own container and workspace, and both persist across turns.
4

You read events, files, and output rows

Progress streams while the task runs; finished rows land in the task’s output.
Every task has a durable task_id. That id is the handle for everything else: status, streaming, continuation, files, and output.

One task

Store the returned task_id. It stays valid after the run finishes.

Two start modes

Start from a prompt with /task, or from a task.json-style spec with /task/start.

One planning flag

clarify: false plans without asking. clarify: true allows one blocking question.

​
Two ways to start

Choose /task/start for enrichment jobs with known inputs, workflows your own app generates, repeatable research with a fixed output schema, or a task restored from a saved spec. Choose /task when you only have a user request. Use GET /task/metaprompt when another agent or app needs to generate a clean task.json-style spec before calling /task/start.

​
Planning and clarify

clarify is the only planning knob. Left at its default of false, the agent plans, infers defaults, and executes without stopping. Set to true, it may ask one blocking question before execution. Use clarify: true only when a caller is present and a wrong assumption would cost more than a short question. Human in the loop covers both modes and the review-then-continue pattern.

​
Turns

A task runs one turn at a time. Starting a task is a turn; so is continuing it. A turn ends with a done event, and the task returns to rest. The task itself is not finished in any final sense. You can continue it later, and it picks up the same plan, rows, and task-local files. This is why continuing beats starting over: a new task loses the plan and the rows.
Because a task runs one turn at a time, continuing or executing while a turn is still in flight is rejected with 409, not queued. See Errors.

​
Next

Task lifecycle

The states a task moves through, and how to tell when it is done.

Outputs and sources

What a task produces, and how every value carries its source.