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

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

Changes:
- Add create_handoff_tools() function to pre-create handoff tools that can
  be registered at agent creation time (required for Azure AI Agent Service)
- Modify _apply_auto_tools() to skip duplicate tools instead of raising
  ValueError, logging a debug message instead
- Export create_handoff_tools and get_handoff_tool_name from the public API
- Add comprehensive tests for the new functionality

The Azure AI Agent Service requires tools to be registered at agent creation
time, not at request time. This change allows users to pre-create handoff
tools and include them in the agent's default_options.tools list.

Fixes #3713

Author: frdeange

python/packages/core/agent_framework/_workflows/__init__.py

@@ -73,7 +73,13 @@
     GroupChatBuilder,
     GroupChatState,
 )
-from ._handoff import HandoffAgentUserRequest, HandoffBuilder, HandoffSentEvent
+from ._handoff import (
+    HandoffAgentUserRequest,
+    HandoffBuilder,
+    HandoffSentEvent,
+    create_handoff_tools,
+    get_handoff_tool_name,
+)
 from ._magentic import (
     ORCH_MSG_KIND_INSTRUCTION,
     ORCH_MSG_KIND_NOTICE,
@@ -215,8 +221,10 @@
     "WorkflowValidationError",
     "WorkflowViz",
     "create_edge_runner",
+    "create_handoff_tools",
     "executor",
     "get_checkpoint_summary",
+    "get_handoff_tool_name",
     "handler",
     "resolve_agent_id",
     "response_handler",

python/packages/core/agent_framework/_workflows/_handoff.py

@@ -122,6 +122,76 @@ def get_handoff_tool_name(target_id: str) -> str:
     return f"handoff_to_{target_id}"
 
 
+def create_handoff_tools(
+    target_agent_ids: Sequence[str],
+    descriptions: Mapping[str, str] | None = None,
+) -> list[FunctionTool[Any, Any]]:
+    """Create handoff tools for pre-registration with agents.
+
+    This function is particularly useful when using Azure AI Agent Service or other
+    providers that require tools to be registered at agent creation time rather than
+    at request time. By pre-creating handoff tools, you can include them in the agent's
+    tool list when creating the agent.
+
+    The HandoffBuilder will automatically detect pre-existing handoff tools and skip
+    creating duplicates, ensuring seamless integration.
+
+    Args:
+        target_agent_ids: Sequence of target agent identifiers that can be handed off to.
+        descriptions: Optional mapping of agent IDs to custom tool descriptions.
+                     If not provided, a default description will be used.
+
+    Returns:
+        List of FunctionTool instances ready for use with ChatAgent.
+
+    Example:
+        .. code-block:: python
+
+            from agent_framework import ChatAgent
+            from agent_framework._workflows._handoff import 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",
+                },
+            )
+
+            # Include tools when creating the agent
+            agent = ChatAgent(
+                chat_client=azure_client,
+                name="triage",
+                default_options={"tools": handoff_tools + other_tools},
+            )
+
+    See Also:
+        - `get_handoff_tool_name`: Get the standardized tool name for a target agent.
+        - `HandoffBuilder`: Builder for creating handoff workflows.
+    """
+    descriptions = descriptions or {}
+    tools: list[FunctionTool[Any, Any]] = []
+
+    for target_id in target_agent_ids:
+        tool_name = get_handoff_tool_name(target_id)
+        doc = descriptions.get(target_id) or f"Handoff to the {target_id} agent."
+
+        # Note: approval_mode is set to "never_require" for handoff tools because
+        # they are framework-internal signals that trigger routing logic, not
+        # actual function executions. They are automatically intercepted by
+        # _AutoHandoffMiddleware which short-circuits execution and provides synthetic
+        # results, so the function body never actually runs in practice.
+        @tool(name=tool_name, description=doc, approval_mode="never_require")
+        def _handoff_tool(context: str | None = None, *, _target: str = target_id) -> str:
+            """Return a deterministic acknowledgement that encodes the target alias."""
+            return f"Handoff to {_target}"
+
+        tools.append(_handoff_tool)
+
+    return tools
+
+
 HANDOFF_FUNCTION_RESULT_KEY = "handoff_to"
 
 
@@ -335,11 +405,15 @@ def _apply_auto_tools(self, agent: ChatAgent, targets: Sequence[HandoffConfigura
         for target in targets:
             tool = self._create_handoff_tool(target.target_id, target.description)
             if tool.name in existing_names:
-                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."
-                    "Please rename the existing tool or modify the target agent ID to avoid conflicts."
+                # Skip adding duplicate tools - this supports Azure AI Agent Service
+                # where users pre-create handoff tools using create_handoff_tools()
+                # and register them at agent creation time.
+                logger.debug(
+                    "Handoff tool '%s' already exists for agent '%s', skipping duplicate creation.",
+                    tool.name,
+                    resolve_agent_id(agent),
                 )
+                continue
             new_tools.append(tool)
 
         if new_tools:

python/packages/core/tests/workflow/test_handoff.py

@@ -707,3 +707,135 @@ def create_specialist() -> MockHandoffAgent:
 
 
 # endregion Participant Factory Tests
+
+
+# region Azure AI Agent Service Compatibility Tests (Issue #3713)
+
+
+def test_handoff_skips_existing_tools_without_error():
+    """Test that pre-existing handoff tools are skipped without raising ValueError.
+
+    This test addresses the Azure AI Agent Service compatibility issue where tools
+    must be registered at agent creation time, not at request time.
+    Users can pre-create handoff tools using create_handoff_tools() and the builder
+    should skip duplicates instead of raising ValueError.
+
+    See: https://github.com/microsoft/agent-framework/issues/3713
+    """
+    from agent_framework._workflows._handoff import create_handoff_tools, get_handoff_tool_name
+
+    # Create handoff tools that will be pre-registered with the agent
+    pre_created_tools = create_handoff_tools(["specialist", "escalation"])
+
+    # Verify tools were created with correct names
+    tool_names = [t.name for t in pre_created_tools]
+    assert get_handoff_tool_name("specialist") in tool_names
+    assert get_handoff_tool_name("escalation") in tool_names
+
+    # Create a MockChatClient that has the pre-created tools
+    from agent_framework import ChatAgent
+
+    class PreTooledMockChatClient(MockChatClient):
+        """Mock client where agent has pre-registered handoff tools."""
+
+        def __init__(self, name: str, handoff_to: str | None = None) -> None:
+            super().__init__(name, handoff_to=handoff_to)
+
+    # Create agent with pre-registered handoff tools in default_options
+    triage = ChatAgent(
+        chat_client=PreTooledMockChatClient("triage", handoff_to="specialist"),
+        name="triage",
+        id="triage",
+        default_options={"tools": pre_created_tools},
+    )
+    specialist = MockHandoffAgent(name="specialist", handoff_to="escalation")
+    escalation = MockHandoffAgent(name="escalation")
+
+    # This should NOT raise ValueError - the builder should skip existing tools
+    workflow = (
+        HandoffBuilder(participants=[triage, specialist, escalation])
+        .with_start_agent(triage)
+        .with_termination_condition(lambda conv: len(conv) >= 3)
+        .build()
+    )
+
+    # Verify the workflow was built successfully
+    assert "triage" in workflow.executors
+    assert "specialist" in workflow.executors
+    assert "escalation" in workflow.executors
+
+
+def test_create_handoff_tools_returns_correct_tools():
+    """Test that create_handoff_tools creates FunctionTool objects with correct names and descriptions."""
+    from agent_framework._workflows._handoff import create_handoff_tools, get_handoff_tool_name
+
+    tools = create_handoff_tools(
+        ["agent_a", "agent_b"],
+        descriptions={"agent_a": "Route to Agent A for billing", "agent_b": "Route to Agent B for tech support"},
+    )
+
+    assert len(tools) == 2
+
+    tool_by_name = {t.name: t for t in tools}
+
+    # Check tool names
+    assert get_handoff_tool_name("agent_a") in tool_by_name
+    assert get_handoff_tool_name("agent_b") in tool_by_name
+
+    # Check descriptions
+    assert tool_by_name[get_handoff_tool_name("agent_a")].description == "Route to Agent A for billing"
+    assert tool_by_name[get_handoff_tool_name("agent_b")].description == "Route to Agent B for tech support"
+
+
+def test_create_handoff_tools_default_descriptions():
+    """Test that create_handoff_tools uses default descriptions when not provided."""
+    from agent_framework._workflows._handoff import create_handoff_tools
+
+    tools = create_handoff_tools(["my_agent"])
+
+    assert len(tools) == 1
+    assert tools[0].description == "Handoff to the my_agent agent."
+
+
+async def test_workflow_with_pre_created_tools_executes_correctly():
+    """Integration test: workflow with pre-created handoff tools executes handoffs correctly."""
+    from agent_framework import ChatAgent
+    from agent_framework._workflows._handoff import create_handoff_tools
+
+    # Pre-create handoff tools for Azure AI Agent Service compatibility
+    triage_tools = create_handoff_tools(["specialist"])
+    specialist_tools = create_handoff_tools(["escalation"])
+
+    # Create agents with pre-registered tools
+    triage = ChatAgent(
+        chat_client=MockChatClient("triage", handoff_to="specialist"),
+        name="triage",
+        id="triage",
+        default_options={"tools": triage_tools},
+    )
+    specialist = ChatAgent(
+        chat_client=MockChatClient("specialist", handoff_to="escalation"),
+        name="specialist",
+        id="specialist",
+        default_options={"tools": specialist_tools},
+    )
+    escalation = MockHandoffAgent(name="escalation")
+
+    workflow = (
+        HandoffBuilder(participants=[triage, specialist, escalation])
+        .with_start_agent(triage)
+        .with_termination_condition(lambda conv: sum(1 for m in conv if m.role == "user") >= 2)
+        .build()
+    )
+
+    # Execute the workflow - should complete without errors
+    events = await _drain(workflow.run_stream("Need help"))
+    requests = [ev for ev in events if isinstance(ev, RequestInfoEvent)]
+
+    # Workflow should reach escalation agent and request user input
+    assert requests
+    assert len(requests) == 1
+    assert requests[0].source_executor_id == escalation.name
+
+
+# endregion Azure AI Agent Service Compatibility Tests