Multi-Agent - Agentbase Docs

Multi-agent systems enable sophisticated workflows where specialized agents collaborate, transfer conversations, and handle different aspects of complex tasks.

Overview

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

How Multi-Agent Works

When you configure multiple agents:

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.

Code Examples

Basic Multi-Agent Setup

import { Agentbase } from '@agentbase/sdk';

const agentbase = new Agentbase({
  apiKey: process.env.AGENTBASE_API_KEY
});

// Configure multiple specialized agents
const 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

from agentbase import Agentbase

agentbase = Agentbase(api_key=os.environ['AGENTBASE_API_KEY'])

# Configure multiple specialized agents
result = agentbase.run_agent(
    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

curl -X POST https://api.agentbase.sh \
  -H "Authorization: Bearer $AGENTBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "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"
      }
    ]
  }'

Sales and Support Routing

// Configure sales and support agents
const 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

# Configure sales and support agents
result = agentbase.run_agent(
    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

Multi-Agent with Custom Tools

// Different agents with different tool access
const result = await agentbase.runAgent({
  message: "Process this customer order",
  system: "You are an order coordinator. Route to appropriate specialist.",
  agents: [
    {
      name: "Order Processor",
      description: "Processes new orders, checks inventory, creates order records"
    },
    {
      name: "Payment Handler",
      description: "Handles payment processing, refunds, and billing"
    },
    {
      name: "Shipping Coordinator",
      description: "Manages shipping, tracking, and delivery logistics"
    }
  ],
  mcpServers: [
    {
      serverName: "order-system",
      serverUrl: "https://api.company.com/orders"
    },
    {
      serverName: "payment-gateway",
      serverUrl: "https://api.company.com/payments"
    },
    {
      serverName: "shipping-api",
      serverUrl: "https://api.company.com/shipping"
    }
  ]
});

// Each specialist agent uses relevant tools for their domain

# Different agents with different tool access
result = agentbase.run_agent(
    message="Process this customer order",
    system="You are an order coordinator. Route to appropriate specialist.",
    agents=[
        {
            "name": "Order Processor",
            "description": "Processes new orders, checks inventory, creates order records"
        },
        {
            "name": "Payment Handler",
            "description": "Handles payment processing, refunds, and billing"
        },
        {
            "name": "Shipping Coordinator",
            "description": "Manages shipping, tracking, and delivery logistics"
        }
    ],
    mcp_servers=[
        {
            "serverName": "order-system",
            "serverUrl": "https://api.company.com/orders"
        },
        {
            "serverName": "payment-gateway",
            "serverUrl": "https://api.company.com/payments"
        },
        {
            "serverName": "shipping-api",
            "serverUrl": "https://api.company.com/shipping"
        }
    ]
)

# Each specialist agent uses relevant tools for their domain

Continuing Multi-Agent Conversations

// Initial request with multi-agent setup
const 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 Specialist
const sessionId = initial.session;

// Continue conversation with same session
const followUp = await agentbase.runAgent({
  message: "I need a copy of my invoice",
  session: sessionId
  // Billing Specialist still handling, has full context
});

// Another follow-up
const finalResponse = await agentbase.runAgent({
  message: "Can you explain this charge?",
  session: sessionId
  // Still with Billing Specialist, remembers everything
});

# Initial request with multi-agent setup
initial = agentbase.run_agent(
    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 Specialist
session_id = initial.session

# Continue conversation with same session
follow_up = agentbase.run_agent(
    message="I need a copy of my invoice",
    session=session_id
    # Billing Specialist still handling, has full context
)

# Another follow-up
final_response = agentbase.run_agent(
    message="Can you explain this charge?",
    session=session_id
    # Still with Billing Specialist, remembers everything
)

Use Cases

1. Customer Service Hub

Multi-tier support with specialized agents:

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 application
const result = await agentbase.runAgent({
  message: "I can't access my account",
  ...await customerServiceHub()
});

2. Sales Pipeline

Route through sales stages with specialized agents:

const salesPipeline = await agentbase.runAgent({
  message: "I'm interested in your enterprise plan",
  system: `You manage the sales pipeline. Route prospects through:
  - Discovery Agent: initial contact, qualification
  - Demo Agent: product demonstrations, feature explanations
  - Pricing Agent: pricing discussions, proposals
  - Closing Agent: contract negotiation, final steps`,
  agents: [
    {
      name: "Discovery Agent",
      description: "Qualifies leads, understands customer needs, identifies pain points, and determines fit"
    },
    {
      name: "Demo Agent",
      description: "Showcases product features, provides demonstrations, explains use cases, answers product questions"
    },
    {
      name: "Pricing Agent",
      description: "Discusses pricing options, creates proposals, explains ROI, handles budget conversations"
    },
    {
      name: "Closing Agent",
      description: "Finalizes contracts, addresses final concerns, coordinates onboarding, completes sale"
    }
  ]
});

3. Content Production Workflow

Coordinate content creation across specialists:

const contentWorkflow = await agentbase.runAgent({
  message: "Create a comprehensive blog post about AI in healthcare",
  system: "You coordinate content production. Route through specialists for best results.",
  agents: [
    {
      name: "Research Agent",
      description: "Conducts research, gathers sources, verifies facts, finds statistics and case studies"
    },
    {
      name: "Writing Agent",
      description: "Creates compelling content, ensures proper structure, maintains tone and voice"
    },
    {
      name: "SEO Agent",
      description: "Optimizes for search engines, adds meta descriptions, suggests keywords, improves discoverability"
    },
    {
      name: "Editing Agent",
      description: "Reviews for grammar, clarity, consistency, fact-checks, and overall quality"
    }
  ]
});

// Research Agent gathers information
// Writing Agent creates draft
// SEO Agent optimizes
// Editing Agent reviews and polishes

4. Development Team Simulation

Specialized development agents:

const devTeam = await agentbase.runAgent({
  message: "Build a REST API for user management",
  system: "You are a tech lead coordinating development specialists.",
  agents: [
    {
      name: "Backend Developer",
      description: "Designs and implements server-side logic, APIs, database schemas, and business logic"
    },
    {
      name: "Database Architect",
      description: "Designs database schemas, optimizes queries, ensures data integrity and performance"
    },
    {
      name: "DevOps Engineer",
      description: "Sets up deployment pipelines, manages infrastructure, handles containerization and orchestration"
    },
    {
      name: "QA Engineer",
      description: "Creates test plans, writes tests, performs quality assurance, validates functionality"
    },
    {
      name: "Security Specialist",
      description: "Reviews for security vulnerabilities, implements authentication, ensures compliance"
    }
  ]
});

// Each specialist contributes their expertise to the project

5. Healthcare Triage System

Medical domain specialists:

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

6. Financial Advisory Service

Financial domain specialists:

const financialAdvisory = await agentbase.runAgent({
  message: "Help me plan for retirement",
  system: `You coordinate financial advisory services.

  IMPORTANT: Remind users that agents provide educational information only and to consult licensed financial advisors for personalized advice.`,
  agents: [
    {
      name: "Retirement Planner",
      description: "Provides retirement planning information, 401k guidance, pension advice, retirement age calculations"
    },
    {
      name: "Investment Advisor",
      description: "Educates about investment options, portfolio strategies, risk assessment, asset allocation"
    },
    {
      name: "Tax Specialist",
      description: "Provides tax-related information, deduction guidance, tax-advantaged account education"
    },
    {
      name: "Estate Planner",
      description: "Educates about estate planning, wills, trusts, inheritance considerations"
    }
  ]
});

Best Practices

Agent Design

Clear Specialization

// Good: Clear, distinct specializations
agents: [
  {
    name: "Technical Support",
    description: "Handles technical issues: bugs, errors, performance problems, integration issues"
  },
  {
    name: "Product Support",
    description: "Handles product usage: features, best practices, workflows, how-to questions"
  }
]

// Avoid: Overlapping or vague descriptions
agents: [
  {
    name: "Support Agent 1",
    description: "Helps with various issues"
  },
  {
    name: "Support Agent 2",
    description: "Also helps with issues"
  }
]

Descriptive Names

// Good: Descriptive, role-based names
agents: [
  {
    name: "Order Fulfillment Specialist",
    description: "Processes orders, manages inventory, coordinates shipping"
  },
  {
    name: "Returns and Refunds Specialist",
    description: "Handles return requests, processes refunds, manages exchanges"
  }
]

// Avoid: Generic or numbered names
agents: [
  {
    name: "Agent 1",
    description: "Handles some tasks"
  },
  {
    name: "Agent 2",
    description: "Handles other tasks"
  }
]

Detailed Descriptions

// Good: Comprehensive descriptions
agents: [
  {
    name: "Billing Specialist",
    description: `Expert in all billing matters including:
    - Payment processing and methods
    - Invoice generation and history
    - Refund and chargeback handling
    - Subscription management
    - Pricing and plan changes
    - Payment failure resolution

    Has access to payment gateway and billing systems.`
  }
]

// Avoid: Minimal descriptions
agents: [
  {
    name: "Billing Specialist",
    description: "Handles billing"
  }
]

Routing Strategy

Main Agent Guidance: Give your main/coordinator agent clear instructions on when to route to each specialist and how to handle edge cases.

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
  ]
});

Performance Optimization

Limit Agent Count

Use 3-5 specialized agents per workflow for optimal performance

Smart Routing

Design clear routing criteria to minimize unnecessary transfers

Session Reuse

Keep multi-agent sessions alive for related conversations

Tool Scoping

Give each agent access only to tools they need

Error Handling

Handle Ambiguous Requests

system: `You are a coordinator.

If the customer's request is ambiguous:
1. DON'T transfer immediately
2. Ask 1-2 clarifying questions
3. Once clear, route to appropriate specialist

Example:
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

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

Integration with Other Primitives

With Prompts

Each agent can have specialized system prompts:

// Main agent has routing prompt
// Specialist agents get specialized prompts when they take over
const 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
    }
  ]
});

Learn more: Prompts Primitive

With Custom Tools

Different agents can access different tools:

const result = await agentbase.runAgent({
  message: "Process order and payment",
  agents: [
    {
      name: "Order Agent",
      description: "Processes orders (has access to order-system tools)"
    },
    {
      name: "Payment Agent",
      description: "Handles payments (has access to payment-gateway tools)"
    }
  ],
  mcpServers: [
    {
      serverName: "order-system",
      serverUrl: "https://api.company.com/orders"
    },
    {
      serverName: "payment-gateway",
      serverUrl: "https://api.company.com/payments"
    }
  ]
});

// Each agent intelligently uses tools relevant to their domain

Learn more: Custom Tools Primitive

With Sessions

All agents in a session share context:

// Start multi-agent session
const initial = await agentbase.runAgent({
  message: "I need help",
  agents: [
    { name: "Agent A", description: "Handles A" },
    { name: "Agent B", description: "Handles B" }
  ]
});

// Continue - agents share full conversation history
const continued = await agentbase.runAgent({
  message: "Follow-up question",
  session: initial.session
  // Current agent has full context from previous agents
});

Learn more: Sessions Primitive

With Parallelization

Run multiple agents in parallel:

// Parallel multi-agent execution
const results = await Promise.all([
  agentbase.runAgent({
    message: "Research topic A",
    agents: [{ name: "Research A", description: "Expert in A" }]
  }),
  agentbase.runAgent({
    message: "Research topic B",
    agents: [{ name: "Research B", description: "Expert in B" }]
  }),
  agentbase.runAgent({
    message: "Research topic C",
    agents: [{ name: "Research C", description: "Expert in C" }]
  })
]);

// Each runs independently with specialized agent

Learn more: Parallelization Primitive

Performance Considerations

Agent Count Impact

2-3 Agents: Optimal performance, clear routing
4-6 Agents: Good performance, more specialization
7+ Agents: Consider if all are necessary, may slow routing decisions

// Optimize by grouping related capabilities
// Instead of 10 narrow specialists:
agents: [
  { name: "Spec1", description: "Does X" },
  { name: "Spec2", description: "Does Y" },
  // ... 8 more
]

// Use 4-5 broader specialists:
agents: [
  { name: "Order & Shipping", description: "Handles all order-related tasks including shipping" },
  { name: "Billing & Payments", description: "Handles all financial transactions" },
  { name: "Technical Support", description: "Handles all technical issues" },
  { name: "Account Management", description: "Handles user accounts and settings" }
]

Routing Efficiency

Clear routing reduces transfer overhead:

// Efficient: Clear routing criteria
system: `Route based on keywords:
- "order", "shipping", "delivery" → Order Support
- "payment", "charge", "refund" → Billing Support
- "error", "bug", "not working" → Technical Support`

// Less efficient: Vague routing
system: "Figure out which agent should handle this"

Tool Access Optimization

Only provide tools relevant to each agent:

// Configure tools that all agents might need at the main level
mcpServers: [
  {
    serverName: "customer-data",  // All agents can access
    serverUrl: "https://api.company.com/customers"
  }
]

// Specialist agents automatically use domain-specific tools wisely

Troubleshooting

Agent Not Transferring

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

// Add explicit routing guidance
system: `IMPORTANT: You must transfer to specialists.

When you receive a request:
1. Identify the primary topic
2. Match to specialist description
3. Transfer immediately with warm introduction

Examples:
- "Track my order" → Transfer to Order Support
- "Refund question" → Transfer to Billing Support

DO 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

// Make descriptions mutually exclusive
agents: [
  {
    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

// Ensure session continuity
const initial = await agentbase.runAgent({
  message: "My order #12345 is late",
  agents: [ /* ... */ ]
});

// Use same session for follow-ups
const 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

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 Support

Never transfer more than once per request.`

Prompts

Specialized system prompts for each agent

Sessions

Shared context across all agents

Custom Tools

Domain-specific tools for specialists

Parallelization

Run multiple agents concurrently

Additional Resources

API Reference

Agents parameter documentation

Use Cases

Multi-agent implementation examples

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.

​Overview

Seamless Handoffs

Domain Experts

Automatic Routing

Shared Context

​How Multi-Agent Works

​Code Examples

​Basic Multi-Agent Setup

​Sales and Support Routing

​Multi-Agent with Custom Tools

​Continuing Multi-Agent Conversations

​Use Cases

​1. Customer Service Hub

​2. Sales Pipeline

​3. Content Production Workflow

​4. Development Team Simulation

​5. Healthcare Triage System

​6. Financial Advisory Service

​Best Practices

​Agent Design

​Routing Strategy

​Performance Optimization

Limit Agent Count

Smart Routing

Session Reuse

Tool Scoping

​Error Handling

​Integration with Other Primitives

​With Prompts

​With Custom Tools

​With Sessions

​With Parallelization

​Performance Considerations

​Agent Count Impact

​Routing Efficiency

​Tool Access Optimization

​Troubleshooting

​Related Primitives

Prompts

Sessions

Custom Tools

Parallelization

​Additional Resources

API Reference

Use Cases

Overview

How Multi-Agent Works

Code Examples

Basic Multi-Agent Setup

Sales and Support Routing

Multi-Agent with Custom Tools

Continuing Multi-Agent Conversations

Use Cases

1. Customer Service Hub

2. Sales Pipeline

3. Content Production Workflow

4. Development Team Simulation

5. Healthcare Triage System

6. Financial Advisory Service

Best Practices

Agent Design

Routing Strategy

Performance Optimization

Error Handling

Integration with Other Primitives

With Prompts

With Custom Tools

With Sessions

With Parallelization

Performance Considerations

Agent Count Impact

Routing Efficiency

Tool Access Optimization

Troubleshooting

Related Primitives

Additional Resources