Python: feat: Add create_handoff_tools() for Azure AI Agent Service compatibility

[frdeange]

Summary

This PR addresses issue #3713 where HandoffBuilder raised ValueError when users pre-created handoff tools for Azure AI Agent Service compatibility.

Problem

When using Azure AI Agent Service, tools must be registered at agent creation time (via AzureAIClient.create_agent()), not at request time. The current HandoffBuilder implementation creates handoff tools at workflow build time and raises ValueError if tools with the same names already exist:

raise ValueError(
    f"Agent '{resolve_agent_id(agent)}' already has a tool named '{tool.name}'. "
    f"Handoff tool name '{tool.name}' conflicts with existing tool."
)

This prevents users from pre-creating handoff tools for Azure compatibility.

Solution

1. Add create_handoff_tools() function: A public helper that creates handoff tools compatible with the framework's internal structure. Users can call this before creating their agents and include the tools in default_options.tools.

2. Modify _apply_auto_tools() to skip duplicates: Instead of raising ValueError, the method now logs a debug message and skips creating duplicate tools using continue.

3. Export new functions: Both create_handoff_tools and get_handoff_tool_name are now part of the public API.

Usage Example

from agent_framework import ChatAgent, HandoffBuilder, create_handoff_tools

# Pre-create handoff tools for Azure AI Agent Service compatibility
handoff_tools = create_handoff_tools(
    ["specialist", "escalation"],
    descriptions={
        "specialist": "Route to specialist for technical issues",
        "escalation": "Escalate to supervisor for complex cases",
    },
)

# Create agent with Azure AI Agent Service
agent_definition = azure_project.agents.create_agent(
    name="triage",
    model="gpt-4o",
    instructions="...",
    tools=[t.metadata for t in handoff_tools],  # Pre-register tools
)

# Create ChatAgent with pre-registered tools
triage = ChatAgent(
    chat_client=azure_client,
    name="triage",
    default_options={"tools": handoff_tools},
)

# HandoffBuilder will skip duplicate tools automatically
workflow = (
    HandoffBuilder(participants=[triage, specialist, escalation])
    .with_start_agent(triage)
    .build()
)

Changes

• _handoff.py:

  • Added create_handoff_tools() function (lines 120-186)
  • Modified _apply_auto_tools() to use continue instead of raise ValueError (lines 405-416)

• _workflows/__init__.py:

  • Added exports for create_handoff_tools and get_handoff_tool_name

• tests/workflow/test_handoff.py:

  • Added 4 new tests covering the Azure AI compatibility scenario

Testing

All 30 tests in test_handoff.py pass:

packages/core/tests/workflow/test_handoff.py ........................... [100%]
============================= 30 passed in 44.49s ==============================

Checklist

• Tests added
• Documentation in docstrings
• Lint checks pass (poe lint)
• Type checks pass (poe pyright)

Fixes #3713

[Copilot]

Pull request overview

This PR addresses issue #3713 by enabling HandoffBuilder to work with Azure AI Agent Service, which requires tools to be registered at agent creation time rather than request time. The solution adds a public create_handoff_tools() helper function that users can call to pre-create handoff tools before agent creation, and modifies the builder to skip (rather than error on) duplicate tools.

Changes:

• Added create_handoff_tools() function to generate handoff tools compatible with the framework's internal structure
• Modified _apply_auto_tools() to log and skip duplicate tools instead of raising ValueError
• Exported create_handoff_tools and get_handoff_tool_name in the public API

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
python/packages/core/agent_framework/_workflows/_handoff.py	Implements create_handoff_tools() function and modifies duplicate tool handling to use continue instead of raising ValueError
python/packages/core/agent_framework/_workflows/init.py	Adds exports for create_handoff_tools and get_handoff_tool_name to public API
python/packages/core/tests/workflow/test_handoff.py	Adds 4 comprehensive tests covering Azure AI compatibility scenarios including pre-created tools and integration testing
python/packages/declarative/README.md	Comprehensive documentation update (appears unrelated to PR's stated purpose)

[markwallace-microsoft]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/orchestrations/agent_framework_orchestrations
_handoff.py	337	56	83%	104–105, 107, 153, 176–177, 199–209, 211, 213, 215, 220, 318, 398, 426, 434–435, 449, 500–501, 533, 573–575, 580–582, 698, 701, 708, 713, 775, 780, 787, 797, 799, 818, 820, 902–903, 935–936, 1018, 1025, 1097–1098, 1100
TOTAL	21135	3255	84%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
4078	225 💤	0 ❌	0 🔥	1m 11s ⏱️

[TaoChenOSU]

Hi @frdeange,

Thanks for your contribution!

I am surprised that your sample would work.

The handoff workflow creates a mesh topology by default where all nodes are connected to each other. In your sample, you didn't create tool for the specialist and escalation to handoff to triage. The system internal will still attempt to create handoff tools for specialist and escalation to handoff to triage, which will fail.

I think we need a way to let the builder know not to create the handoff tools at all.

[frdeange]

Hello @TaoChenOSU!

Thanks for your time checking this!!!

Actually, let me say it works.... I have the example running right now using this method (before the latest updates I have see right now in the breaking_changes :-(

Here is tracing for the router agent handoff tool execution

And the abseceAgent giving back to routerAgent after solving situation with user:

So yes, it works....

[moonbox3]

Hi @frdeange, thanks for working on this. Could you help check for conflicts between main and this branch?

[frdeange]

Hi @frdeange, thanks for working on this. Could you help check for conflicts between main and this branch?

Thanks for your incredible effort @moonbox3 and team!!!

I have updated the PR to the latest version of the repo with the renaming functions and libraries structure. Now it pass all the test.

Thanks again!

[moonbox3]

Hi @frdeange, thanks for working on this. We actually have an easier solution to use the Foundry agents with orchestration patterns. I will get a PR out soon that shows this - and requires no extra helper functions.

[moonbox3]

Closing in favor of #3873.