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

This PR adds support for Azure AI Agent Service and other providers that
require tools to be registered at agent creation time.

Changes:
- Add create_handoff_tools() function to pre-create handoff FunctionTools
- Modify _apply_auto_tools() to skip duplicates instead of raising ValueError
- Add get_handoff_tool_name() to public exports
- Add tests for Azure AI compatibility scenario

The create_handoff_tools() function allows users to pre-create handoff
tools that can be included in the agent's default_options when creating
agents with Azure AI Agent Service. The HandoffBuilder now detects
pre-existing handoff tools and gracefully skips creating duplicates,
logging a debug message instead of raising an error.

Fixes #3713

Author: frdeange

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

@@ -17,6 +17,8 @@
     "HandoffBuilder",
     "HandoffConfiguration",
     "HandoffSentEvent",
+    "create_handoff_tools",
+    "get_handoff_tool_name",
     # Base orchestrator
     "BaseGroupChatOrchestrator",
     "GroupChatRequestMessage",

python/packages/core/agent_framework/orchestrations/__init__.pyi

@@ -36,6 +36,8 @@ from agent_framework_orchestrations import (
     SequentialBuilder,
     StandardMagenticManager,
     __version__,
+    create_handoff_tools,
+    get_handoff_tool_name,
 )
 
 __all__ = [
@@ -74,4 +76,6 @@ __all__ = [
     "SequentialBuilder",
     "StandardMagenticManager",
     "__version__",
+    "create_handoff_tools",
+    "get_handoff_tool_name",
 ]

python/packages/orchestrations/agent_framework_orchestrations/__init__.py

@@ -39,6 +39,8 @@
     HandoffBuilder,
     HandoffConfiguration,
     HandoffSentEvent,
+    create_handoff_tools,
+    get_handoff_tool_name,
 )
 from ._magentic import (
     MAGENTIC_MANAGER_NAME,
@@ -107,4 +109,6 @@
     "__version__",
     "clean_conversation_for_handoff",
     "create_completion_message",
+    "create_handoff_tools",
+    "get_handoff_tool_name",
 ]

python/packages/orchestrations/agent_framework_orchestrations/_handoff.py

@@ -116,6 +116,75 @@ 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.orchestrations 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"
 
 
@@ -331,11 +400,15 @@ def _apply_auto_tools(self, agent: ChatAgent, targets: Sequence[HandoffConfigura
         for target in targets:
             handoff_tool = self._create_handoff_tool(target.target_id, target.description)
             if handoff_tool.name in existing_names:
-                raise ValueError(
-                    f"Agent '{resolve_agent_id(agent)}' already has a tool named '{handoff_tool.name}'. "
-                    f"Handoff tool name '{handoff_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.",
+                    handoff_tool.name,
+                    resolve_agent_id(agent),
                 )
+                continue
             new_tools.append(handoff_tool)
 
         if new_tools:

python/packages/orchestrations/tests/test_handoff.py

@@ -727,3 +727,83 @@ def create_specialist() -> MockHandoffAgent:
 
 
 # endregion Participant Factory Tests
+
+
+# region Azure AI Agent Service Compatibility Tests
+
+
+def test_create_handoff_tools_basic():
+    """Test that create_handoff_tools creates tools with correct names and descriptions."""
+    from agent_framework.orchestrations import create_handoff_tools, get_handoff_tool_name
+
+    target_ids = ["specialist", "escalation"]
+    tools = create_handoff_tools(target_ids)
+
+    assert len(tools) == 2
+    assert tools[0].name == get_handoff_tool_name("specialist")
+    assert tools[1].name == get_handoff_tool_name("escalation")
+    assert "specialist" in tools[0].description.lower()
+    assert "escalation" in tools[1].description.lower()
+
+
+def test_create_handoff_tools_with_custom_descriptions():
+    """Test that create_handoff_tools accepts custom descriptions."""
+    from agent_framework.orchestrations import create_handoff_tools
+
+    target_ids = ["specialist", "escalation"]
+    descriptions = {
+        "specialist": "Route to technical specialist for complex issues",
+        "escalation": "Escalate to supervisor for urgent matters",
+    }
+    tools = create_handoff_tools(target_ids, descriptions=descriptions)
+
+    assert len(tools) == 2
+    assert tools[0].description == descriptions["specialist"]
+    assert tools[1].description == descriptions["escalation"]
+
+
+def test_get_handoff_tool_name():
+    """Test that get_handoff_tool_name returns consistent naming."""
+    from agent_framework.orchestrations import get_handoff_tool_name
+
+    assert get_handoff_tool_name("specialist") == "handoff_to_specialist"
+    assert get_handoff_tool_name("my_agent") == "handoff_to_my_agent"
+
+
+def test_handoff_builder_skips_duplicate_tools():
+    """Test that HandoffBuilder skips adding duplicate handoff tools.
+
+    This is crucial for Azure AI Agent Service compatibility where users
+    pre-create handoff tools using create_handoff_tools() and register
+    them at agent creation time.
+    """
+    from agent_framework.orchestrations import create_handoff_tools
+
+    # Pre-create handoff tools (simulating Azure AI Agent Service pattern)
+    pre_created_tools = create_handoff_tools(["specialist"])
+
+    # Create agent with pre-created tools
+    triage_client = MockChatClient(name="triage", handoff_to="specialist")
+    triage = ChatAgent(
+        chat_client=triage_client,
+        name="triage",
+        default_options={"tools": pre_created_tools},
+    )
+
+    specialist_client = MockChatClient(name="specialist")
+    specialist = ChatAgent(chat_client=specialist_client, name="specialist")
+
+    # Build workflow - should NOT raise ValueError for duplicate tools
+    workflow = (
+        HandoffBuilder()
+        .participants([triage, specialist])
+        .with_start_agent(triage)
+        .add_handoff(triage, [specialist])
+        .build()
+    )
+
+    # Verify workflow was built successfully
+    assert workflow is not None
+
+
+# endregion Azure AI Agent Service Compatibility Tests