[Lanre Shittu (Shizoqua)]

Motivation & Context

HandoffBuilder named each handoff tool handoff_to_<agent name> without checking the name. An agent called "Billing Agent" produced handoff_to_Billing Agent, which OpenAI, Anthropic and Bedrock reject because tool names may only contain letters, digits, underscores and dashes.

Description & Review Guide

• What are the major changes? get_handoff_tool_name now replaces any other character with an underscore. The builder also raises when two targets end up with the same tool name, instead of one silently overwriting the other.
• What is the impact of these changes? Handoff workflows work with agent names that contain spaces or dots. Names that were already valid keep the same tool name, so existing prompts that mention handoff_to_<name> are unaffected.
• What do you want reviewers to focus on? Whether raising on a name collision is the right call, or if a suffix would be preferred.

Related Issue

Fixes #9034

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix), and a workflow keeps the label and title prefix in sync automatically.

[Copilot]

Copilot review overview

🟡 Changes recommended

Generated names can still exceed providers’ 64-character limit.

Review effort: Balanced
Findings: 1

Open (1)

• Cap generated handoff names at the providers' 64-character limit · New

What changed in this PR

Sanitizes generated handoff tool names for provider compatibility and detects normalization collisions.

Changes:

• Replaces unsupported characters with underscores.
• Rejects colliding generated names.
• Adds unit and workflow coverage.

File	Description
_handoff.py	Implements sanitization and collision detection.
test_handoff.py	Tests sanitized names, routing, and collisions.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.