> ## Documentation Index
> Fetch the complete documentation index at: https://hexelstudio.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tasks & Workflows

> How a goal becomes a planned, executed, and auditable workflow.

A task is a goal you submit to a fleet. The platform plans the goal into a workflow, executes it across the fleet's agents, streams progress, and records the result for auditing and replay.

## Key concepts

| Term         | Meaning                                                              |
| ------------ | -------------------------------------------------------------------- |
| **Task**     | A goal submitted to a fleet via `client.orchestrator.task.create()`. |
| **Plan**     | The workflow generated from the goal.                                |
| **Workflow** | The execution of the plan across agents.                             |
| **Replay**   | A recorded trace for auditing and re-running.                        |

## Task lifecycle

<img src="https://mintcdn.com/hexelstudio-2127951d/utVkRjxsT1DGYlO5/assets/diagrams/tasks-and-workflows.png?fit=max&auto=format&n=utVkRjxsT1DGYlO5&q=85&s=929d6932161b6cfa2d89dd73773ebbd4" alt="Task and workflow lifecycle" width="1693" height="929" data-path="assets/diagrams/tasks-and-workflows.png" />

| State         | Meaning                                                               |
| ------------- | --------------------------------------------------------------------- |
| `pending`     | Accepted; awaiting dispatch. Does not plan automatically on creation. |
| `planning`    | Plan is being generated.                                              |
| `plan_review` | Awaiting approval before execution.                                   |
| `executing`   | Workflow is running.                                                  |
| `completed`   | Finished successfully (terminal).                                     |
| `failed`      | Error during execution (terminal).                                    |
| `cancelled`   | Cancelled by user, policy rejection, or expiry (terminal).            |

## SubmitTaskRequest fields

| Field            | Required | Type   | Description                                  |
| ---------------- | -------- | ------ | -------------------------------------------- |
| `fleet_id`       | Yes      | string | Fleet to execute the task.                   |
| `environment_id` | Yes      | string | Environment scope.                           |
| `workspace_id`   | Yes      | string | Workspace scope.                             |
| `input`          | Yes      | string | The work to perform (natural language).      |
| `context`        | No       | string | Structured context as a JSON-encoded string. |

## SDK operations

```python theme={"dark"}
# Submit
task = client.orchestrator.task.create(
    fleet_id="YOUR_FLEET_ID",
    environment_id="YOUR_ENVIRONMENT_ID",
    workspace_id="YOUR_WORKSPACE_ID",
    input="Summarize this week's support tickets",
)

# Track
client.orchestrator.task.list()
client.orchestrator.task.get(task["id"])

# Control
client.orchestrator.task.cancel(task["id"])
client.orchestrator.task.replay(task["id"])

# Stream
for event in client.orchestrator.task.stream(task["id"]):
    print(event)
```

## Related pages

<CardGroup cols={2}>
  <Card title="Orchestration → Tasks" icon="list-check" href="/docs/orchestration/tasks">
    Submit, track, and manage tasks.
  </Card>

  <Card title="Approvals" icon="user-check" href="/docs/orchestration/approvals">
    Gate execution with human approval.
  </Card>

  <Card title="Streaming & Replay" icon="play" href="/docs/orchestration/streaming-and-replay">
    Follow and reproduce task execution.
  </Card>

  <Card title="Fleets" icon="layer-group" href="/docs/concepts/fleets">
    The agents a task runs across.
  </Card>
</CardGroup>

## Next steps

Continue to [Tools](/docs/concepts/tools).