AssistantsToolsHandoff tool

Troubleshoot handoffs

Diagnose handoffs that never fire, starting with the system prompt

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

1# System context
2
3You are part of a multi-agent system designed to make agent coordination and execution easy.
4Agents uses two primary abstraction: **Agents** and **Handoffs**. An agent encompasses
5instructions and tools and can hand off a conversation to another agent when appropriate.
6Handoffs are achieved by calling a handoff function, generally named `handoff_to_<agent_name>`.
7Handoffs between agents are handled seamlessly in the background; do not mention or draw
8attention to these handoffs in your conversation with the user.
9
10# Agent context
11
12{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)