Skip to main content
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:
FieldTypeRequiredDescription
idstringYesShort identifier for the member, unique within the crew.
namestringYesDisplay name for the member (for example, “Alex”).
instructionsstringYesThis member’s own instructions, up to 8000 characters.
use_knowledge_basebooleanNoWhen 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_idsarrayNoOptional 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_allowlistarrayNoOptional 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.
handoffsarrayNoThe 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:
FieldTypeRequiredDescription
tostringYesThe id of the member to hand off to. Must be another member in the same crew.
whenstringYesPlain 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:
  1. 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.
  2. 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.
  3. 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

LimitValue
Members per crew2 to 5
Instructions per memberup to 8000 characters
when condition lengthup to 300 characters
max_handoffs1 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.

​
Next Steps

Campaign Management

Learn how crew fits into campaign configuration.

AI & Voice Customization

Learn how to write effective instructions for a single agent.