Harden default handoff tool name normalization

[Mark Zhang (shuofengzhang)]

What changed

• Hardened _normalize_agent_name in langgraph_swarm/handoff.py so default handoff tool names are safe for provider tool/function naming constraints:
  • keep lowercase + whitespace-to-underscore behavior
  • replace non [a-z0-9_] characters with _
  • collapse repeated underscores and trim leading/trailing underscores
  • fallback to agent when normalization would otherwise become empty
• Added regression tests in tests/test_swarm.py:
  • R&D Agent / v2 now normalizes to transfer_to_r_d_agent_v2
  • punctuation-only names (e.g. !!!) now normalize to transfer_to_agent

Why

create_handoff_tool builds a default tool name from agent_name. Previously only whitespace was normalized, so punctuation was preserved. For real-world agent names (R&D Agent, ops/bot, etc.), this can generate tool names that are rejected by some model/tool providers, causing runtime failures during tool binding or invocation.

Insight / Why this matters

Root cause: normalization handled spacing but not invalid symbols. That leaves a hidden integration edge case where swarm setup looks correct, but fails later when the LLM provider validates function names.

Why easy to miss: examples typically use simple names like Alice/Bob, so this only appears with more realistic team-style names and specific providers.

Tradeoff: this slightly changes generated default tool names for punctuation-heavy agent names, but only toward safer/portable identifiers. Explicitly provided name= remains unchanged.

Practical gain / Why this matters

• Improves cross-provider reliability of default handoff tools.
• Reduces setup/debug friction for users naming agents naturally (with spaces/symbols/version tags).
• Keeps scope rollback-safe and low risk (small internal normalization helper + focused tests).

Testing

• ✅ .venv/bin/pytest -q
  • Result: 6 passed