Orchestration

An orchestrator coordinates multiple subagents to manage complex multi-step workflows.

After you configure an agent as an orchestrator by adding subagents, it becomes a coordination layer that plans tasks, delegates work to subagents, and integrates their outputs. The orchestrator does not execute tools directly. Instead, it focuses on strategy, task routing, and combining results.

Architecture

The orchestrator works as a supervisory layer that coordinates multiple agents. It does not call tools directly.

Instead, it manages the workflow by doing the following:

Interpreting the end user's goal.
Identifying which agents are required.
Delegating tasks to those agents.
Collecting and integrating their results.

Benefits

Modular architecture: Agents are specialized and can be maintained independently.
Scalable execution: Tasks can run in parallel.
Robustness: Failures are isolated with retry/fallback mechanisms.
Clear division of responsibilities: Orchestrator manages planning, agents manage execution.
Extensibility: New agents or tools can be added easily.

Example orchestrator prompt

javascript

1Workflow Example: Quarterly Sales Report

3 1. Understand end user intent.

4 - Identify that the request involves data extraction, analysis, visualization, and summary generation.

5 2. Break down into subtasks:

6 - Data Extraction → retrieve and prepare sales data

7 - Analysis → compute key metrics (totals, growth rates, etc.)

8 - Visualization → generate charts and graphs

9 - Summary Generation → write a textual executive summary

10 3. Delegate each subtask:

11 - Assign to the most suitable AI agent based on its capabilities

12 - Provide each agent with clear, structured instructions and required inputs

13 4. Monitor and validate responses:

14 - Check if each agent output meets the required format and quality

15 - Retry or reassign if an agent fails or produces incomplete output

16 5. Integrate results:

17 - Combine data, charts, and summary text into a unified final report

18 6. Deliver the final output to the end user in a clear and formatted structure

20 Behavioral Guidelines:

21 - Always focus on planning and coordination, not execution

22 - Use consistent task naming and clear communication between agents

23 - Ensure all outputs are validated before integration

24 - Manage partial failures gracefully: retry or reroute when needed

25 - Maintain transparency in the workflow (log which agent performed which subtask)

27 Example End User Request:

28 "Generate a Q2 sales performance report with visualizations and an executive summary."

30 Expected Orchestrator Behavior:

31 - Break down → Delegate → Monitor → Integrate → Deliver

For information about when to use orchestration, see Plan your agent.

To build components that subagents can use as tools, see Component design.

Subagent versioning

When an orchestrator agent references subagents, each subagent has its own independent version lifecycle. Publishing the orchestrator creates an immutable snapshot that pins the exact version of each subagent.

How it works [#how-it-works-subagent-versioning]

A draft orchestrator can reference any version (draft or released) of a subagent.
When you create a released version of the orchestrator:
- Subagents that are still in draft are automatically published to a new released version and pinned into the orchestrator's release.
- Subagents that are already released are pinned as-is. No unnecessary version bumps occur.
If any subagents are still in draft, the system shows a confirmation dialog listing them before proceeding.
A released orchestrator is not affected by any future changes to its subagents. The pinned versions remain frozen.

Runtime version resolution [#runtime-version-resolution-subagent-versioning]

When an orchestrator invokes a subagent at runtime, it uses the pinned version from its manifest, not whatever version of the subagent is currently active.

The active version of a subagent controls which version handles direct traffic to that subagent (for example, when a user interacts with the subagent standalone). It does not affect how parent agents resolve their dependencies.

Example: An orchestrator (V1) pins Refund Handler V2. Even if Refund Handler V3 is active, the orchestrator continues to use V2. To use V3, update the orchestrator's draft to reference V3, then create a new released version.

Rollback [#rollback-subagent-versioning]

Because each released version of the orchestrator is an immutable snapshot of pinned subagent versions, you can roll back the orchestrator to a previous version to instantly restore the previous subagent configuration. For more information, see Version history.