> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Troubleshoot handoffs

> Fix handoffs that never fire or route to the wrong assistant, starting with the system prompt instructions that tell the model when to call the handoff tool.

A handoff that never fires is almost always a prompting problem rather than a configuration one. The model has to be told when to call the tool. Start with the system prompt guidance below, then work through the remaining checks.

## System prompt best practices

When using the Handoff tool, add this to your system prompt for optimal agent coordination (adapted from the [OpenAI Agents Handoff Prompt](https://openai.github.io/openai-agents-python/ref/extensions/handoff_prompt/)):

```markdown
# System context

You are part of a multi-agent system designed to make agent coordination and execution easy.
Agents uses two primary abstraction: **Agents** and **Handoffs**. An agent encompasses
instructions and tools and can hand off a conversation to another agent when appropriate.
Handoffs are achieved by calling a handoff function, generally named `handoff_to_<agent_name>`.
Handoffs between agents are handled seamlessly in the background; do not mention or draw
attention to these handoffs in your conversation with the user.

# Agent context

{put your agent system prompt here}
```

## Best practices

1. **Clear descriptions**: Write specific, actionable descriptions for each destination in your system prompt. Use `tool.function.name` to customize the name of the function to reference in your prompt.
2. **Context management**: Use `lastNMessages` or `userAndAssistantMessages` to limit context size for performance.
3. **Model optimization**: Use multiple tools for OpenAI, single tool for Anthropic.
4. **Variable extraction**: Extract key data before handoff to maintain context across assistants.
5. **Tool messages**: Add custom `request-start` messages to set caller expectations during transfers.
6. **Testing**: Test handoff scenarios thoroughly, including edge cases and rejection conditions.
7. **Monitoring and analysis**: Enable [`artifactPlan.fullMessageHistoryEnabled`](/api-reference/assistants/create#response.body.artifactPlan.fullMessageHistoryEnabled) to capture the complete message history across all handoffs in your artifacts. See [squad artifact behavior](/assistants/call-recording#squad-and-transfer-behavior) for details.

## Troubleshooting

* Ensure assistant IDs are valid and accessible
* Verify webhook server URLs are reachable and return the proper format
* Check that required parameters in custom functions match destinations
* Monitor context size to avoid token limits
* Test variable extraction schemas with sample data
* Validate that assistant names exist in the same squad
* Verify rejection plan conditions use correct regex syntax (remember to double-escape `\\` in JSON)

### Destination assistant ignores part of its system prompt

If a destination assistant has more than one system message in `model.messages`, only the first system message is sent to the model after a handoff. Any additional system messages are dropped. The same assistant follows all of its instructions when you call it directly.

To fix this, combine all system instructions into a single system message. Use the [`model`](/api-reference/assistants/update#request.body.model) field of the [Update Assistant](/api-reference/assistants/update) endpoint to replace `model.messages` with one system message. Include the full `model` object in your request, since the update replaces the existing `model` configuration.

For example, this configuration loses the second system message after a handoff:

```json
{
  "model": {
    "messages": [
      {
        "role": "system",
        "content": "You are a support agent for Acme."
      },
      {
        "role": "system",
        "content": "Only discuss billing questions."
      }
    ]
  }
}
```

Combine the instructions into one system message instead:

```json
{
  "model": {
    "messages": [
      {
        "role": "system",
        "content": "You are a support agent for Acme.\n\nOnly discuss billing questions."
      }
    ]
  }
}
```