Coordinate multiple specialized agents for complex workflows and seamless conversation handoffs
Multi-agent systems enable sophisticated workflows where specialized agents collaborate, transfer conversations, and handle different aspects of complex tasks.
The Multi-Agent primitive allows you to orchestrate multiple specialized agents within a single workflow or conversation. Instead of one generalist agent handling everything, you can deploy domain experts that collaborate, transfer work between each other, and provide specialized capabilities for different parts of your application.Multi-agent systems are essential for:
Specialized Expertise: Different agents with deep knowledge in specific domains
Conversation Routing: Intelligent transfer between support, sales, technical agents
Complex Workflows: Breaking down large tasks across multiple specialized agents
Parallel Processing: Multiple agents working simultaneously on different subtasks
Scalable Architecture: Add new agent specialists without modifying existing ones
Seamless Handoffs
Agents can transfer conversations to other specialists while maintaining full context
Domain Experts
Each agent can have specialized knowledge, tools, and behavioral patterns
Automatic Routing
Main agent intelligently determines which specialist should handle each request
Shared Context
All agents in a session share conversation history and can build on each other’s work
Main Agent: Acts as coordinator, receives initial requests
Agent Discovery: Main agent knows about available specialists and their capabilities
Intelligent Routing: Determines which specialist is best suited for the current task
Transfer: Hands off conversation to specialist while preserving full context
Specialist Handling: Specialist agent takes over and handles the request
Return or Continue: Specialist can return control to main agent or continue handling
Context Preservation: When agents transfer conversations, the entire message history and context is preserved. The specialist agent has full visibility into everything that was discussed before.
import { Agentbase } from '@agentbase/sdk';const agentbase = new Agentbase({ apiKey: process.env.AGENTBASE_API_KEY});// Configure multiple specialized agentsconst result = await agentbase.runAgent({ message: "I need help with my order", system: "You are a customer service coordinator. Analyze the request and transfer to the appropriate specialist.", agents: [ { name: "Order Support", description: "Handles order status, tracking, shipping, and delivery questions" }, { name: "Billing Support", description: "Handles payment issues, refunds, invoices, and billing questions" }, { name: "Technical Support", description: "Handles technical issues, bugs, and product functionality questions" } ]});// Main agent analyzes request and transfers to Order Support
// Configure sales and support agentsconst result = await agentbase.runAgent({ message: "What are your pricing plans?", system: `You are a helpful assistant. Route customers to: - Sales Agent for pricing, demos, and product information - Support Agent for existing customer issues and technical help`, agents: [ { name: "Sales Agent", description: "Handles product inquiries, pricing questions, demos, and new customer onboarding" }, { name: "Support Agent", description: "Handles existing customer support, technical issues, and account management" } ]});// Main agent transfers to Sales Agent for pricing inquiry
// Initial request with multi-agent setupconst initial = await agentbase.runAgent({ message: "I have a billing question", system: "Route to appropriate specialist", agents: [ { name: "Billing Specialist", description: "Handles all billing and payment questions" }, { name: "Technical Specialist", description: "Handles technical issues" } ]});// Main agent transfers to Billing Specialistconst sessionId = initial.session;// Continue conversation with same sessionconst followUp = await agentbase.runAgent({ message: "I need a copy of my invoice", session: sessionId // Billing Specialist still handling, has full context});// Another follow-upconst finalResponse = await agentbase.runAgent({ message: "Can you explain this charge?", session: sessionId // Still with Billing Specialist, remembers everything});
async function customerServiceHub() { const config = { system: `You are a customer service coordinator for TechCorp. Analyze each customer request and route to the appropriate specialist: - Order Support: order status, shipping, delivery - Billing Support: payments, refunds, invoices - Technical Support: product issues, bugs, troubleshooting - Account Support: account settings, password resets, user management Always greet customers warmly and let them know you're transferring them to a specialist.`, agents: [ { name: "Order Support", description: "Expert in order management, shipping, tracking, and delivery. Has access to order database and shipping APIs." }, { name: "Billing Support", description: "Expert in payments, refunds, invoices, and billing issues. Has access to payment systems and accounting tools." }, { name: "Technical Support", description: "Expert in product functionality, troubleshooting, and bug reporting. Has access to technical documentation and bug tracking system." }, { name: "Account Support", description: "Expert in account management, user settings, and authentication. Has access to user management system." } ], mcpServers: [ { serverName: "customer-systems", serverUrl: "https://api.company.com/mcp" } ] }; return config;}// Use in applicationconst result = await agentbase.runAgent({ message: "I can't access my account", ...await customerServiceHub()});
const healthcareTriage = await agentbase.runAgent({ message: "Patient experiencing chest pain and shortness of breath", system: `You are a medical triage coordinator. IMPORTANT: This is for informational purposes only. Always advise patients to seek immediate medical attention for serious symptoms. Route to appropriate specialist based on symptoms and severity.`, agents: [ { name: "Emergency Triage", description: "Handles urgent symptoms requiring immediate medical attention. Advises calling 911 or going to ER." }, { name: "Primary Care Advisor", description: "Handles general health questions, non-urgent symptoms, provides health information and guidance" }, { name: "Specialist Referral", description: "Recommends appropriate medical specialists based on symptoms, provides information about specialists" }, { name: "Appointment Scheduler", description: "Helps schedule appointments with appropriate providers, checks availability" } ]});// Emergency Triage would handle this serious symptom
Main Agent Guidance: Give your main/coordinator agent clear instructions on when to route to each specialist and how to handle edge cases.
Copy
const result = await agentbase.runAgent({ message: customerMessage, system: `You are a customer service coordinator. ROUTING RULES: 1. Order questions (status, tracking, delivery) → Order Support 2. Payment questions (charges, refunds, invoices) → Billing Support 3. Technical problems (errors, bugs, not working) → Technical Support 4. Account questions (login, settings, profile) → Account Support EDGE CASES: - If unclear, ask clarifying questions before routing - If spans multiple areas, route to primary concern - If urgent (data loss, security), route to Technical Support immediately Always: - Greet customer warmly - Briefly acknowledge their issue - Explain which specialist will help them - Transfer seamlessly`, agents: [ // ... agent definitions ]});
system: `You are a coordinator.If the customer's request is ambiguous:1. DON'T transfer immediately2. Ask 1-2 clarifying questions3. Once clear, route to appropriate specialistExample:Customer: "I have a problem"You: "I'd be happy to help! Could you tell me a bit more about the problem you're experiencing? Is it related to an order, billing, technical issue, or something else?"Then route based on clarification.`
Fallback Agents
Copy
agents: [ { name: "Order Support", description: "Handles order-related questions" }, { name: "Billing Support", description: "Handles billing questions" }, { name: "General Support", description: "Fallback agent for questions that don't fit other categories or need general assistance" }]// Main agent can route to General Support for edge cases
// Main agent has routing prompt// Specialist agents get specialized prompts when they take overconst result = await agentbase.runAgent({ message: "Technical issue", system: "You are a coordinator. Route technical issues to Technical Support.", agents: [ { name: "Technical Support", description: "Handles technical issues" // When this agent takes over, it gets technical support expertise } ]});
// Configure tools that all agents might need at the main levelmcpServers: [ { serverName: "customer-data", // All agents can access serverUrl: "https://api.company.com/customers" }]// Specialist agents automatically use domain-specific tools wisely
Problem: Main agent not routing to specialistsSolutions:
Make agent descriptions more specific
Add explicit routing guidance in system prompt
Ensure agent names clearly indicate their purpose
Copy
// Add explicit routing guidancesystem: `IMPORTANT: You must transfer to specialists.When you receive a request:1. Identify the primary topic2. Match to specialist description3. Transfer immediately with warm introductionExamples:- "Track my order" → Transfer to Order Support- "Refund question" → Transfer to Billing SupportDO NOT try to handle specialist topics yourself.`
Wrong Agent Selected
Problem: Requests routed to incorrect specialistSolutions:
Improve agent descriptions to be more distinct
Add routing examples in system prompt
Use clear, non-overlapping specializations
Copy
// Make descriptions mutually exclusiveagents: [ { name: "Pre-Sales", description: "ONLY for prospects and leads who haven't purchased yet. Handles product questions, demos, pricing for new customers." }, { name: "Post-Sales", description: "ONLY for existing customers who have already purchased. Handles support, issues, account management." }]
Context Lost After Transfer
Problem: Specialist doesn’t seem to have previous contextSolution: This shouldn’t happen - verify you’re using same session
Copy
// Ensure session continuityconst initial = await agentbase.runAgent({ message: "My order #12345 is late", agents: [ /* ... */ ]});// Use same session for follow-upsconst followUp = await agentbase.runAgent({ message: "Did you check the tracking?", session: initial.session // ✓ Context preserved});
Too Many Transfers
Problem: Request bounces between multiple agentsSolutions:
Design clear, non-overlapping specializations
Give guidance on edge cases
Use a generalist fallback agent
Copy
system: `Route requests clearly:- If request fits ONE specialist perfectly → transfer immediately- If request spans MULTIPLE areas → route to primary concern- If request is UNCLEAR → ask clarifying question first- If request is GENERAL → handle yourself or route to General SupportNever transfer more than once per request.`
Remember: Design agents as specialists with clear, non-overlapping domains. Let the main agent handle routing, and give each specialist deep expertise in their area.