# How Orchestra works

With Orchestra on, the model you chat with becomes the orchestrator: it plans the work and hands each part to an agent, on any provider you set up.

*Where in Studio: Composer → Orchestra*

*Last updated: 2026-10-25*

Turn on **Orchestra** in the composer and the model you chat with becomes the orchestrator. It breaks your request into steps, hands each step to an agent, reads what the agents report and answers you in the chat. Each agent runs on the model its role names, so one run can use models from several providers at once.

## The parts of a run

| Part | What it is |
| --- | --- |
| Orchestrator | The chat's own model. It plans, starts agents, answers their questions and writes the reply you read. It hands reading, editing and testing to its agents instead of doing that work itself. |
| Agents | Workers the orchestrator starts, one task each. They run side by side and report a result: a summary, findings, changed files, the checks they ran and anything that blocked them. |
| Roles | What an agent can be: **Research**, **Code Implementation**, **UI Design**, **Code Review**, **Security Review**, **Git Commit**, **Plan Advisor**, plus profiles you add. You turn roles on in **Settings → Subagents**. |
| Plan | The steps the orchestrator declares for the run, shown in the **Plan** card and the composer's plan panel. |

## An example

You ask for a retry queue for failed webhooks in `payments-api`. The orchestrator, on Fable 5.1 in Claude Code, declares a plan and starts agents for it:

| Agent | Job | Model and agent |
| --- | --- | --- |
| Map webhook failure modes | Research | Grok 4.7 in Grok |
| Retry queue with idempotency keys | Implementation | SWE-2 in Devin |
| Integration tests for retries | Tests | GPT-5.6 in Codex |
| Check billing dashboard in the browser | Browser checks | Sonnet 5 in Claude Code |

While they work, the agent map lists each one as running, finished or waiting on you. When they are done, the orchestrator reviews the results and replies in the chat.

## What to expect

- **Agents work in the chat's checkout**, on the same computer as the chat: this Mac, or the server the chat runs on. Writers may run at the same time in the same checkout.
- **Access is per role.** Each role has an execution mode: **Read only**, **Workspace write** or **Full access**. The agent's record shows the one it ran with.
- **Agents ask the orchestrator, not you.** A question from an agent goes to the orchestrator, which answers it. Only when the orchestrator needs you does it ask in the chat, and the agent shows under **Needs you**.
- **You talk to the orchestrator.** You cannot message or stop a single agent. Send a message in the chat to change course, or press Stop to end the turn; Stop also cancels the agents that turn started.
- **One level.** Agents cannot start agents of their own.
- **Orchestra stays on for the chat** until you turn it off, and cannot be switched while the chat is running.

## Next

[Start an Orchestra](https://kelrova.com/docs/studio/orchestra/start), then [mix providers and accounts](https://kelrova.com/docs/studio/orchestra/providers).

## Related

- [Start an Orchestra](https://kelrova.com/docs/studio/orchestra/start)
- [Mix providers and accounts](https://kelrova.com/docs/studio/orchestra/providers)
- [The agent map and records](https://kelrova.com/docs/studio/orchestra/agent-map)
- [Limits and usage](https://kelrova.com/docs/studio/orchestra/limits)