[AI] [Projects] Add Connected Agent Tool definition and sample (#40629)

* [AI] [Projects] add ConnectedAgentTool and sample

* add connected agent sample

* update sample to delete connected agent

* fix typo

Author: glharper

sdk/ai/azure-ai-projects/azure/ai/projects/models/_patch.py

@@ -55,6 +55,8 @@
     BingGroundingToolDefinition,
     CodeInterpreterToolDefinition,
     CodeInterpreterToolResource,
+    ConnectedAgentToolDefinition,
+    ConnectedAgentDetails,
     FileSearchToolDefinition,
     FileSearchToolResource,
     FunctionDefinition,
@@ -1086,6 +1088,48 @@ def resources(self) -> ToolResources:
     def execute(self, tool_call: Any) -> Any:
         pass
 
+class ConnectedAgentTool(Tool[ConnectedAgentToolDefinition]):
+    """
+    A tool that connects to a sub-agent, with a description describing the conditions
+    or domain where the sub-agent would be called.
+    """
+    def __init__(self, id: str, name: str, description: str):
+        """
+        Initialize ConnectedAgentTool with an id, name, and description. 
+        
+        :param id: The ID of the connected agent.
+        :param name: The name of the connected agent.
+        :param description: The description of the connected agent, used by the calling agent
+           to determine when to call the connected agent.
+        """
+        self.connected_agent = ConnectedAgentDetails(id=id, name=name, description=description)
+
+    @property
+    def definitions(self) -> List[ConnectedAgentToolDefinition]:
+        """
+        Get the connected agent tool definitions.
+
+        :rtype: List[ToolDefinition]
+        """
+        return [ConnectedAgentToolDefinition(connected_agent=self.connected_agent)]
+
+    @property
+    def resources(self) -> ToolResources:
+        """
+        Get the tool resources for the agent.
+
+        :return: An empty ToolResources as ConnectedAgentTool doesn't have specific resources.
+        :rtype: ToolResources
+        """
+        return ToolResources()
+
+    def execute(self, tool_call: Any) -> None:
+        """
+        ConnectedAgentTool does not execute client-side.
+
+        :param Any tool_call: The tool call to execute.
+        :type tool_call: Any
+        """
 
 class FabricTool(ConnectionTool[MicrosoftFabricToolDefinition]):
     """
@@ -1917,6 +1961,7 @@ def get_last_text_message_by_role(self, role: MessageRole) -> Optional[MessageTe
     "BaseAsyncAgentEventHandler",
     "BaseAgentEventHandler",
     "CodeInterpreterTool",
+    "ConnectedAgentTool",
     "ConnectionProperties",
     "AsyncAgentEventHandler",
     "OpenAIPageableListOfThreadMessage",

sdk/ai/azure-ai-projects/samples/agents/sample_agents_connected_agent.py

@@ -0,0 +1,97 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+
+"""
+DESCRIPTION:
+    This sample demonstrates how to use Agent operations with the Connected Agent tool from
+    the Azure Agents service using a synchronous client.
+
+USAGE:
+    python sample_agents_connected_agent.py
+
+    Before running the sample:
+
+    pip install azure-ai-projects azure-identity
+
+    Set these environment variables with your own values:
+    1) PROJECT_CONNECTION_STRING - The project connection string, as found in the overview page of your
+       Azure AI Foundry project.
+    2) MODEL_DEPLOYMENT_NAME - The deployment name of the AI model, as found under the "Name" column in 
+       the "Models + endpoints" tab in your Azure AI Foundry project.
+"""
+
+import os
+from azure.ai.projects import AIProjectClient
+from azure.ai.projects.models import ConnectedAgentTool, MessageRole
+from azure.identity import DefaultAzureCredential
+
+
+project_client = AIProjectClient.from_connection_string(
+    credential=DefaultAzureCredential(),
+    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
+)
+
+connected_agent_name = "stock_price_bot"
+
+stock_price_agent = project_client.agents.create_agent( 
+    model=os.environ["MODEL_DEPLOYMENT_NAME"],
+    name=connected_agent_name, 
+    instructions=( 
+        "Your job is to get the stock price of a company. If you don't know the realtime stock price, return the last known stock price." 
+    ), 
+) 
+
+# [START create_agent_with_connected_agent_tool]
+# Initialize Connected Agent tool with the agent id, name, and description
+connected_agent = ConnectedAgentTool(id=stock_price_agent.id, name=connected_agent_name, description="Gets the stock price of a company")
+
+# Create agent with the Connected Agent tool and process assistant run
+with project_client:
+    agent = project_client.agents.create_agent(
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
+        name="my-assistant",
+        instructions="You are a helpful assistant, and use the connected agent to get stock prices.",
+        tools=connected_agent.definitions,
+    )
+    # [END create_agent_with_connected_agent_tool]
+
+    print(f"Created agent, ID: {agent.id}")
+
+    # Create thread for communication
+    thread = project_client.agents.create_thread()
+    print(f"Created thread, ID: {thread.id}")
+
+    # Create message to thread
+    message = project_client.agents.create_message(
+        thread_id=thread.id,
+        role=MessageRole.USER,
+        content="What is the stock price of Microsoft?",
+    )
+    print(f"Created message, ID: {message.id}")
+
+    # Create and process Agent run in thread with tools
+    run = project_client.agents.create_and_process_run(thread_id=thread.id, agent_id=agent.id)
+    print(f"Run finished with status: {run.status}")
+
+    if run.status == "failed":
+        print(f"Run failed: {run.last_error}")
+
+    # Delete the Agent when done
+    project_client.agents.delete_agent(agent.id)
+    print("Deleted agent")
+
+    # Delete the connected Agent when done
+    project_client.agents.delete_agent(stock_price_agent.id)
+    print("Deleted connected agent")
+
+    # Print the Agent's response message with optional citation
+    response_message = project_client.agents.list_messages(thread_id=thread.id).get_last_message_by_role(
+        MessageRole.AGENT
+    )
+    if response_message:
+        for text_message in response_message.text_messages:
+            print(f"Agent response: {text_message.text.value}")
+        for annotation in response_message.url_citation_annotations:
+            print(f"URL Citation: [{annotation.url_citation.title}]({annotation.url_citation.url})")