Agent orchestration is a hub-and-spoke way to handle a goal that is too broad for one agent. A central orchestrator plans the work, delegates subtasks to specialized worker agents, reviews their results, and decides what happens next. Workers carry out the assigned tasks and return their results to the hub. section 1.4.2 section 9.3
Think of a manager who assigns research and analysis rather than doing both jobs personally. The orchestrator makes strategic decisions; workers execute. Unlike a fixed agent flow, it can call only the workers it needs and change its plan when findings reveal a missing subtask. Unlike agent collaboration, workers generally communicate through the orchestrator rather than freely critiquing one another. section 9.3 section 1.6 section 4.1.1
A practical orchestration loop has four parts:
- Keep a global plan and state: record the goal, current focus, and completed work. section 9.3
- Delegate a specific subtask to a worker suited to it, such as a research or analysis agent. section 9.3
- Evaluate the returned result against the goal. Choose whether to delegate again, revise the plan, or finalize. section 9.3
- Set an iteration limit and inspect decisions and outputs so the loop does not run without a clear stopping point. section 9.3 section 9.5
Listing 9.7 08_orchestrator_loop.py (types and agent init)
class OrchestratorPlan(BaseModel):
"""The orchestrator's decomposition of a complex goal."""
sub_tasks: list[SubTopic] = Field(default_factory=list)
overall_strategy: str = ""
current_focus: str = ""
class OrchestratorDecision(BaseModel): #1
"""Output from the orchestrator after evaluating progress."""
next_action: str # "delegate" | "re_plan" | "finalize"
target_worker: str = "" # which worker to delegate to
task_description: str = ""
reasoning: str = ""
plan_updates: list[SubTopicUpdate] = []
is_complete: bool = False
research_worker = Agent( #2
name="Research Worker",
instructions="""You are a focused research worker.
You receive a specific research sub-task and execute it
thoroughly using your search tools. Return detailed findings
with sources. Do not deviate from the assigned sub-task.""",
model="gpt-5.1",
output_type=ResearchIteration,
)
analysis_worker = Agent( #3
name="Analysis Worker",
instructions="""You are a data analysis worker.
You receive findings and data to analyze. Identify patterns,
contradictions, and gaps. Return a structured analysis with
confidence assessments.""",
model="gpt-5.1",
output_type=ResearchIteration,
)
orchestrator_agent = Agent( #4
name="Research Orchestrator",
instructions="""
You are a research orchestrator managing a team of workers.
Your job is to decompose complex goals, delegate sub-tasks
to the right worker, evaluate their output, and decide
when the overall goal is satisfied.
Workers available:
- Research Worker: for searching and gathering information
- Analysis Worker: for analyzing and synthesizing findings
Each iteration, review the current state and plan, then decide:
1. "delegate" - assign a sub-task to a specific worker
2. "re_plan" - revise the plan based on new information
3. "finalize" - all sub-tasks complete, ready for synthesis
Always provide reasoning for your decision.
""",
model="gpt-5.1",
output_type=OrchestratorDecision,
)
The typed plan and decision models make the loop inspectable: a decision records its next action, target worker, task, plan updates, and completion status. section 9.3
Research and analysis
To compare residential solar and wind energy by environmental effect and cost effectiveness, give an orchestrator a research worker with a search tool and an analysis worker. Print each decision and the aggregated findings. If initial research exposes a gap, the orchestrator can add or reprioritize a subtask before producing the final result. section 9.5 section 9.3
Start with a simpler agent flow when tasks can run in a known order. Orchestration adds flexible decisions and can recover from worker failures, but it is harder to build, debug, and evaluate. Give it evaluation, feedback, and guardrails; improve instructions and structured outputs before adding architectural complexity. A delegated worker can also lose details that a previous flow preserved, so compare final outputs rather than assuming the new pattern is better. section 4.1.1 section 4.4.3
