Crew (Multi-Agent Handoffs)

Crew is rolling out gradually. Availability may vary by account while this feature is being enabled.

What Is a Crew?

A crew lets a single call be handled by more than one AI agent. Instead of one set of instructions trying to cover every part of a conversation, you define several members, each with their own instructions, and the call moves between them when specific conditions are met. One member starts the call. When the conversation reaches a point you defined, that member hands off to another member, who takes over with their own instructions and tone. A handoff can only happen along a path you set up, and a few built-in guards stop a crew from looping or bouncing a call back and forth. Use cases include a sales agent that hands off to a scheduling specialist, or a first-line agent that hands off to a member with access to the knowledge base for detailed questions.

Crew Members

Each crew has a members array. Every member is an object with these fields:

Field	Type	Required	Description
`id`	string	Yes	Short identifier for the member, unique within the crew.
`name`	string	Yes	Display name for the member (for example, “Alex”).
`instructions`	string	Yes	This member’s own instructions, up to 8000 characters.
`use_knowledge_base`	boolean	No	When true, your knowledge base is added to this member’s instructions. When false or absent, this member does not use the knowledge base.
`knowledge_base_ids`	array	No	Optional subset of this campaign’s attached knowledge base entry ids visible to this member. When absent, `use_knowledge_base` controls all-or-none access. An empty array means this member gets no knowledge base entries.
`mcp_tool_allowlist`	array	No	Optional subset of the campaign-level `mcp_tool_allowlist` available to this member. When absent, the member inherits the campaign-level tool list. An empty array means this member gets no remote tools.
`handoffs`	array	No	The list of members this member can hand off to, and when. Empty or absent means this member cannot hand off (a terminal member).

The first member in the members array is the one who answers the call.

How Handoffs Work

Each entry in a member’s handoffs array is a condition pointing at another member:

Field	Type	Required	Description
`to`	string	Yes	The `id` of the member to hand off to. Must be another member in the same crew.
`when`	string	Yes	Plain text describing the condition for this handoff, up to 300 characters.

The when text is descriptive, not code. Write it the way you would explain the condition to a person, for example “the caller wants to book a specific appointment time” or “the caller is asking a detailed product question.”

Handoff Guards

Three checks apply to every handoff, so a crew cannot loop or run away with a call:

Only listed destinations. A member can only hand off to a member listed in its own handoffs. A handoff to any other member, or to an id that does not exist in the crew, does not happen.
Handoff limit. Each crew has a maximum number of handoffs allowed in a single call. This is set with max_handoffs, an integer from 1 to 10. If you don’t set it, the default is 3. Once a call reaches the limit, no further handoffs happen for the rest of that call.
No immediate bounce-back. A member cannot immediately hand a call back to the member who just handed it to them. This prevents two members from passing the call back and forth on the same turn.

Invalid Configuration Falls Back to a Single Agent

If a crew configuration does not meet the requirements described here (for example, too few or too many members, a missing field, or a handoff pointing at an id that doesn’t exist), the call does not fail. It runs as a normal single-agent call using the first member’s instructions, and the invalid crew configuration is skipped for that call.

Limits

Limit	Value
Members per crew	2 to 5
Instructions per member	up to 8000 characters
`when` condition length	up to 300 characters
`max_handoffs`	1 to 10 (default 3)

Example

A crew is set inside the config object of a campaign, under the crew key:

{
  "config": {
    "mode": "legacy",
    "mcp_tool_allowlist": ["book_appointment", "send_pricing_link"],
    "crew": {
      "max_handoffs": 3,
      "members": [
        {
          "id": "intro",
          "name": "Alex",
          "instructions": "You are Alex, the first point of contact. Greet the caller, confirm who you're speaking with, and find out whether they want to book an appointment or ask a question 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": "You are Jordan, the scheduling specialist. Confirm the caller's preferred date and time and lock in the appointment.",
          "use_knowledge_base": false,
          "mcp_tool_allowlist": ["book_appointment"]
        },
        {
          "id": "pricing",
          "name": "Sam",
          "instructions": "You are Sam, the pricing specialist. Answer pricing questions using the knowledge base and offer to transfer back to booking once the caller is ready.",
          "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

A crew can also be set directly on an individual call at call creation, using the same crew object shape, instead of at the campaign level.

Getting Started

Core Concepts

Guides

Use Cases

Integrations

What Is a Crew?

Crew Members

How Handoffs Work

Handoff Guards

Invalid Configuration Falls Back to a Single Agent

Limits

Example

Setting Crew Per Call

Next Steps

Campaign Management

AI & Voice Customization

​What Is a Crew?

​Crew Members

​How Handoffs Work

​Handoff Guards

​Invalid Configuration Falls Back to a Single Agent

​Limits

​Example

​Setting Crew Per Call

​Next Steps

Campaign Management

AI & Voice Customization

What Is a Crew?

Crew Members

How Handoffs Work

Handoff Guards

Invalid Configuration Falls Back to a Single Agent

Limits

Example

Setting Crew Per Call

Next Steps