Multi-Agent Orchestration

Agent objective

Produce a builder with agent tools registered so an agent can delegate subtasks to specialized sub-agents and integrate their results.

When to load this skill

• Building a lead agent that coordinates specialist sub-agents
• Splitting complex tasks across research, writing, coding, or review agents
• Connecting to remote agents via A2A protocol
• Allowing the agent to dynamically spawn sub-agents at runtime based on task needs

Implementation baseline

import { ReactiveAgents } from "@reactive-agents/runtime";

// Lead agent with registered sub-agents as tools
const agent = await ReactiveAgents.create()
  .withName("lead")
  .withProvider("anthropic")
  .withReasoning({ defaultStrategy: "plan-execute-reflect", maxIterations: 20 })
  .withAgentTool("researcher", {
    name: "Research Agent",
    description: "Gathers information, reads web pages, and synthesizes findings",
    maxIterations: 12,
    tools: ["web-search", "http-get", "checkpoint"],
  })
  .withAgentTool("coder", {
    name: "Code Agent",
    description: "Writes, tests, and refactors TypeScript code",
    maxIterations: 15,
    strategy: "plan-execute-reflect",
    tools: ["file-read", "file-write", "code-execute"],
  })
  .withAgentTool("reviewer", {
    name: "Review Agent",
    description: "Reviews code for correctness, style, and security issues",
    maxIterations: 8,
    tools: ["file-read"],
  })
  .withTools({ allowedTools: ["researcher", "coder", "reviewer", "checkpoint", "final-answer"] })
  .withSystemPrompt(`
    You coordinate a team of specialists. Delegate tasks to the appropriate agent.
    Always checkpoint results from sub-agents before continuing to the next phase.
  `)
  .build();

Key patterns

withAgentTool() — register a named sub-agent

.withAgentTool("analyst", {
  name: "Data Analyst",                        // display name for the agent
  description: "Analyzes datasets and produces statistics",  // tool description shown to LLM
  provider: "anthropic",                       // defaults to parent's provider
  model: "claude-haiku-4-5-20251001",          // use a cheaper model for sub-tasks
  maxIterations: 10,                           // sub-agent iteration limit
  strategy: "adaptive",                        // sub-agent reasoning strategy
  tools: ["file-read", "code-execute"],        // tools available to sub-agent
})

The sub-agent runs as a tool call — the LLM calls it with a task description and receives the result.

Dynamic sub-agents (runtime spawning)

.withDynamicSubAgents({ maxIterations: 8 })
// Enables spawning ad-hoc agents at runtime.
// The agent can dynamically create and call sub-agents based on task needs.
// Sub-agents inherit the parent's provider and model by default.

Remote agent via A2A

.withRemoteAgent("data-service", "http://data-agent:8000")
// Connects to a remote A2A agent at the given URL.
// Remote agent is exposed as a tool — called exactly like a local sub-agent.
// Remote agent must expose the A2A JSON-RPC interface (see a2a-agent-networking skill).

Pipeline pattern: research → write → review

const agent = await ReactiveAgents.create()
  .withProvider("anthropic")
  .withReasoning({ defaultStrategy: "plan-execute-reflect", maxIterations: 25 })
  .withAgentTool("researcher", {
    name: "Researcher",
    description: "Research a topic and return key findings",
    tools: ["web-search", "http-get", "checkpoint"],
  })
  .withAgentTool("writer", {
    name: "Writer",
    description: "Write a document given research findings",
    tools: ["file-write", "checkpoint"],
  })
  .withAgentTool("reviewer", {
    name: "Reviewer",
    description: "Review a document and return critique",
    tools: ["file-read"],
  })
  .withTools({ allowedTools: ["researcher", "writer", "reviewer", "final-answer"] })
  .withSystemPrompt(`
    1. Call researcher to gather information on the topic.
    2. Call writer with the research to produce the document.
    3. Call reviewer with the document path.
    4. Revise if the reviewer finds critical issues.
    5. Return final-answer when approved.
  `)
  .build();

withAgentTool() parameters

Parameter	Type	Notes
name	string	Human-readable display name
description	string	Tool description shown to the orchestrating LLM
provider	ProviderName	Defaults to parent's provider
model	string	Defaults to parent's model — use cheaper models for sub-agents
maxIterations	number	Sub-agent iteration cap
strategy	string	Sub-agent reasoning strategy
tools	string[]	Tools available to the sub-agent

Builder API reference

Method	Notes
.withAgentTool(name, opts)	Registers a local sub-agent as a named tool
.withDynamicSubAgents(opts?)	Allows the agent to spawn sub-agents at runtime
.withRemoteAgent(name, url)	Connects to a remote A2A agent as a named tool

Pitfalls

• Sub-agent tools are scoped to that sub-agent only — the parent's tool set does not propagate down
• Each sub-agent runs in an isolated context — it has no access to the parent's conversation history
• withDynamicSubAgents is open-ended — the agent can create arbitrary sub-agents, which can significantly increase costs
• Remote agents must be up and serving A2A requests at build time — connection failures surface during .build()
• Always include "final-answer" in the orchestrator's allowedTools or it cannot complete