> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topcalls.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Crew (Multi-Agent Handoffs)
> Run a call with multiple specialised agents that hand off to each other under controlled conditions.
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:
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
| 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:
```json theme={null}
{
"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
Learn how crew fits into campaign configuration.
Learn how to write effective instructions for a single agent.