Merge pull request #6113 from MicrosoftDocs/main

Auto Publish – main to live - 2025-07-17 22:05 UTC

Author: learn-build-service-prod[bot]

.github/policies/disallow-edits.yml

@@ -28,15 +28,17 @@ configuration:
               matchAny: true
               pattern: articles/ai-foundry/responsible-ai/*
           - not:
-              activitySenderHasAssociation:
-                association: Member
+              or:
+                - activitySenderHasAssociation:
+                    association: Member
+                - isActivitySender:
+                    user: learn-build-service-prod[bot]
         then:
           - addReply:
               reply: >-
                 @${issueAuthor} - Pull requests that modify files in this folder aren't accepted from public contributors.
           - closePullRequest
 
-
       - description: \@mention specific people when a PR is opened in the "ai-foundry/responsible-ai" folder.
         if:
           - payloadType: Pull_Request

articles/ai-foundry/.openpublishing.redirection.ai-studio.json

@@ -1203,6 +1203,11 @@
           "redirect_url": "/azure/ai-foundry/how-to/develop/trace-application#visualize-your-traces",
           "redirect_document_id": false
         },
+        {
+          "source_path_from_root": "/articles/ai-foundry/agents/index.yml",
+          "redirect_url": "/azure/ai-foundry/",
+          "redirect_document_id": false
+        },
         {
           "source_path_from_root": "/articles/ai-foundry/how-to/online-evaluation.md",
           "redirect_url": "/azure/ai-foundry/how-to/monitor-applications",

articles/ai-foundry/agents/how-to/tools/file-search.md

@@ -6,7 +6,7 @@ services: cognitive-services
 manager: nitinme
 ms.service: azure-ai-agent-service
 ms.topic: how-to
-ms.date: 12/11/2024
+ms.date: 07/17/2025
 author: aahill
 ms.author: aahi
 ms.custom: azure-ai-agents
@@ -26,17 +26,13 @@ File search augments agents with knowledge from outside its model, such as propr
 
 ### File sources  
 - Upload local files 
-- Azure Blob Storage 
-
-### Supported file types
-
-- [Supported file types](#supported-file-types)
+- Azure Blob Storage
 
 ### Usage support
 
 |Azure AI foundry support  | Python SDK |	C# SDK | JavaScript SDK | REST API | Basic agent setup | Standard agent setup |
 |---------|---------|---------|---------|---------|---------|---------|
-| ✔️  | ✔️ | ✔️ | ✔️ | ✔️ | File upload only | File upload and using  BYO blob storage | 
+| ✔️  | ✔️ | ✔️ | ✔️ | ✔️ | File upload only | File upload and using  bring-your-own blob storage | 
 
 ## Dependency on agent setup
 
@@ -49,9 +45,8 @@ The file search tool has the same functionality as Azure OpenAI Assistants. Micr
 The file search tool uses the Azure AI Search and Azure Blob Storage resources you connected during agent setup. 
 - Uploaded files get stored in your connected Azure Blob Storage account 
 - Vector stores get created using your connected Azure AI Search resource 
-<br> </br>
 
-For both agent setups, Azure OpenAI handles the entire ingestion process, which includes:
+For both agent setups, the service handles the entire ingestion process, which includes:
 - Automatically parsing and chunking documents
 - Generating and storing embeddings
 - Utilizing both vector and keyword searches to retrieve relevant content for user queries. 
@@ -169,9 +164,9 @@ vector_store = project_client.agents.create_vector_store_and_poll(
 
 Vector stores created using thread helpers (like `tool_resources.file_search.vector_stores` in Threads or `message.attachments` in Messages) have a default expiration policy of seven days after they were last active (defined as the last time the vector store was part of a run).
 
-When a vector store expires, the runs on that thread fail.  To fix this issue, you can recreate a new vector_store with the same files and reattach it to the thread.
+When a vector store expires, the runs on that thread fail. To fix this issue, you can recreate a new vector_store with the same files and reattach it to the thread.
 
-### Supported file types
+## Supported file types
 
 > [!NOTE]
 > For text/ MIME types, the encoding must be either utf-8, utf-16, or ASCII.

articles/ai-foundry/agents/how-to/tools/model-context-protocol-samples.md

@@ -1,7 +1,7 @@
 ---
-title: 'MCP tool code samples'
+title: Code Samples for the Model Context Protocol Tool (Preview)
 titleSuffix: Azure AI Foundry
-description: Find code samples to connect Foundry Agent service with MCP.
+description: Find code samples to connect Azure AI Foundry Agent Service with MCP servers.
 services: cognitive-services
 manager: nitinme
 ms.service: azure-ai-agent-service
@@ -13,13 +13,14 @@ zone_pivot_groups: selection-mcp-code
 ms.custom: azure-ai-agents-code
 ---
 
-# How to use the Model Context Protocol (MCP) tool
+# Code samples for the Model Context Protocol tool (preview)
 
-Use this article to find step-by-step instructions and code samples for connecting Foundry Agent service with MCP.
+Use this article to find code samples for connecting Azure AI Foundry Agent Service with Model Context Protocol (MCP) servers.
 
 :::zone pivot="python"
 
-## Initialization
+## Initialize the client
+
 The code begins by setting up the necessary imports, getting the relevant MCP server configuration, and initializing the AI Project client:
 
 ```python
@@ -29,7 +30,7 @@ from azure.ai.projects import AIProjectClient
 from azure.identity import DefaultAzureCredential
 from azure.ai.agents.models import McpTool, RequiredMcpToolCall, SubmitToolApprovalAction, ToolApproval
 
-# Get MCP server configuration from environment variables
+# Get the MCP server configuration from environment variables
 mcp_server_url = os.environ.get("MCP_SERVER_URL", "https://gitmcp.io/Azure/azure-rest-api-specs")
 mcp_server_label = os.environ.get("MCP_SERVER_LABEL", "github")
 
@@ -39,8 +40,9 @@ project_client = AIProjectClient(
 )
 ```
 
-## Tool setup
-To add the MCP server to the agent, use the following example, which takes the MCP server label and URL from the last step. You can also add or remove allowed tools dynamically through the `allow_tool` parameter. 
+## Set up the tool
+
+To add the MCP server to the agent, use the following example, which takes the MCP server label and URL from the previous step. You can also add or remove allowed tools dynamically through the `allow_tool` parameter.
 
 ```python
 mcp_tool = McpTool(
@@ -55,17 +57,18 @@ mcp_tool.allow_tool(search_api_code)
 print(f"Allowed tools: {mcp_tool.allowed_tools}")
 ```
 
-## Agent creation
-An agent is created using the `project_client.agents.create_agent` method.
+## Create an agent
+
+You create an agent by using the `project_client.agents.create_agent` method:
 
 ```python
 # Create a new agent.
-# NOTE: To reuse existing agent, fetch it with get_agent(agent_id)
+# NOTE: To reuse an existing agent, fetch it with get_agent(agent_id)
 with project_client:
     agents_client = project_client.agents
 
     # Create a new agent.
-    # NOTE: To reuse existing agent, fetch it with get_agent(agent_id)
+    # NOTE: To reuse an existing agent, fetch it with get_agent(agent_id)
     agent = agents_client.create_agent(
         model=os.environ["MODEL_DEPLOYMENT_NAME"],
         name="my-mcp-agent",
@@ -74,15 +77,16 @@ with project_client:
     )
 ```
 
-## Thread management
-Create the thread and add the initial user message.
+## Create a thread
+
+Create the thread and add the initial user message:
 
 ```python
-# Create thread for communication
+# Create a thread for communication
 thread = agents_client.threads.create()
 print(f"Created thread, ID: {thread.id}")
 
-# Create message to thread
+# Create a message for the thread
 message = agents_client.messages.create(
     thread_id=thread.id,
     role="user",
@@ -91,20 +95,20 @@ message = agents_client.messages.create(
 print(f"Created message, ID: {message.id}")
 ```
 
-## Handle tool approvals and create a run
+## Handle tool approvals
 
-Set the MCP server update headers and optionally disable tool approval requirements.
+Set the MCP server update headers and optionally disable tool approval requirements:
 
 ```python
 mcp_tool.update_headers("SuperSecret", "123456")
-# mcp_tool.set_approval_mode("never")  # Uncomment to disable approval requirement
+# mcp_tool.set_approval_mode("never")  # Uncomment to disable approval requirements
 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}")
 ```
 
-
 ## Create a run and check the output
-Create the run, check the output, and examine what tools were called during the run.
+
+Create the run, check the output, and examine what tools were called during the run:
 
 ```python
     # Create and automatically process the run, handling tool calls internally
@@ -133,9 +137,9 @@ Create the run, check the output, and examine what tools were called during the
         print()
 ```
 
+## Perform cleanup
 
-## Cleanup
-After the interaction is complete, the script performs cleanup by deleting the created agent resource using `agents_client.delete_agent()` to avoid leaving unused resources. It also fetches and prints the entire message history from the thread using `agents_client.list_messages()` for review or logging.
+After the interaction is complete, the script performs cleanup by deleting the created agent resource via `agents_client.delete_agent()` to avoid leaving unused resources. It also fetches and prints the entire message history from the thread by using `agents_client.list_messages()` for review or logging.
 
 ```python
         # Delete the agent resource to clean up
@@ -152,24 +156,24 @@ After the interaction is complete, the script performs cleanup by deleting the c
 
 :::zone pivot="rest"
 
-Follow the [REST API Quickstart](../../quickstart.md?pivots=rest-api#api-call-information) to set the right values for the environment variables `AGENT_TOKEN`, `AZURE_AI_FOUNDRY_PROJECT_ENDPOINT`, and `API_VERSION`.
+Follow the [REST API quickstart](../../quickstart.md?pivots=rest-api#api-call-information) to set the right values for the environment variables `AGENT_TOKEN`, `AZURE_AI_FOUNDRY_PROJECT_ENDPOINT`, and `API_VERSION`.
 
+## Create an agent with the MCP tool enabled
 
-## Create an Agent with the MCP tool enabled
+To make the MCP tool available to your agent, initialize a tool with the server endpoint, server label, and more:
 
-To make the MCP tool available to your agent, initialize a tool with the server endpoint, server label and more
 ```bash
 curl --request POST \
   --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/assistants?api-version=$API_VERSION \
   -H "Authorization: Bearer $AGENT_TOKEN" \
   -H "Content-Type: application/json" \
   -d "{
-	  "instructions": "You are a customer support chatbot. Use the tools provided and your knowledge base to best respond to customer queries.",
-  	"tools": [
+    "instructions": "You are a customer support chatbot. Use the tools provided and your knowledge base to best respond to customer queries.",
+    "tools": [
           {
               "type": "mcp",
               "server_label": "<unique name for your MCP server>",
-              "server_url": "<your MCP server url>",
+              "server_url": "<your MCP server URL>",
               "allowed_tools": ["<tool_name>"], # optional
           }
       ],
@@ -203,26 +207,27 @@ curl --request POST \
 
 ## Create a run and check the output
 
-Create a run to pass headers for the tool and observe that the model uses the Grounding with Bing Search tool to provide a response to the user's question. 
-`require_approval` parameter is optional. If not provided, `always` is the default value, meaning each time developer needs to approve before calling. Supported values:
+Create a run to pass headers for the tool. Observe that the model uses the Grounding with Bing Search tool to provide a response to the user's question.
+
+The `require_approval` parameter is optional. Supported values are:
 
-- `always` by default
-- `never` meaning no approval is required
-- `{"never":[<tool_name_1>, <tool_name_2>]}` you can also provide a list of tools without required approval
-- `{"always":[<tool_name_1>, <tool_name_2>]}` you can provide a list of tools with required approval
+- `always`: A developer needs to provide approval for every call. If you don't provide a value, this one is the default.
+- `never`: No approval is required.
+- `{"never":[<tool_name_1>, <tool_name_2>]}`: You provide a list of tools that don't require approval.
+- `{"always":[<tool_name_1>, <tool_name_2>]}`: You provide a list of tools that require approval.
 
 ```bash
 curl --request POST \
   --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs?api-version=$API_VERSION \
   -H "Authorization: Bearer $AGENT_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-	    "assistant_id": "<agent_id>",
-    	"tool_resources": {
+      "assistant_id": "<agent_id>",
+      "tool_resources": {
           "mcp": [
             {
                 "server_label": "<the same unique name you provided during agent creation>",
-		"require_approval": "always" #always by default
+    "require_approval": "always" #always by default
                 "headers": {
                     "Authorization": "Bearer <token>",
                 }
@@ -232,6 +237,7 @@ curl --request POST \
       },
     }'
 ```
+
 ## Retrieve the status of the run
 
 ```bash
@@ -240,7 +246,8 @@ curl --request GET \
   -H "Authorization: Bearer $AGENT_TOKEN"
 ```
 
-If the model is trying to invoke a tool in your MCP server with approval required, you get a run with `require_action` status.
+If the model tries to invoke a tool in your MCP server with approval required, you get a run with `requires_action` status:
+
 ```bash
 {
   "id": "run_123",
@@ -274,17 +281,20 @@ If the model is trying to invoke a tool in your MCP server with approval require
  ...
 }
 ```
-Make sure you carefully reviewed the tool and argument(s) to be passed and make an informed decision for approval.
+
+Carefully review the tool and arguments to be passed so that you can make an informed decision for approval.
 
 ## Submit your approval
-If you decide to approve, you need to set the `approve` parameter to be `true` with the `id` for the preceding tool calls.
+
+If you decide to approve, set the `approve` parameter to `true` with the `id` value for the preceding tool calls:
+
 ```bash
 curl --request POST \
   --url $AZURE_AI_FOUNDRY_PROJECT_ENDPOINT/threads/thread_abc123/runs/run_abc123/submit_tool_outputs?api-version=$API_VERSION \
   -H "Authorization: Bearer $AGENT_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
-	"tool_approvals": [
+  "tool_approvals": [
         {
             "tool_call_id": "call_abc123",
             "approve": true,
@@ -295,7 +305,6 @@ curl --request POST \
 }
 ```
 
-
 ## Retrieve the agent response
 
 ```bash
@@ -305,4 +314,3 @@ curl --request GET \
 ```
 
 :::zone-end
-