Crew (Multi-Agent Handoffs)

What Is a Crew?

A crew lets more than one AI agent handle a single call. You define several members, each with its own instructions, and the call moves between them when conditions you wrote are met. A handoff only happens along a path you set up, and built-in guards stop a crew from looping. A sales agent handing off to a scheduling specialist is a typical crew. So is a first-line agent that passes detailed questions to a member carrying the knowledge base. Crews run in both legacy and live mode. For when to use one and how to design it, see the Crews guide.

Crew Members

Each crew has a members array. The first member answers the call.

Field	Type	Required	Description
`id`	string	Yes	Unique within the crew. 2 to 32 characters of lowercase letters, digits, `_` or `-`, starting with a letter.
`name`	string	Yes	Internal label (for example, “Alex”). The caller never hears it.
`instructions`	string	Yes	This member’s instructions, up to 8,000 characters.
`use_knowledge_base`	boolean	No	`true` gives this member every knowledge base attached to the campaign. Absent or `false`, it gets none.
`knowledge_base_ids`	array	No	Ids from the campaign’s attached knowledge bases that this member reads. Overrides `use_knowledge_base`; `[]` means none.
`mcp_tool_allowlist`	array	No	Subset of the campaign’s `mcp_tool_allowlist` this member can call. Absent inherits the campaign list; `[]` means no Integrations tools.
`mcp_tool_once_per_call`	array	No	Tools withdrawn from this member after their first successful result on the call. When the member sets `mcp_tool_allowlist`, each name must be in it.
`handoffs`	array	No	Where this member can hand off, and when. Absent or empty means it keeps the call to the end.

How Handoffs Work

Each entry in a member’s handoffs array points at another member:

Field	Type	Required	Description
`to`	string	Yes	The `id` of another member in the same crew. A member can’t hand off to itself.
`when`	string	Yes	The condition in plain words, up to 300 characters.

Write when the way you’d explain it to a person: “the caller wants to book a specific appointment time”. Handoffs are silent in both modes. The next member answers the caller’s last message directly, with no greeting, no introduction and no mention of a colleague. Every member speaks with the campaign’s voice; there’s no voice setting per member. On a Live call, the first reply after a handoff takes a little longer than a normal one.

Handoff Guards

Listed destinations only. A member can hand off only to a member in its own handoffs.
Handoff limit. max_handoffs caps handoffs per call (1 to 10, default 10). After that, the active member keeps the call.
No immediate bounce-back. A member can’t hand the call back to the member that just passed it, on the very next turn.

An Invalid Crew Is Refused

A crew that breaks a rule on this page (member count, a missing field, a bad id, a handoff to an unknown member) is never run as a single agent. Creating or updating a campaign with it, or placing a call with it, returns a 400 naming the rule. If a crew already saved on a campaign fails the checks, the call is refused before it dials with the code CREW_CONFIG_INVALID.

Limits

Limit	Value
Members per crew	2 to 5
Instructions per member	8,000 characters
`when` condition length	300 characters
`max_handoffs`	1 to 10 (default 10)

Example

A crew goes in the campaign config, under crew. This POST /v1/campaigns body creates one:

{
  "name": "Front desk",
  "config": {
    "mcp_tool_allowlist": ["book_appointment", "send_pricing_link"],
    "crew": {
      "max_handoffs": 3,
      "members": [
        {
          "id": "intro",
          "name": "Alex",
          "instructions": "You are Alex from the front desk. Greet the caller, confirm who you're speaking with, and find out whether they want to book an appointment or ask about pricing.",
          "handoffs": [
            {
              "to": "scheduler",
              "when": "the caller wants to book, reschedule, or confirm a specific appointment time"
            },
            {
              "to": "pricing",
              "when": "the caller is asking about pricing or plan details"
            }
          ]
        },
        {
          "id": "scheduler",
          "name": "Jordan",
          "instructions": "Confirm the caller's preferred date and time and book the appointment.",
          "use_knowledge_base": false,
          "mcp_tool_allowlist": ["book_appointment"]
        },
        {
          "id": "pricing",
          "name": "Sam",
          "instructions": "Answer pricing questions from the knowledge base and offer to send the pricing link.",
          "use_knowledge_base": true,
          "mcp_tool_allowlist": ["send_pricing_link"],
          "handoffs": [
            {
              "to": "scheduler",
              "when": "the caller is ready to book after getting pricing information"
            }
          ]
        }
      ]
    }
  }
}

Setting Crew Per Call

POST /v1/calls takes the same crew object for a single call.

Next Steps

Campaign Management

Learn how crew fits into campaign configuration.

AI & Voice Customization

Learn how to write effective instructions for a single agent.

Getting Started

Core Concepts

Guides

Use Cases

Integrations

What Is a Crew?

Crew Members

How Handoffs Work

Handoff Guards

An Invalid Crew Is Refused

Limits

Example

Setting Crew Per Call

Next Steps

Campaign Management

AI & Voice Customization

​What Is a Crew?

​Crew Members

​How Handoffs Work

​Handoff Guards

​An Invalid Crew Is Refused

​Limits

​Example

​Setting Crew Per Call

​Next Steps

Campaign Management

AI & Voice Customization

What Is a Crew?

Crew Members

How Handoffs Work

Handoff Guards

An Invalid Crew Is Refused

Limits

Example

Setting Crew Per Call

Next Steps