Troubleshoot handoffs

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):

# 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 to capture the complete message history across all handoffs in your artifacts. See squad artifact 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 field of the Update Assistant 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:

{
  "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:

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