Chapter 9: Orchestrating multi-agent systems

Introduction

The introduction explains why growing task complexity motivates specialist agents and shows that the multi-agent system builds on the book’s existing Agent foundation.

• Motivation for specialist agents: Explain why assigning more roles to one agent can hurt performance and why the chapter proposes collaborating specialist agents instead.
  Why it matters: This is the reason for moving beyond the single-agent system built so far.
• Existing agent foundation: Describe how the proposed specialist agents relate to the Agent and supporting components already built in the book.
  Why it matters: Specialization does not require replacing the agent architecture already built.

Key terms: single agent, system prompts, tools, multi-agent system, specialized role, Agent class, tool system, ExecutionContext, system prompt, run() method

9.1 Why multi-agent?

This section explains why dividing a complex task among specialist agents can be more effective than giving one agent every role, instruction, and tool.

• Single-agent context overload: Explain why packing research, coding, writing, and review into one agent can make it less effective.
  Why it matters: This is the problem the section uses to motivate multiple agents.
• Specialist agent roles: Describe how the blog-writing assistant is divided into specialist agents and why each receives role-specific instructions and tools.
  Why it matters: The specialist-team example shows the section’s proposed way to reduce role confusion.
• Reusable and extensible specialists: Explain how specialist agents support reuse across systems and expansion when a new role is needed.
  Why it matters: Specialist agents can remain useful as projects change or grow.

Key terms: system prompt, tools, context window, multi-agent systems, Researcher, Coder, Writer, Reviewer, specialization, reusability

9.2 Three collaboration patterns

This section distinguishes three multi-agent collaboration patterns by who chooses the next agent, how context and control are handled, and when each pattern fits.

• Agent selection and context: Explain the two questions used to distinguish collaboration patterns: who decides the next agent and whether agents share context or work in isolation.
  Why it matters: These two questions make the differences between the patterns easier to reason about.
• Pattern selection by task: Apply the section’s rule of thumb to choose Workflow for known steps, Agent as Tool for a coordinator delegating to specialists, or Transfer when one specialist should take over.
  Why it matters: The choice determines whether a pipeline, a coordinator, or a specialist directs the work.
• Developer defined Workflow flow: Describe how Workflow fixes agent execution in code while leaving the developer free to share or isolate context and to compose sequential, parallel, or looping flows.
  Why it matters: A predefined flow can still vary in how agents exchange information and how stages are arranged.
• Isolated Agent as Tool calls: Explain how a main agent calls specialist agents as tools while retaining control and receiving only their results from separate contexts.
  Why it matters: This pattern lets a coordinator use specialist work without exposing every intermediate step or giving up control.
• LLM directed agent Transfer: Describe how Transfer lets an LLM route a request to a suitable registered agent and hands that agent control to complete the task.
  Why it matters: Routing a request to the right expert changes who is responsible for completing it.
• Combining collaboration patterns: Explain that a system can combine Workflow, Agent as Tool, and Transfer rather than choosing one for every part of the system.
  Why it matters: Different stages of one system can benefit from different ways of coordinating agents.

Key terms: execution order, context, sharing, isolation, Workflow, Agent as Tool, Transfer, orchestrator, execution flow, parallel execution

9.3 Agent workflow: Defining order in code

This section defines developer-controlled agent workflows, distinguishes three ways to order agents, and explains why workflows are a predictable starting point for multi-agent collaboration.

• Developer-defined agent execution order: Explain that in the Workflow pattern, the developer specifies the agents’ execution order in code rather than letting the LLM choose the next step, and why this makes the flow predictable and easy to debug.
  Why it matters: This distinction explains what the developer, rather than the LLM, controls in a workflow.
• Sequential parallel and loop patterns: Distinguish Sequential, Parallel, and Loop workflows by how agents run and the kinds of tasks each suits.
  Why it matters: The three patterns offer different ways to coordinate agents according to whether a task needs stages, independent work, or revision.

Key terms: Workflow pattern, execution order, LLM-driven routing, Sequential, Parallel, Loop, context

9.3.1 Workflow design principles

This section explains how giving workflows the same interface as agents makes multi-agent workflows composable.

• Composable workflow interface: Explain why a simple loop of agent calls limits composition and how workflows that inherit from Agent and implement run() can be nested and used wherever an agent is expected. Illustrate this with the researcher, parallel perspective agents, and editor.
  Why it matters: A common interface lets you build larger workflows from smaller ones without changing how callers invoke them.

Key terms: Agent, run(), ParallelWorkflow, SequentialWorkflow, composable

9.3.2 Sequential: Step-by-step execution

This section explains how a sequential workflow runs agents in order while carrying context from one agent to the next.

• Sequential context handoff: Trace how a sequential workflow runs agents in order: the first receives user_input and context, each later agent receives the preceding result’s context, and the last result becomes the workflow result.
  Why it matters: This handoff lets each agent build on earlier work without duplicating the original input.
• Between-agent termination reset: Explain why final_result and current_step are reset before each agent executes in a sequential workflow.
  Why it matters: Each agent needs to begin its execution without inheriting the prior agent’s stopping state.

Key terms: Sequential workflow, user_input, context, result.context, final_result, current_step, termination state

9.3.3 Parallel: Concurrent execution

This section explains when to run independent agents in parallel and how to merge their events and results into one context and output.

• Independent parallel analyses: Explain that a Parallel workflow gives independent agents the same input so they can analyze different perspectives concurrently, then synthesizes their results.
  Why it matters: This helps you recognize tasks that benefit from parallel agents rather than a single line of analysis.
• Parallel event and result merging: Trace how the run() method executes agents concurrently and combines their events without duplicating the user message or prior context. Describe how it keeps results attributable to their agents.
  Why it matters: Correct merging keeps a shared context readable without losing earlier work or confusing one agent’s result with another’s.

Key terms: Parallel workflow, independent, concurrently, asyncio.gather(), existing_event_count, seen_user_event, event.author, [agent_name]

9.3.4 Loop: Iterative execution

Explains when to use a Loop workflow and how it repeatedly runs agents, carries context forward, and stops.

• Iterative refinement use cases: Explain when a Loop workflow is useful: output can improve through repeated work and review, and a condition can indicate when to stop.
  Why it matters: It helps you decide whether repetition will improve a task rather than merely repeat it.
• Agent execution and context flow: Trace how a Loop runs agents within iterations and passes the initial input and subsequent context.
  Why it matters: Context carried between executions lets later passes work from earlier results rather than start over.
• Stop condition and iteration limit: Describe how a Loop decides to terminate and why it also has a maximum iteration count.
  Why it matters: A checkable stopping rule and a limit make iterative work both purposeful and bounded.

Key terms: Loop workflow, iterative refinement, user_input, context, iteration, is_first_agent, stop_condition, max_iterations, quality_reached

9.3.5 Composing workflows

This section explains how agent workflows can be nested into one pipeline while retaining a common interface, shared context, and a developer-defined execution flow.

• Composable workflow interface: Explain why SequentialWorkflow, ParallelWorkflow, and LoopWorkflow can be nested and used wherever an agent is expected. Describe the section’s example of combining research, parallel analysis, a write/review loop, and final editing.
  Why it matters: A common agent interface lets you combine workflow patterns without changing how the resulting pipeline is called.
• Context across pipeline stages: Describe how context behaves across a composed workflow and what that lets later stages do.
  Why it matters: Later stages can build on earlier results even when workflow patterns are nested.
• Developer-defined execution flow: Explain why a composed agent workflow has a predictable flow and is easier to debug.
  Why it matters: A fixed, visible flow makes it easier to locate where a pipeline went wrong.

Key terms: SequentialWorkflow, ParallelWorkflow, LoopWorkflow, Agent, run(), composability, Context, pipeline, stage, execution flow

9.4 Agent as Tool: Calling agents as tools

This section contrasts fixed workflows with request-dependent specialist selection and introduces calling specialist agents as tools.

• Fixed versus dynamic routing: Explain why a fixed Workflow sequence is useful when the order is known, but may not fit requests that need different specialists.
  Why it matters: It clarifies when a fixed sequence is helpful and when it would run specialists a request does not need.
• Specialist agents as tools: Explain how registering agents as tools lets an LLM choose which specialist to call for a request.
  Why it matters: It is the section’s proposed way to route requests to specialists without prescribing the same sequence every time.

Key terms: Workflow pattern, dynamic routing, specialists, agents as tools, LLM, specialist

9.4.1 Making agents into tools

This section explains that an agent can be presented to an LLM through the same interface as any other tool.

• Agent as Tool interface: Explain why an LLM can call another agent as a tool: it sees a name, description, parameters, and a returned result, just as it does for a function-based tool.
  Why it matters: It lets an orchestrator use specialized agents alongside regular tools.

Key terms: Agent as Tool, tool, name, description, parameters, result

9.4.2 Implementing AgentTool

This section explains how AgentTool wraps a specialist agent as a tool, handles its input, and keeps its execution context separate from the parent agent’s.

• AgentTool adapter and delegation: Explain how AgentTool lets a parent agent delegate a subtask to a child agent through the existing tool interface.
  Why it matters: This explains how specialist agents fit into the tool system the parent already uses.
• AgentTool input handling: Describe the default request input and how an optional input_schema changes the tool definition and execution input.
  Why it matters: The schema option gives the parent more precise ways to specify a subtask without changing what the child receives.
• Child agent context isolation: Explain why receiving the parent’s context in execute does not mean the child agent runs in that context.
  Why it matters: It clarifies what information actually crosses the boundary when one agent calls another.

Key terms: AgentTool, BaseTool, parent agent, orchestrator, child agent, request, input_schema, Pydantic, JSON schema, tool parameters

9.4.3 Context isolation

This section contrasts shared workflow context with isolated Agent as Tool context and explains the benefits and tradeoffs of that isolation.

• Shared versus isolated context: Distinguish how Sequential Workflow and Agent as Tool share context. Describe what earlier agents and the orchestrator can see in each pattern.
  Why it matters: The context-sharing difference determines how much of one agent’s work another agent can see.
• Benefits of child isolation: Explain how isolating a child agent provides abstraction, context efficiency, and independence for the orchestrator.
  Why it matters: Isolation lets the orchestrator use a result without carrying the child’s entire work history.
• Isolation tradeoffs and workflow choice: Describe the debugging cost of child-agent isolation and when a workflow is more suitable.
  Why it matters: The benefit of hiding internal work comes with a visibility cost and may not fit tasks that need shared intermediate state.

Key terms: Sequential Workflow, Agent as Tool, context, orchestrator, child agents, Abstraction, Context efficiency, Independence, parent context, context window

9.4.4 Practical example: Researcher and coder collaboration

A researcher-and-coder example shows an orchestrator using specialist agents as tools to answer a request that needs both research and code.

• Researcher and coder orchestration: Describe how the orchestrator delegates the framework research to a web-search-equipped researcher and the comparison script to a code-executing coder, then combines their results. State that both specialists are wrapped with AgentTool to make them available as tools.
  Why it matters: The example makes the division of work in Agent as Tool concrete.

Key terms: orchestrator, researcher, coder, AgentTool, web search, code-execution capability

9.5 Agent Transfer pattern

Introduces agent transfer by contrasting its handoff of control with the Agent as Tool pattern.

• Control in agent collaboration: Distinguish Agent as Tool from Transfer by explaining who controls the interaction and what happens to the conversation when control changes.
  Why it matters: The distinction tells you whether a specialist is returning a result to the original agent or taking over the response.

Key terms: Agent as Tool, Transfer pattern, orchestrator, control

9.5.1 Differences between Agent as Tool and Transfer

This section contrasts Agent as Tool and Transfer in control, context sharing, and who continues the conversation.

• Agent collaboration pattern differences: Distinguish Agent as Tool from Transfer by explaining who controls the interaction, what context the other agent receives, and which agent handles follow-up questions.
  Why it matters: The distinction determines whether another agent merely helps behind the scenes or takes over the conversation.

Key terms: Agent as Tool, Transfer, control, context sharing, conversation continuity

9.5.2 Transfer is also a tool

This section presents agent transfer as a tool call that reuses the existing tool system to hand control to a specialist agent.

• Transfer as a tool call: Explain that an agent hands control to a specialist by calling transfer_to_agent, and why this approach reuses the existing tool system.
  Why it matters: It connects agent handoffs to the tool-calling system you already use.

Key terms: Transfer pattern, transfer_to_agent, tool system

9.5.3 Agent tree

This section explains how an agent tree represents transfer relationships, determines allowed targets, and lets a transfer tool find an agent by name.

• Transfer flow and state: Trace how a router transfers a request to a specialist and how transfer state records the target. Explain why transfer tools are cached separately for each agent.
  Why it matters: It connects the user-visible handoff to the state the agent uses to carry it out.
• Agent tree relationships and validation: Describe the Agent fields that form the tree and justify its unique-name and single-parent constraints.
  Why it matters: Clear relationships and identities make transfer targets and name-based lookup unambiguous.
• Allowed transfer target rules: Explain which child, parent, and sibling agents are available as transfer targets and how disallow_transfer_to_peers changes that set.
  Why it matters: These rules determine which handoffs an agent can actually offer.
• Transfer structure choices: Distinguish supervisory, hierarchical, and network structures by their routing relationships and suitable use cases.
  Why it matters: The tree can be configured to match the way a team of agents needs to collaborate.
• Whole-tree name lookup: Trace how _find_agent locates a named agent from any starting point in the tree.
  Why it matters: A transfer request supplies a name, so the system must resolve it to an agent even when the requester is elsewhere in the tree.

Key terms: router agent, transfer_to_agent, ExecutionContext, transfer_to, transfer_tools, sub_agents, parent, description, _validate_and_set_sub_agents, agent tree

9.5.4 Implementing the transfer tool

This section explains how the transfer tool limits agent choices and records a requested transfer for the agent’s run method to handle.

• Transfer tool creation and behavior: Explain how create_transfer_tool builds transfer_to_agent from a list of transferable agents, helps the LLM choose a valid target, and records the choice without performing the transfer.
  Why it matters: It separates choosing a valid destination from carrying out the transfer.

Key terms: create_transfer_tool, transfer_to_agent, agent_name, enum constraint, context.transfer_to, run() method

9.5.5 Implementing agent transfer

This section connects the transfer tool to the Agent’s execution flow so an LLM-selected transfer hands work to another agent and returns its result.

• Transfer tool registration and exposure: Describe how run() registers the current agent’s transfer tool and how _prepare_llm_request() makes it available for the LLM to select.
  Why it matters: The LLM cannot choose a transfer unless the agent makes the transfer tool available in its request.
• Tool execution versus actual transfer: Distinguish executing the LLM’s transfer tool call in act() from transferring control to the target agent.
  Why it matters: The tool call records the intended destination; the execution loop must still act on it.
• Execution loop handoff and result: Trace how run() detects a recorded transfer, hands work to the target agent, and returns the final result.
  Why it matters: This is the point where a requested transfer becomes an actual handoff without the original agent continuing its loop.

Key terms: transfer_to_agent, context.transfer_tools, _prepare_llm_request(), act(), tools_dict, context.transfer_to, run(), step(), context.final_result

9.6 A2A: Collaborating across networks

This section explains why agents in separate codebases need A2A to collaborate over a network.

• Cross-network agent collaboration: Explain why the earlier same-process patterns cannot directly connect separately operated agents, and describe how A2A enables them to discover and collaborate across languages and frameworks.
  Why it matters: This distinction explains when collaboration needs a network protocol rather than an in-process agent pattern.

Key terms: A2A (Agent-to-Agent) protocol, Workflows, AgentTool, Transfer, HTTP-based communication

9.6.1 The core of A2A: Agent card and task request/response

This section explains how A2A clients discover remote agents through agent cards and communicate with them through standardized task requests and responses.

• Agent card discovery and routing: Explain what an A2A agent card tells a client, where the server publishes it, and how its fields help the client choose an agent and send a request.
  Why it matters: The card lets a client find a suitable remote agent and the address for contacting it.
• A2A client-server task exchange: Trace the roles of an A2A client and server from finding agent information through sending a task and receiving its result.
  Why it matters: This exchange is the basic model for calling an agent across a network.

Key terms: agent card, name, description, url, capabilities, A2A, client, server, task request/response, HTTP

9.6.2 Server: Exposing an agent to the network

Explains how to expose an agent as an A2A server by publishing an agent card and handling task requests through an AgentExecutor.

• A2A server responsibilities: Describe the two responsibilities needed to make an agent callable by other systems: provide an agent card and process task requests. Explain that the server combines the card and executor while the A2A library handles HTTP endpoints and routing.
  Why it matters: These are the pieces needed to make a local agent available to other systems.
• AgentExecutor request translation: Trace how AgentExecutor handles an A2A task request: its execute method extracts user input from RequestContext, calls the agent's run() method, and returns the result in A2A format.
  Why it matters: The executor is the bridge that lets an existing agent respond to A2A requests.

Key terms: A2A server, agent card, agent_card, agent_executor, AgentExecutor, execute, RequestContext, run(), A2A format

9.6.3 Client: Calling remote agents

This section shows how a client uses RemoteAgent to call a networked agent through the familiar agent interface and identifies security concerns for inter-agent communication.

• RemoteAgent client behavior: Trace how RemoteAgent obtains a remote agent’s information and sends it a task. Explain why callers can use it like a local agent.
  Why it matters: This interface lets existing agent code call a remote agent without handling HTTP directly.
• Reuse of collaboration patterns: Describe how RemoteAgent fits into the existing Transfer and AgentTool patterns and what that demonstrates about A2A.
  Why it matters: Remote agents can join an existing multi-agent design without requiring a separate collaboration pattern.
• Inter-agent communication safeguards: State the security concerns the section identifies for agents deployed across networks.
  Why it matters: Crossing a network boundary makes authorization and protected communication necessary design considerations.

Key terms: RemoteAgent, agent card, run(), _load_agent_info(), sub_agents, AgentTool, Transfer, A2A, authentication, communication encryption

9.7 Summary

The chapter summary explains why specialized agents help as tasks grow, compares three collaboration patterns, and shows how they can be combined across network boundaries.