> ## 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.

# Orchestration Overview

> Submit tasks to agent fleets that plan, execute, and stream results.

Orchestration lets you describe a goal in plain language and have Hexel plan and execute it across a group of agents. Instead of writing the control loop yourself (deciding which agent handles what, sequencing steps, retrying failures), you submit a task and the platform does the coordination. Use orchestration when work spans multiple agents or steps, such as triaging a batch of support tickets, running a multi-stage research pipeline, or processing documents with human approval gates.

You submit a task to a fleet; the platform plans it, executes it across the fleet's agents, gates it with approvals when needed, and streams progress you can follow and replay.

## Capabilities

<CardGroup cols={2}>
  <Card title="Tasks" icon="list-check" href="/docs/orchestration/tasks">
    Submit work and track it through its lifecycle.
  </Card>

  <Card title="Fleets" icon="layer-group" href="/docs/orchestration/fleets">
    Group agents and configure how they run.
  </Card>

  <Card title="Routing & Modes" icon="route" href="/docs/orchestration/routing-and-modes">
    Control capacity, deployment, and routing.
  </Card>

  <Card title="Approvals" icon="user-check" href="/docs/orchestration/approvals">
    Require human or policy approval before execution.
  </Card>

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

## How it works

```
Submit task → Plan → (approval gate) → Execute across fleet → Stream events → Record & replay
```

A task is scoped to a fleet, workspace, and environment. The platform plans the work, optionally pauses for approval, executes across the fleet, and records everything for auditing and replay.

## Access

Through the Python and TypeScript SDKs (`client.orchestrator.*`) or the REST API.

```python theme={"dark"}
from hexel import Hexel

client = Hexel(api_key="YOUR_API_KEY")

task = client.orchestrator.task.create(
    fleet_id="YOUR_FLEET_ID",
    environment_id="YOUR_ENVIRONMENT_ID",
    workspace_id="YOUR_WORKSPACE_ID",
    input="Triage new support tickets",
)
```

## Rate limits

| Scope            | Limit                 |
| ---------------- | --------------------- |
| Per organization | 100 requests / minute |

## Pagination

List endpoints accept `page` (starting at 1) and `page_size` (1–100, default 20).

## Errors

Orchestration endpoints return standard HTTP status codes with a JSON body describing the problem.

| HTTP  | When                                                                                                                |
| ----- | ------------------------------------------------------------------------------------------------------------------- |
| `400` | Invalid request — a required field is missing or malformed (e.g. `fleet_id required`).                              |
| `403` | Not permitted, or the organization lacks the required entitlement (e.g. `compute entitlement required`).            |
| `404` | The task, fleet, approval, or policy doesn't exist.                                                                 |
| `429` | Rate limit exceeded. The response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `Retry-After` headers. |

<Tip>
  The SDKs retry `429` automatically with exponential backoff and surface the `Retry-After` value.
</Tip>

## Security

| Concern        | How it's handled                                                                                                  |
| -------------- | ----------------------------------------------------------------------------------------------------------------- |
| Authentication | Every request uses a short-lived Bearer token.                                                                    |
| Authorization  | Operations require RBAC permissions (for example, fleet management requires fleet write/read/delete permissions). |
| Scoping        | Tasks, fleets, approvals, and policies are scoped to your organization, workspace, and environment.               |
| Entitlement    | Submitting a task requires an active compute entitlement.                                                         |

## Next steps

Start with [Tasks](/docs/orchestration/tasks) to submit and track your first task.