Merge pull request #8763 from MicrosoftDocs/main

Auto Publish – main to live - 2025-11-21 18:12 UTC

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

.openpublishing.redirection.json

@@ -302,12 +302,12 @@
     },
     {
       "source_path": "articles/ai-foundry/openai/concepts/models.md",
-      "redirect_url": "/azure/ai-foundry/foundry-models/concepts/models-sold-directly-by-azure?pivots=azure-openai",
+      "redirect_url": "/azure/ai-foundry/foundry-models/concepts/models-sold-directly-by-azure",
       "redirect_document_id": false
     },
     {
       "source_path": "articles/ai-foundry/foundry-models/concepts/models.md",
-      "redirect_url": "/azure/ai-foundry/foundry-models/concepts/models-sold-directly-by-azure?pivots=azure-direct-others",
+      "redirect_url": "/azure/ai-foundry/foundry-models/concepts/models-sold-directly-by-azure",
       "redirect_document_id": false
     },
     {

articles/ai-foundry/agents/quickstart.md

@@ -8,7 +8,7 @@ manager: nitinme
 ms.service: azure-ai-foundry
 ms.subservice: azure-ai-foundry-agent-service
 ms.topic: quickstart
-ms.date: 09/25/2025
+ms.date: 11/21/2025
 ms.custom:
   - azure-ai-agents
   - build-2025
@@ -17,6 +17,9 @@ zone_pivot_groups: agents-quickstart
 
 # Quickstart: Create a new agent
 
+> [!NOTE]
+> This quickstart is for the previous version of agents. See the [**quickstart for Microsoft Foundry**](../quickstarts/get-started-code.md?view=foundry&preserve-view=true) to use the new version of the API.
+
 Foundry Agent Service allows you to create AI agents tailored to your needs through custom instructions and augmented by advanced tools like code interpreter, and custom functions.
 
 ::: zone pivot="ai-foundry-portal"

articles/ai-foundry/concepts/evaluation-evaluators/general-purpose-evaluators.md

@@ -315,7 +315,7 @@ if __name__ == "__main__":
     main()
 ```
 
-For more details, see the [complete working sample.](https://github.com/Azure/azure-sdk-for-python/blob/evaluation_samples_graders/sdk/ai/azure-ai-projects/samples/evaluation/agentic_evaluators/sample_coherence.py)
+For more details, see the [complete working sample](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/evaluations/agentic_evaluators/sample_coherence.py).
 
 ::: moniker-end
 

articles/ai-foundry/default/agents/how-to/tools/knowledge-retrieval.md

@@ -141,6 +141,25 @@ Content-Type: application/json
 
 ---
 
+## Optimize agent instructions for knowledge base retrieval
+
+To maximize the accuracy of knowledge base invocations and ensure proper citation formatting, use optimized agent instructions. Based on our experiments, we recommend the following instruction template as a starting point:
+
+```plaintext
+You are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.
+Every answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`
+If you cannot find the answer in the provided knowledge base you must respond with "I don't know".
+"""
+```
+
+This instruction template optimizes for:
+
++ **Higher MCP tool invocation rates**: Explicit directives ensure the agent consistently calls the knowledge base tool rather than relying on its training data.
++ **Proper annotation formatting**: The specified citation format ensures the agent includes provenance information in responses, making it clear which knowledge sources were used.
+
+> [!TIP]
+> While this template provides a strong foundation, we recommend evaluating and iterating on the instructions based on your specific use case and the tasks you're trying to accomplish. Test different variations to find what works best for your scenarios.
+
 ## Create an agent with the MCP tool
 
 The next step is to create an agent that integrates the knowledge base as an MCP tool. The agent uses a system prompt to instruct when and how to call the knowledge base, follows instructions on how to answer questions, and automatically maintains its tool configuration and settings across conversation sessions.
@@ -168,11 +187,11 @@ agent_model = "{deployed_LLM}" # e.g. gpt-4.1-mini
 # Create project client
 project_client = AIProjectClient(endpoint = project_endpoint, credential = credential)
 
-# Define agent instructions
+# Define agent instructions (see "Optimize agent instructions" section for guidance)
 instructions = """
-A Q&A agent that can answer questions based on the attached knowledge base.
-Always provide references to the ID of the data source used to answer the question.
-If you don't have the answer, respond with "I don't know".
+You are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.
+Every answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`
+If you cannot find the answer in the provided knowledge base you must respond with "I don't know".
 """
 
 # Create MCP tool with knowledge base connection
@@ -215,7 +234,7 @@ Content-Type: application/json
 {
   "definition": {
     "model": "{deployed_llm}",
-    "instructions": "\nA Q&A agent that can answer questions based on the attached knowledge base.\nAlways provide references to the ID of the data source used to answer the question.\nIf you don't have the answer, respond with \"I don't know\".\n",
+    "instructions": "\nYou are a helpful assistant that must use the knowledge base to answer all the questions from user. You must never answer from your own knowledge under any circumstances.\nEvery answer must always provide annotations for using the MCP knowledge base tool and render them as: `【message_idx:search_idx†source_name】`\nIf you cannot find the answer in the provided knowledge base you must respond with \"I don't know\".\n",
     "tools": [
       {
         "server_label": "knowledge-base",

articles/ai-foundry/default/includes/agent-v2-switch.md

@@ -11,4 +11,4 @@ ms.custom: include
 ---
 
 > [!TIP]
-> Code uses **Agents v2 API (preview)** and is incompatible with Agents v1. [Switch to (classic)](?view=foundry-classic&preserve-view=true) for the Agents v1 API version.
+> Code uses **Agents v2 API (preview)** and is incompatible with Agents v1. [Switch to Foundry (classic) documentation](?view=foundry-classic&preserve-view=true) for the Agents v1 API version.

articles/ai-foundry/includes/agent-v1-switch.md

@@ -11,4 +11,4 @@ ms.custom: include
 ---
 
 > [!TIP]
-> Code uses **Agents v1 API** and is incompatible with Agents v2 (preview). [Switch to (new)](?view=foundry&preserve-view=true) for the Agents v2 API (preview) version.
+> Code uses **Agents v1 API** and is incompatible with Agents v2 (preview). [Switch to Foundry (new) documentation](?view=foundry&preserve-view=true) for the Agents v2 API (preview) version.

articles/ai-foundry/openai/how-to/responses.md

@@ -1057,6 +1057,11 @@ response = client.responses.create(
 
 ### Authentication
 
+> [!IMPORTANT]
+> - The MCP client within the Responses API requires TLS 1.2 or greater.
+> - mutual TLS (mTLS) is currently not supported.
+> - [Azure service tags](/azure/virtual-network/service-tags-overview) are currently not supported for MCP client traffic.
+
 Unlike the GitHub MCP server, most remote MCP servers require authentication. The MCP tool in the Responses API supports custom headers, allowing you to securely connect to these servers using the authentication scheme they require.
 
 You can specify headers such as API keys, OAuth access tokens, or other credentials directly in your request. The most commonly used header is the `Authorization` header.

articles/search/agentic-retrieval-overview.md

@@ -131,7 +131,7 @@ Currently, Azure portal support for agentic retrieval is limited to the 2025-08-
 + [Quickstart-Agentic-Retrieval: Python](https://github.com/Azure-Samples/azure-search-python-samples/tree/main/Quickstart-Agentic-Retrieval)
 + [Quickstart-Agentic-Retrieval: .NET](https://github.com/Azure-Samples/azure-search-dotnet-samples/blob/main/quickstart-agentic-retrieval)
 + [Quickstart-Agentic-Retrieval: REST](https://github.com/Azure-Samples/azure-search-rest-samples/tree/main/Quickstart-agentic-retrieval)
-+ [End-to-end with Azure AI Search and Azure AI Agent Service](https://github.com/Azure-Samples/azure-search-python-samples/tree/main/agentic-retrieval-pipeline-example)
++ [End-to-end with Azure AI Search and Foundry Agent Service](https://github.com/Azure-Samples/azure-search-python-samples/tree/main/agentic-retrieval-pipeline-example)
 
 ### [**REST API references**](#tab/rest-api-references)
 

articles/search/cognitive-search-concept-image-scenarios.md

@@ -6,7 +6,7 @@ author: HeidiSteen
 ms.author: heidist
 ms.service: azure-ai-search
 ms.topic: how-to
-ms.date: 05/01/2025
+ms.date: 11/21/2025
 ms.update-cycle: 180-days
 ms.custom:
   - devx-track-csharp
@@ -15,16 +15,16 @@ ms.custom:
 
 # Extract text and information from images by using AI enrichment
 
-Images often contain useful information that's relevant in search scenarios. You can [vectorize images](search-get-started-portal-image-search.md) to represent visual content in your search index. Or, you can use [AI enrichment and skillsets](cognitive-search-concept-intro.md) to create and extract searchable *text* from images, including:
+Images often contain useful information that's relevant in search scenarios. Azure AI Search doesn't query image content in real time, but you can extract information about an image during indexing and make that content searchable. To represent images in a search index, you can use these approaches:
 
- + [GenAI Prompt](cognitive-search-skill-genai-prompt.md) to pass a prompt to a chat completion skill, requesting a description of image content.
-+ [OCR](cognitive-search-skill-ocr.md) for optical character recognition of text and digits
-+ [Image Analysis](cognitive-search-skill-image-analysis.md) that describes images through visual features
-+ [Custom skills](#passing-images-to-custom-skills) to invoke any external image processing that you want to provide
++ [Vectorize images](search-get-started-portal-image-search.md) to represent visual content as a searchable vector.
++ [Verbalize images](cognitive-search-skill-genai-prompt.md) using the GenAI Prompt skill that sends a verbalization request to a chat completion model to describe the image.
++ [Analyze images](cognitive-search-skill-image-analysis.md) using an image analysis skill to generate a text representation of an image, such as *dandelion* for a photo of a dandelion, or the color *yellow*. You can also extract metadata about the image, such as its size.
++ [Use OCR](cognitive-search-skill-ocr.md) to extract text and from photos or pictures, such as the word *STOP* in a stop sign.
 
-By using OCR, you can extract text and from photos or pictures, such as the word *STOP* in a stop sign. Through image analysis, you can generate a text representation of an image, such as *dandelion* for a photo of a dandelion, or the color *yellow*. You can also extract metadata about the image, such as its size.
+You can also create a [custom skill](#passing-images-to-custom-skills) to invoke any external image processing that you want to provide.
 
-This article covers the fundamentals of working with images in skillsets, and also describes several common scenarios, such as working with embedded images, custom skills, and overlaying visualizations on original images.
+This article focuses on image analysis and OCR, custom skills that provide external processing, working with embedded images, and overlaying visualizations on original images. If verbalization or vectorization is your preferred approach, see [Multimodal search](multimodal-search-overview.md) instead.
 
 To work with image content in a skillset, you need:
 
@@ -102,7 +102,7 @@ Metadata adjustments are captured in a complex type created for each image. You
 
    The default of 2,000 pixels for the normalized images maximum width and height is based on the maximum sizes supported by the [OCR skill](cognitive-search-skill-ocr.md) and the [image analysis skill](cognitive-search-skill-image-analysis.md). The [OCR skill](cognitive-search-skill-ocr.md) supports a maximum width and height of 4,200 for non-English languages, and 10,000 for English. If you increase the maximum limits, processing could fail on larger images depending on your skillset definition and the language of the documents. 
 
-1.  Optionally, [set file type criteria](search-blob-storage-integration.md#PartsOfBlobToIndex) if the workload targets a specific file type. Blob indexer configuration includes file inclusion and exclusion settings. You can filter out files you don't want.
+1. Optionally, [set file type criteria](search-blob-storage-integration.md#PartsOfBlobToIndex) if the workload targets a specific file type. Blob indexer configuration includes file inclusion and exclusion settings. You can filter out files you don't want.
 
   ```json
   {

articles/search/includes/how-tos/knowledge-source-delete-csharp.md

@@ -81,7 +81,7 @@ To delete a knowledge source:
     }
    ```
 
-1. Either delete the knowledge base or [update the knowledge base](/dotnet/api/azure.search.documents.indexes.searchindexclient.createorupdateknowledgebaseasync?view=azure-dotnet-preview) to remove the knowledge source if you have multiple sources. This example shows deletion.
+1. Either delete the knowledge base or [update the knowledge base](/dotnet/api/azure.search.documents.indexes.searchindexclient.createorupdateknowledgebaseasync?view=azure-dotnet-preview&preserve-view=true) to remove the knowledge source if you have multiple sources. This example shows deletion.
 
     ```csharp
     using Azure.Search.Documents.Indexes;