Azure
diff --git a/‎sdk/ai/azure-ai-agents/CHANGELOG.md
Lines changed: 19 additions & 0 deletions b/‎sdk/ai/azure-ai-agents/CHANGELOG.md
Lines changed: 19 additions & 0 deletions
diff --git a/‎sdk/ai/azure-ai-agents/README.md
Lines changed: 171 additions & 40 deletions b/‎sdk/ai/azure-ai-agents/README.md
Lines changed: 171 additions & 40 deletions
@@ -2,6 +2,25 @@
 
 # Release History
 
+## 1.1.0b4 (2025-07-11)
+
+### Features Added
+
+- Added support for MCP tool. For more information, see https://aka.ms/FoundryAgentMCPDoc.
+- New tool_resources parameter added to runs.create method. This parameter represents overridden enabled tool resources that the agent should use to run
+the thread. Default value is None.
+
+### Bugs Fixed
+
+- `_AgentsClientOperationsMixin` now it is private.
+
+### Sample updates
+
+- Added a sample showing usage of MCP tool, [`sample_agents_mcp.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_mcp.py).
+- Added a sample showing auto function call for a synchronous client, [`sample_agents_auto_function_call.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_auto_function_call.py)
+- Added a sample showing auto function call for an asynchronous client, [`sample_agents_auto_function_call_async.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_async/sample_agents_auto_function_call_async.py).
+
+
 ## 1.1.0b3 (2025-06-30)
 
 ### Features Added
 
@@ -39,6 +39,7 @@ To report an issue with the client library, or request additional features, plea
     - [Fabric data](#create-an-agent-with-fabric)
     - [Connected agents](#create-an-agent-using-another-agents)
     - [Deep Research](#create-agent-with-deep-research)
+    - [MCP](#create-agent-with-mcp)
   - [Create thread](#create-thread) with
     - [Tool resource](#create-thread-with-tool-resource)
   - [Create message](#create-message) with:
@@ -52,7 +53,9 @@ To report an issue with the client library, or request additional features, plea
   - [Tracing](#tracing)
     - [Installation](#installation)
     - [How to enable tracing](#how-to-enable-tracing)
+    - [Enabling content recording](#enabling-content-recording)
     - [How to trace your own functions](#how-to-trace-your-own-functions)
+    - [Adding custom attributes to spans](#adding-custom-attributes-to-spans)
 - [Troubleshooting](#troubleshooting)
   - [Logging](#logging)
   - [Reporting issues](#reporting-issues)
@@ -374,7 +377,7 @@ with project_client:
 
 ### Create Agent with Deep Research
 
-To enable your Agent to do a detailed research of a topic, use the `DeepResearchTool` along with a connection to a Bing Grounding resource.
+To enable your Agent to do detailed research of a topic, use the `DeepResearchTool` along with a connection to a Bing Grounding resource.
 This scenarios requires you to specify two model deployments. One is the generic chat model that does arbitration, and is
 specified as usual when you call the `create_agent` method. The other is the Deep Research model, which is specified
 when you define the `DeepResearchTool`.
@@ -384,7 +387,7 @@ Here is an example:
 <!-- SNIPPET:sample_agents_deep_research.create_agent_with_deep_research_tool -->
 
 ```python
-conn_id = os.environ["AZURE_BING_CONNECTION_ID"]
+conn_id = project_client.connections.get(name=os.environ["BING_RESOURCE_NAME"]).id
 
 # Initialize a Deep Research tool with Bing Connection ID and Deep Research model deployment name
 deep_research_tool = DeepResearchTool(
@@ -413,46 +416,128 @@ with project_client:
 > **Limitation**: The Deep Research tool is currently recommended **only** in non-streaming scenarios.
 > Using it with streaming can work, but it may occasionally time-out and is therefore not yet recommended.
 
-### Create Agent with Azure AI Search
+### Create Agent with MCP
 
-Azure AI Search is an enterprise search system for high-performance applications. It integrates with Azure OpenAI Service and Azure Machine Learning, offering advanced search technologies like vector search and full-text search. Ideal for knowledge base insights, information discovery, and automation. Creating an Agent with Azure AI Search requires an existing Azure AI Search Index. For more information and setup guides, see [Azure AI Search Tool Guide](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/azure-ai-search?tabs=azurecli%2Cpython&pivots=overview-azure-ai-search).
+To enable your Agent to connect to a MCP server, use the `McpTool` along with a server URI to a MCP server and a label for that server.
+Note that approval to send data to that server is required by default (but can be set to not required for each run).
 
-Here is an example to integrate Azure AI Search:
+Here is an example:
 
-<!-- SNIPPET:sample_agents_azure_ai_search.create_agent_with_azure_ai_search_tool -->
+<!-- SNIPPET:sample_agents_mcp.create_agent_with_mcp_tool -->
 
 ```python
-with AIProjectClient(
-    endpoint=os.environ["PROJECT_ENDPOINT"],
-    credential=DefaultAzureCredential(),
-) as project_client:
-    conn_id = project_client.connections.get_default(ConnectionType.AZURE_AI_SEARCH).id
-
-    print(conn_id)
-
-    # Initialize agent AI search tool and add the search index connection id
-    ai_search = AzureAISearchTool(
-        index_connection_id=conn_id,
-        index_name="sample_index",
-        query_type=AzureAISearchQueryType.SIMPLE,
-        top_k=3,
-        filter="",
-    )
+# Initialize agent MCP tool
+mcp_tool = McpTool(
+    server_label=mcp_server_label,
+    server_url=mcp_server_url,
+    allowed_tools=[],  # Optional: specify allowed tools
+)
+
+# You can also add or remove allowed tools dynamically
+search_api_code = "search_azure_rest_api_code"
+mcp_tool.allow_tool(search_api_code)
+print(f"Allowed tools: {mcp_tool.allowed_tools}")
 
-    # Create agent with AI search tool and process agent run
+# Create agent with MCP tool and process agent run
+with project_client:
     agents_client = project_client.agents
 
+    # Create a new agent.
+    # NOTE: To reuse existing agent, fetch it with get_agent(agent_id)
     agent = agents_client.create_agent(
         model=os.environ["MODEL_DEPLOYMENT_NAME"],
-        name="my-agent",
-        instructions="You are a helpful agent",
-        tools=ai_search.definitions,
-        tool_resources=ai_search.resources,
+        name="my-mcp-agent",
+        instructions="You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
+        tools=mcp_tool.definitions,
     )
 ```
 
 <!-- END SNIPPET -->
 
+The tool approval flow looks like this:
+
+<!-- SNIPPET:sample_agents_mcp.handle_tool_approvals -->
+
+```python
+# Create and process agent run in thread with MCP tools
+mcp_tool.update_headers("SuperSecret", "123456")
+# mcp_tool.set_approval_mode("never")  # Uncomment to disable approval requirement
+run = agents_client.runs.create(thread_id=thread.id, agent_id=agent.id, tool_resources=mcp_tool.resources)
+print(f"Created run, ID: {run.id}")
+
+while run.status in ["queued", "in_progress", "requires_action"]:
+    time.sleep(1)
+    run = agents_client.runs.get(thread_id=thread.id, run_id=run.id)
+
+    if run.status == "requires_action" and isinstance(run.required_action, SubmitToolApprovalAction):
+        tool_calls = run.required_action.submit_tool_approval.tool_calls
+        if not tool_calls:
+            print("No tool calls provided - cancelling run")
+            agents_client.runs.cancel(thread_id=thread.id, run_id=run.id)
+            break
+
+        tool_approvals = []
+        for tool_call in tool_calls:
+            if isinstance(tool_call, RequiredMcpToolCall):
+                try:
+                    print(f"Approving tool call: {tool_call}")
+                    tool_approvals.append(
+                        ToolApproval(
+                            tool_call_id=tool_call.id,
+                            approve=True,
+                            headers=mcp_tool.headers,
+                        )
+                    )
+                except Exception as e:
+                    print(f"Error approving tool_call {tool_call.id}: {e}")
+
+        print(f"tool_approvals: {tool_approvals}")
+        if tool_approvals:
+            agents_client.runs.submit_tool_outputs(
+                thread_id=thread.id, run_id=run.id, tool_approvals=tool_approvals
+            )
+
+    print(f"Current run status: {run.status}")
+```
+
+<!-- END SNIPPET -->
+
+### Create Agent with Azure AI Search
+
+Azure AI Search is an enterprise search system for high-performance applications. It integrates with Azure OpenAI Service and Azure Machine Learning, offering advanced search technologies like vector search and full-text search. Ideal for knowledge base insights, information discovery, and automation. Creating an Agent with Azure AI Search requires an existing Azure AI Search Index. For more information and setup guides, see [Azure AI Search Tool Guide](https://learn.microsoft.com/azure/ai-services/agents/how-to/tools/azure-ai-search?tabs=azurecli%2Cpython&pivots=overview-azure-ai-search).
+
+Here is an example to integrate Azure AI Search:
+
+<!-- SNIPPET:sample_agents_azure_ai_search.create_agent_with_azure_ai_search_tool -->
+
+```python
+conn_id = project_client.connections.get_default(ConnectionType.AZURE_AI_SEARCH).id
+
+print(conn_id)
+
+# Initialize agent AI search tool and add the search index connection id
+ai_search = AzureAISearchTool(
+    index_connection_id=conn_id,
+    index_name="sample_index",
+    query_type=AzureAISearchQueryType.SIMPLE,
+    top_k=3,
+    filter="",
+)
+
+# Create agent with AI search tool and process agent run
+agents_client = project_client.agents
+
+agent = agents_client.create_agent(
+    model=os.environ["MODEL_DEPLOYMENT_NAME"],
+    name="my-agent",
+    instructions="You are a helpful agent",
+    tools=ai_search.definitions,
+    tool_resources=ai_search.resources,
+)
+```
+
+<!-- END SNIPPET -->
+
 If the agent has found the relevant information in the index, the reference
 and annotation will be provided in the message response. In the example above, we replace
 the reference placeholder by the actual reference and url. Please note, that to
@@ -531,8 +616,12 @@ agent = await agents_client.create_agent(
 
 <!-- END SNIPPET -->
 
-Notice that if `enable_auto_function_calls` is called, the SDK will invoke the functions automatically during `create_and_process` or streaming.  If you prefer to execute them manually, refer to [`sample_agents_stream_eventhandler_with_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_eventhandler_with_functions.py) or
-[`sample_agents_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_functions.py)
+When `enable_auto_function_calls` is called, the SDK will automatically invoke functions during both `create_and_process` and streaming workflows. This simplifies agent logic by handling function execution internally.  Furthermore, although function tools and definitions are preserved in Agent service, their function implements are not.  Therefore, if your code queries earlier created agents through `update_agents` or `get_agents` function, you MUST also provide the function implementations through `enable_auto_function_calls` to complete auto function callings.
+
+- For examples of automatic function calls in action, refer to [`sample_agents_auto_function_call.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_auto_function_call.py) or [`sample_agents_auto_function_call_async.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_async/sample_agents_auto_function_call_async.py).
+- If you prefer to manage function execution manually, refer to [`sample_agents_stream_eventhandler_with_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_streaming/sample_agents_stream_eventhandler_with_functions.py) or
+[`sample_agents_functions.py`](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-agents/samples/agents_tools/sample_agents_functions.py).
+
 
 ### Create Agent With Azure Function Call
 
@@ -634,6 +723,7 @@ def foo(arguments: func.QueueMessage, outputQueue: func.Out[str]) -> None:
 To deploy your function to Azure properly, follow Microsoft's official documentation step by step:
 
 [Azure Functions Python Developer Guide](https://learn.microsoft.com/azure/azure-functions/create-first-function-cli-python?tabs=windows%2Cbash%2Cazure-cli%2Cbrowser)
+**Note:** The Azure Function may be only used in standard agent setup. Please follow the [instruction](https://github.com/azure-ai-foundry/foundry-samples/tree/main/samples/microsoft/infrastructure-setup/41-standard-agent-setup) to deploy an agent, capable of calling Azure Functions.
 
 **Summary of required steps:**
 
@@ -695,13 +785,6 @@ Below is an example of how to create an Azure Logic App utility tool and registe
 <!-- SNIPPET:sample_agents_logic_apps.register_logic_app -->
 
 ```python
-
-# Create the agents client
-project_client = AIProjectClient(
-    endpoint=os.environ["PROJECT_ENDPOINT"],
-    credential=DefaultAzureCredential(),
-)
-
 # Extract subscription and resource group from the project scope
 subscription_id = os.environ["SUBSCRIPTION_ID"]
 resource_group = os.environ["resource_group_name"]
@@ -951,9 +1034,11 @@ To understand what calls were made by the main agent to the connected ones, we w
 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']}")
+            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 -->
@@ -968,7 +1053,7 @@ messages = agents_client.messages.list(thread_id=thread.id, order=ListSortOrder.
 for msg in messages:
     if msg.text_messages:
         last_text = msg.text_messages[-1]
-        text = last_text.text.value.replace('\u3010', '[').replace('\u3011', ']')
+        text = last_text.text.value.replace("\u3010", "[").replace("\u3011", "]")
         print(f"{msg.role}: {text}")
 ```
 
@@ -1481,6 +1566,14 @@ from azure.ai.agents.telemetry import enable_telemetry
 
 enable_telemetry(destination=sys.stdout)
 ```
+
+### Enabling content recording
+Content recording controles whether message contents and tool call related details, such as parameters and return values, are captured with the traces.
+To enable content recording set the `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` environment variable value to `true`. If the environment variable is not set, then the value will default to `false`.
+
+
+**Important:** The `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` environment variable only controls content recording for built-in agent traces. When you use the `@trace_function` decorator on your own functions, all parameters and return values are always traced.
+
 ### How to trace your own functions
 
 The decorator `trace_function` is provided for tracing your own function calls using OpenTelemetry. By default the function name is used as the name for the span. Alternatively you can provide the name for the span as a parameter to the decorator.
@@ -1496,6 +1589,44 @@ Object types are omitted, and the corresponding parameter is not traced.
 
 The parameters are recorded in attributes `code.function.parameter.<parameter_name>` and the return value is recorder in attribute `code.function.return.value`
 
+### Adding custom attributes to spans
+
+Define your own span processor which adds your custom attributes:
+
+<!-- SNIPPET:sample_agents_basics_with_console_tracing_custom_attributes.custom_attribute_span_processor -->
+
+```python
+class CustomAttributeSpanProcessor(SpanProcessor):
+    def __init__(self):
+        pass
+
+    def on_start(self, span: Span, parent_context=None):
+        # Add this attribute to all spans
+        span.set_attribute("trace_sample.sessionid", "123")
+
+        # Add another attribute only to create_message spans
+        if span.name == "create_message":
+            span.set_attribute("trace_sample.message.context", "abc")
+
+    def on_end(self, span: ReadableSpan):
+        # Clean-up logic can be added here if necessary
+        pass
+```
+
+<!-- END SNIPPET -->
+
+Add the span processor to trace provider:
+
+<!-- SNIPPET:sample_agents_basics_with_console_tracing_custom_attributes.add_custom_span_processor_to_tracer_provider -->
+
+```python
+provider = cast(TracerProvider, trace.get_tracer_provider())
+provider.add_span_processor(CustomAttributeSpanProcessor())
+```
+
+<!-- END SNIPPET -->
+
+
 ## Troubleshooting
 
 ### Logging