GUIDES
Multi-Agent Systems
Multi-agent systems use multiple specialized agents that collaborate to solve complex tasks. An orchestrator routes requests to the best agent, and agents can delegate to each other.
Architecture Patterns
There are three common patterns for multi-agent systems:
PatternDescription
RouterA classifier agent routes incoming requests to specialized agents based on intent
PipelineAgents process data sequentially, each adding to or transforming the output
CollaborativeAgents can call each other as tools, delegating subtasks dynamically
Router Pattern
The router pattern uses a fast, low-cost agent to classify incoming requests and delegate to the appropriate specialist:
Router agent
// Create specialist agents
const supportAgent = await client.agents.create({
name: "Support Specialist",
model: "claude-sonnet-4-20250514",
systemPrompt: "You handle customer support issues...",
tools: [lookupOrder, createTicket],
});
const salesAgent = await client.agents.create({
name: "Sales Specialist",
model: "claude-sonnet-4-20250514",
systemPrompt: "You handle sales inquiries...",
tools: [qualifyLead, scheduleDemo],
});
const billingAgent = await client.agents.create({
name: "Billing Specialist",
model: "claude-sonnet-4-20250514",
systemPrompt: "You handle billing questions...",
tools: [lookupInvoice, processRefund],
});
// Create the router (fast, cheap model)
const router = await client.agents.create({
name: "Request Router",
model: "claude-haiku-4-20250514",
systemPrompt: `Classify the user's request into one category:
- SUPPORT: order issues, returns, product questions
- SALES: pricing, demos, purchasing
- BILLING: invoices, payments, refunds
Respond with ONLY the category name, nothing else.`,
parameters: { temperature: 0, maxTokens: 10 },
});
// Orchestration logic
async function handleRequest(input: string, conversationId?: string) {
// Step 1: Route
const classification = await client.agents.execute(router.id, {
input,
});
const category = classification.output.trim().toUpperCase();
// Step 2: Delegate to specialist
const agents: Record<string, string> = {
SUPPORT: supportAgent.id,
SALES: salesAgent.id,
BILLING: billingAgent.id,
};
const agentId = agents[category] || supportAgent.id;
return client.agents.execute(agentId, {
input,
conversationId,
stream: true,
});
}
Pipeline Pattern
Sequential pipeline
// Agent 1: Extract data from email
const extractor = await client.agents.create({
name: "Email Extractor",
model: "claude-sonnet-4-20250514",
systemPrompt: "Extract structured data from emails: sender, subject, intent, entities, urgency.",
parameters: { temperature: 0.1 },
});
// Agent 2: Enrich extracted data
const enricher = await client.agents.create({
name: "Data Enricher",
model: "claude-sonnet-4-20250514",
systemPrompt: "Given extracted email data, look up the sender in our CRM and add context.",
tools: [crmLookup, companyInfo],
});
// Agent 3: Draft a response
const responder = await client.agents.create({
name: "Response Drafter",
model: "claude-sonnet-4-20250514",
systemPrompt: "Draft a response to the email using the enriched context. Match the sender's tone.",
parameters: { temperature: 0.5 },
});
// Run the pipeline
async function processEmail(emailContent: string) {
const extracted = await client.agents.execute(extractor.id, {
input: emailContent,
});
const enriched = await client.agents.execute(enricher.id, {
input: `Enrich this data: ${extracted.output}`,
});
const response = await client.agents.execute(responder.id, {
input: `Draft a response. Context: ${enriched.output}\nOriginal: ${emailContent}`,
});
return response.output;
}
Collaborative Pattern
Agents as tools
// Agents can call other agents as tools
const researchAgent = await client.agents.create({
name: "Research Agent",
model: "claude-sonnet-4-20250514",
systemPrompt: "Research topics and provide detailed analysis.",
tools: [{ builtin: "web_search" }],
});
const writerAgent = await client.agents.create({
name: "Content Writer",
model: "claude-sonnet-4-20250514",
systemPrompt: "Write blog posts using research provided by the research agent.",
tools: [
{
name: "research",
description: "Ask the research agent to investigate a topic",
parameters: {
type: "object",
properties: {
query: { type: "string", description: "Research question" },
},
required: ["query"],
},
// Handler calls the research agent
handler: "https://api.example.com/webhooks/agent-research",
},
],
});
// The handler for the research tool
// POST /webhooks/agent-research
app.post("/webhooks/agent-research", async (req, res) => {
const { query } = req.body.parameters;
const result = await client.agents.execute(researchAgent.id, {
input: query,
});
res.json({ result: { research: result.output } });
});
Note
When using the collaborative pattern, set reasonable timeouts for agent-to-agent calls. The default 10-second tool timeout may not be sufficient for complex research tasks.
Best Practices
- -Use fast models for routing — Haiku for classification, Sonnet for complex tasks
- -Keep agents focused — Each agent should have one clear responsibility
- -Add fallback routing — Always have a default agent for unclassified requests
- -Log the full chain — Track which agents handled each request for debugging
- -Set depth limits — Prevent infinite agent-to-agent delegation loops