Create an example of connected agent tool with Azure function (#41840)

Author: nick863

sdk/ai/azure-ai-agents/README.md

@@ -37,6 +37,7 @@ To report an issue with the client library, or request additional features, plea
     - [Azure Function Call](#create-agent-with-azure-function-call)
     - [OpenAPI](#create-agent-with-openapi)
     - [Fabric data](#create-an-agent-with-fabric)
+    - [Connected agents](#create-an-agent-using-another-agents)
     - [Deep Research](#create-agent-with-deep-research)
   - [Create thread](#create-thread) with
     - [Tool resource](#create-thread-with-tool-resource)
@@ -801,6 +802,178 @@ with project_client:
 
 <!-- END SNIPPET -->
 
+### Create an Agent using another agents
+
+We can use `ConnectedAgentTool` to call specialized agents. In the example below we will create two agents, one is returning the Microsoft stock price and another returns weather. Note that the `ConnectedAgentTool` does not support local functions, we will use Azure function to return weather. The code of that function is given below; please see [Azure Function Call](#create-agent-with-azure-function-call) section for the instructions on how to deploy Azure Function.
+
+```python
+import azure.functions as func
+import datetime
+import json
+import logging
+
+app = func.FunctionApp()
+
+@app.function_name(name="GetWeather")
+@app.queue_trigger(
+    arg_name="arguments",
+    queue_name="weather-input",
+    connection="AzureWebJobsStorage")
+@app.queue_output(
+    arg_name="outputQueue",
+    queue_name="weather-output",
+    connection="AzureWebJobsStorage")
+def foo(arguments: func.QueueMessage, outputQueue: func.Out[str]) -> None:
+    """
+    The function, answering question about weather.
+
+    :param arguments: The arguments, containing json serialized request.
+    :param outputQueue: The output queue to write messages to.
+    """
+
+    parsed_args = json.loads(arguments.get_body().decode('utf-8'))
+    location = parsed_args.get("Location")
+    try:
+        response = {
+            "Value": "60 degrees and cloudy" if location == "Seattle" else "10 degrees and sunny",
+            "CorrelationId": parsed_args['CorrelationId']
+        }
+        outputQueue.set(json.dumps(response))
+        logging.info(f'The function returns the following message: {json.dumps(response)}')
+    except Exception as e:
+        logging.error(f"Error processing message: {e}")
+        raise
+```
+We will define two agents that has descriptions, explaining when they need to be called.
+
+<!-- SNIPPET:sample_agents_multiple_connected_agents.create_two_toy_agents -->
+
+```python
+connected_agent_name = "stock_price_bot"
+weather_agent_name = "weather_bot"
+
+stock_price_agent = agents_client.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 asked for the Microsoft stock price, always return $350."
+    ),
+)
+
+azure_function_tool = AzureFunctionTool(
+    name="GetWeather",
+    description="Get answers from the weather bot.",
+    parameters={
+        "type": "object",
+        "properties": {
+            "Location": {"type": "string", "description": "The location to get the weather for."},
+        },
+    },
+    input_queue=AzureFunctionStorageQueue(
+        queue_name="weather-input",
+        storage_service_endpoint=storage_service_endpoint,
+    ),
+    output_queue=AzureFunctionStorageQueue(
+        queue_name="weather-output",
+        storage_service_endpoint=storage_service_endpoint,
+    ),
+)
+
+weather_agent = agents_client.create_agent(
+    model=os.environ["MODEL_DEPLOYMENT_NAME"],
+    name=weather_agent_name,
+    instructions=(
+        "Your job is to get the weather for a given location. "
+        "Use the provided function to get the weather in the given location."
+    ),
+    tools=azure_function_tool.definitions,
+)
+
+# Initialize Connected Agent tools 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"
+)
+connected_weather_agent = ConnectedAgentTool(
+    id=weather_agent.id, name=weather_agent_name, description="Gets the weather for a given location"
+)
+```
+
+<!-- END SNIPPET -->
+
+Add the `ConnectedAgentTool`-s to main agent.
+
+<!-- SNIPPET:sample_agents_multiple_connected_agents.create_agent_with_connected_agent_tool -->
+
+```python
+# Create agent with the Connected Agent tool and process assistant run
+agent = agents_client.create_agent(
+    model=os.environ["MODEL_DEPLOYMENT_NAME"],
+    name="my-assistant",
+    instructions="You are a helpful assistant, and use the connected agents to get stock prices and weather.",
+    tools=[
+        connected_agent.definitions[0],
+        connected_weather_agent.definitions[0],
+    ],
+)
+```
+
+<!-- END SNIPPET -->
+
+Create thread and run.
+
+<!-- SNIPPET:sample_agents_multiple_connected_agents.run_agent_with_connected_agent_tool -->
+
+```python
+# Create thread for communication
+thread = agents_client.threads.create()
+print(f"Created thread, ID: {thread.id}")
+
+# Create message to thread
+message = agents_client.messages.create(
+    thread_id=thread.id,
+    role=MessageRole.USER,
+    content="What is the stock price of Microsoft and the weather in Seattle?",
+)
+print(f"Created message, ID: {message.id}")
+
+# Create and process Agent run in thread with tools
+run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
+print(f"Run finished with status: {run.status}")
+```
+
+<!-- END SNIPPET -->
+
+To understand what calls were made by the main agent to the connected ones, we will list run steps.
+
+<!-- SNIPPET:sample_agents_multiple_connected_agents.list_tool_calls -->
+
+```python
+for run_step in agents_client.run_steps.list(thread_id=thread.id, run_id=run.id, order=ListSortOrder.ASCENDING):
+    if isinstance(run_step.step_details, RunStepToolCallDetails):
+        for tool_call in run_step.step_details.tool_calls:
+            print(f"\tAgent: {tool_call._data['connected_agent']['name']} "
+                  f"query: {tool_call._data['connected_agent']['arguments']} ",
+                  f"output: {tool_call._data['connected_agent']['output']}")
+```
+
+<!-- END SNIPPET -->
+
+The messages contain references, marked by unicode opening and closing brackets, which cannot be printed by python `print` command. To fix this issue we will replace them by ASCII brackets.
+
+<!-- SNIPPET:sample_agents_multiple_connected_agents.list_messages -->
+
+```python
+# Fetch and log all messages
+messages = agents_client.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING)
+for msg in messages:
+    if msg.text_messages:
+        last_text = msg.text_messages[-1]
+        text = last_text.text.value.replace('\u3010', '[').replace('\u3011', ']')
+        print(f"{msg.role}: {text}")
+```
+
+<!-- END SNIPPET -->
+
 
 ### Create Thread
 

sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_multiple_connected_agents.py

@@ -21,22 +21,35 @@
                           page of your Azure AI Foundry portal.
     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.
+    3) STORAGE_QUEUE_URI - the storage service queue endpoint, triggering Azure function.
+       Please see Getting Started with Azure Functions page for more information on Azure Functions:
+       https://learn.microsoft.com/azure/azure-functions/functions-get-started
 """
 
 import os
 from azure.ai.projects import AIProjectClient
-from azure.ai.agents.models import ConnectedAgentTool, MessageRole
+from azure.ai.agents.models import (
+    AzureFunctionStorageQueue,
+    AzureFunctionTool,
+    ConnectedAgentTool,
+    ListSortOrder,
+    MessageRole,
+    RunStepToolCallDetails,
+    
+)
 from azure.identity import DefaultAzureCredential
 
 
 project_client = AIProjectClient(
     endpoint=os.environ["PROJECT_ENDPOINT"],
     credential=DefaultAzureCredential(),
 )
+storage_service_endpoint = os.environ["STORAGE_QUEUE_URI"]
 
 with project_client:
     agents_client = project_client.agents
 
+    # [START create_two_toy_agents]
     connected_agent_name = "stock_price_bot"
     weather_agent_name = "weather_bot"
 
@@ -48,12 +61,33 @@
         ),
     )
 
+    azure_function_tool = AzureFunctionTool(
+        name="GetWeather",
+        description="Get answers from the weather bot.",
+        parameters={
+            "type": "object",
+            "properties": {
+                "Location": {"type": "string", "description": "The location to get the weather for."},
+            },
+        },
+        input_queue=AzureFunctionStorageQueue(
+            queue_name="weather-input",
+            storage_service_endpoint=storage_service_endpoint,
+        ),
+        output_queue=AzureFunctionStorageQueue(
+            queue_name="weather-output",
+            storage_service_endpoint=storage_service_endpoint,
+        ),
+    )
+
     weather_agent = agents_client.create_agent(
         model=os.environ["MODEL_DEPLOYMENT_NAME"],
         name=weather_agent_name,
         instructions=(
-            "Your job is to get the weather for a given location. If asked for the weather in Seattle, always return 60 degrees and cloudy."
+            "Your job is to get the weather for a given location. "
+            "Use the provided function to get the weather in the given location."
         ),
+        tools=azure_function_tool.definitions,
     )
 
     # Initialize Connected Agent tools with the agent id, name, and description
@@ -63,7 +97,9 @@
     connected_weather_agent = ConnectedAgentTool(
         id=weather_agent.id, name=weather_agent_name, description="Gets the weather for a given location"
     )
+    # [END create_two_toy_agents]
 
+    # [START create_agent_with_connected_agent_tool]
     # Create agent with the Connected Agent tool and process assistant run
     agent = agents_client.create_agent(
         model=os.environ["MODEL_DEPLOYMENT_NAME"],
@@ -78,6 +114,7 @@
 
     print(f"Created agent, ID: {agent.id}")
 
+    # [START run_agent_with_connected_agent_tool]
     # Create thread for communication
     thread = agents_client.threads.create()
     print(f"Created thread, ID: {thread.id}")
@@ -93,6 +130,7 @@
     # Create and process Agent run in thread with tools
     run = agents_client.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)
     print(f"Run finished with status: {run.status}")
+    # [END run_agent_with_connected_agent_tool]
 
     if run.status == "failed":
         print(f"Run failed: {run.last_error}")
@@ -108,10 +146,24 @@
     # Delete the connected Agent when done
     agents_client.delete_agent(weather_agent.id)
     print("Deleted weather agent")
-
+    
+    # [START list_tool_calls]
+    for run_step in agents_client.run_steps.list(thread_id=thread.id, run_id=run.id, order=ListSortOrder.ASCENDING):
+        if isinstance(run_step.step_details, RunStepToolCallDetails):
+            for tool_call in run_step.step_details.tool_calls:
+                print(f"\tAgent: {tool_call._data['connected_agent']['name']} "
+                      f"query: {tool_call._data['connected_agent']['arguments']} ",
+                      f"output: {tool_call._data['connected_agent']['output']}")
+    # [END list_tool_calls]
+
+    # [START list_messages]
     # Fetch and log all messages
-    messages = agents_client.messages.list(thread_id=thread.id)
+    messages = agents_client.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING)
     for msg in messages:
         if msg.text_messages:
             last_text = msg.text_messages[-1]
-            print(f"{msg.role}: {last_text.text.value}")
+            text = last_text.text.value.replace('\u3010', '[').replace('\u3011', ']')
+            print(f"{msg.role}: {text}")
+    # [END list_messages]
+
+    agents_client.threads.delete(thread.id)