Merge branch 'main' into jpvalidation-7-15-2

Author: JustPies

.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

.openpublishing.redirection.json

@@ -489,6 +489,26 @@
       "source_path": "articles/ai-foundry/model-inference/index.yml",
       "redirect_url": "../foundry-models/index",
       "redirect_document_id": false
+    },
+    {
+      "source_path": "articles/machine-learning/concept-package-models.md",
+      "redirect_url": "/azure/machine-learning/concept-endpoints",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "articles/machine-learning/how-to-package-models-moe.md",
+      "redirect_url": "/azure/machine-learning/concept-endpoints",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "articles/machine-learning/how-to-package-models-app-service.md",
+      "redirect_url": "/azure/machine-learning/concept-endpoints",
+      "redirect_document_id": false
+    },
+    {
+      "source_path": "articles/machine-learning/how-to-package-models.md",
+      "redirect_url": "/azure/machine-learning/concept-endpoints",
+      "redirect_document_id": false
     }
   ]
 }

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/concepts/capability-hosts.md

@@ -0,0 +1,139 @@
+---
+title: 'Learn what is a capability host'
+titleSuffix: Azure AI Foundry
+description: Learn how to create and delete capability hosts
+services: cognitive-services
+manager: nitinme
+ms.service: azure-ai-agent-service
+ms.topic: conceptual
+ms.date: 07/07/2025
+author: fosteramanda
+ms.author: fosteramanda
+---
+
+# Capability hosts
+
+> [!NOTE]
+> Updating capability hosts is not supported. To modify a capability host, you must delete the existing one and recreate it with the new configuration.
+
+Capability hosts are sub-resources that you define at both the Azure AI Foundry Account and Foundry project scopes. They specify where the Azure AI Foundry Agent Service should store and process your agent data, including:
+- **Conversation history (threads)** 
+- **File uploads** 
+- **Vector stores** 
+
+## Why use capability hosts?
+
+Capability hosts allow you to **bring your own Azure resources** instead of using the default Microsoft-managed platform resources. This gives you:
+
+- **Data sovereignty** - Keep all agent data within your Azure subscription.
+- **Security control** - Use your own storage accounts, databases, and search services.
+- **Compliance** - Meet specific regulatory or organizational requirements.
+
+## How do capability hosts work?
+
+Creating capability hosts is not required. However if you do want agents to use your own resources, you must create a capability host on both the account and project. 
+
+### Default behavior (Microsoft-managed resources)
+If you don't create an account-level and project-level capability host, the Azure AI Foundry Agent Service automatically uses Microsoft-managed Azure resources for:
+- Thread storage (conversation history)
+- File storage (uploaded documents) 
+- Vector search (embeddings and retrieval)
+
+### Bring-your-own resources
+When you create capability hosts at both the account and project levels, all agent data is stored and processed using your own Azure resources within your subscription. This configuration is called a **standard agent setup**.
+
+#### Configuration hierarchy
+
+Capability hosts follow a hierarchy where more specific configurations override broader ones:
+
+1. **Service defaults** (Microsoft-managed search and storage) - Used when no capability host is configured.
+2. **Account-level capability host** - Provides shared defaults for all projects under the account.
+3. **Project-level capability host** - Overrides account-level and service defaults for that specific project. 
+
+
+## Recommended setup 
+
+### Required properties
+
+A capability host must be configured with the following three properties at either the account or project level:
+
+| Property | Purpose | Required Azure resource | Example connection name |
+|----------|---------|------------------------|------------------------|
+| `threadStorageConnections` | Stores conversation history and chat threads | Azure Cosmos DB | `"my-cosmosdb-connection"` |
+| `vectorStoreConnections` | Handles vector storage for retrieval and search | Azure AI Search | `"my-ai-search-connection"` |
+| `storageConnections` | Manages file uploads and blob storage | Azure Storage Account | `"my-storage-connection"` |
+
+### Optional property
+
+| Property | Purpose | Required Azure resource | When to use |
+|----------|---------|------------------------|-------------|
+| `aiServicesConnections` | Use your own model deployments | Azure OpenAI | When you want to use models from your existing Azure OpenAI resource instead of the built-in account level ones. |
+
+**Account capability host**
+```http
+PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01
+
+{
+  "properties": {
+    "capabilityHostKind": "Agents"
+  }
+}
+```
+**Project capability host**
+
+This configuration overrides service defaults and any account-level settings. All agents in this project will use your specified resources:
+```http
+PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01
+
+{
+  "properties": {
+    "capabilityHostKind": "Agents",
+    "threadStorageConnections": ["my-cosmos-db-connection"],
+    "vectorStoreConnections": ["my-ai-search-connection"],
+    "storageConnections": ["my-storage-account-connection"],
+    "aiServicesConnections": ["my-azure-openai-connection"]  // Optional
+  }
+}
+```
+
+### Optional: account-level defaults with project overrides
+
+Set shared defaults at the account level that apply to all projects:
+
+```http
+PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01
+
+{
+  "properties": {
+    "capabilityHostKind": "Agents",
+
+    // Optional: define shared BYO resources for every project. All foundry projects under this account will uses these Azure resources  
+    "threadStorageConnections": ["shared-cosmosdb-connection"],
+    "vectorStoreConnections": ["shared-ai-search-connection"],
+    "storageConnections": ["shared-storage-connection"]
+  }
+}
+```
+> [!NOTE]
+> All Azure AI Foundry projects will inherit these settings. Then override specific settings at the project level as needed.
+
+## Delete capability hosts
+
+> [!WARNING]
+> Deleting a capability host will affect all agents that depend on it. Make sure you understand the impact before proceeding. For instance, if you delete the project and account capability host, agents in your project will no longer have access to the files, thread, and vector stores it previously did.
+
+### Delete an account-level capability host
+
+```http
+DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01
+```
+
+### Delete a project-level capability host
+
+```http
+DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01
+```
+
+## Next steps
+- Learn more about the [Standard Agent Setup](standard-agent-setup.md) 
+- Get started with [Agent Service](../environment-setup.md)

articles/ai-foundry/agents/how-to/connected-agents.md

@@ -109,7 +109,7 @@ Checks the contract against internal standards or uploaded guidelines to identif
 ## Use the .NET SDK 
 
 > [!NOTE]
-> This shows a synchronous usage. You can find an asynchronous example on [GitHub](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/ai/Azure.AI.Projects/samples/Sample24_Agent_Connected_Agent.md) 
+> This shows a synchronous usage. You can find an asynchronous example on [GitHub](https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/ai/Azure.AI.Agents.Persistent/samples/Sample23_PersistentAgents_Connected_Agent.md) 
 
 To enable your Agent to use a connected agent, you use `ConnectedAgentToolDefinition` along with the agent ID, name, and a description.
 
@@ -230,7 +230,7 @@ To create a multi-agent setup, follow these steps:
     ```python
     import os
     from azure.ai.projects import AIProjectClient
-    from azure.ai.projects.models import ConnectedAgentTool, MessageRole
+    from azure.ai.agents.models import ConnectedAgentTool, MessageRole
     from azure.identity import DefaultAzureCredential
 
 

articles/ai-foundry/agents/how-to/metrics.md

@@ -15,6 +15,8 @@ ms.service: azure-ai-agent-service
 
 Monitoring is available for agents in a [standard agent setup](../concepts/standard-agent-setup.md).
 
+[!INCLUDE [Feature preview](../../openai/includes/preview-feature.md)]
+
 > [!IMPORTANT]
 > Monitoring support is currently limited to Azure AI Foundry hubs. Azure AI Foundry projects are not supported.
 
@@ -94,4 +96,4 @@ You can set alerts for any metric listed in the [monitoring data reference](../r
 ## Related content
 
 - See [Monitoring data reference](../reference/monitor-service.md) for a reference of the metrics and other important values created for Azure AI Foundry Agent Service.
-- See [Monitoring Azure resources with Azure Monitor](/azure/azure-monitor/essentials/monitor-azure-resource) for general details on monitoring Azure resources.
+- See [Monitoring Azure resources with Azure Monitor](/azure/azure-monitor/essentials/monitor-azure-resource) for general details on monitoring Azure resources.

articles/ai-foundry/agents/how-to/tools/azure-functions.md

@@ -14,10 +14,14 @@ ms.custom: azure-ai-agents
 
 # Use Azure Functions with Azure AI Foundry Agent Service
 
-The Azure AI Foundry Agent Service integrates with Azure Functions, enabling you to create intelligent, event-driven applications with minimal overhead. This combination allows AI-driven workflows to leverage the scalability and flexibility of serverless computing, making it easier to build and deploy solutions that respond to real-time events or complex workflows. 
- 
-Azure Functions provide support for triggers and bindings, which simplify how your AI Agents interact with external systems and services. Triggers determine when a function executes—such as an HTTP request, message from a queue, or a file upload to Azure Blob Storage and allows agents to act dynamically based on incoming events. 
- 
+The Azure AI Foundry Agent Service integrates with Azure Functions, enabling you to create intelligent, event-driven applications with minimal overhead. This combination allows AI-driven workflows to leverage the scalability and flexibility of serverless computing, making it easier to build and deploy solutions that respond to real-time events or complex workflows.
+
+Currently, direct integration with Azure Functions is only supported for functions triggered by Azure Storage Queues. Other trigger types, such as HTTP or Blob Storage, are not natively supported at this time.
+
+Azure Functions provide support for triggers and bindings, which simplify how your AI Agents interact with external systems and services. Triggers determine when a function executes—such as an HTTP request, message from a queue, or a file upload to Azure Blob Storage—and allow agents to act dynamically based on incoming events.
+
+For HTTP-triggered Azure Functions, integration is possible by describing the function through an OpenAPI specification and registering it as a callable tool in the agent configuration. Alternatively, you can implement a queue-based wrapper function that receives messages from the agent and internally invokes the HTTP logic, enabling the use of the existing queue-based integration.
+
 Meanwhile, bindings facilitate streamlined connections to input or output data sources, such as databases or APIs, without requiring extensive boilerplate code. For instance, you can configure a trigger to execute an Azure Function whenever a customer message is received in a chatbot and use output bindings to send a response via the Azure AI Agent.
 
 ### Supported models

articles/ai-foundry/agents/how-to/tools/deep-research-samples.md

@@ -50,14 +50,14 @@ Use this article to learn how to use the Deep Research tool with the Azure AI Pr
 
     Save this endpoint to an environment variable named `BING_RESOURCE_NAME`. 
 
-* The names of your `o3-deep-research-model` deployment name and Azure OpenAI GPT model deployment name. You can find them in **Models + Endpoints** in the left navigation menu. 
+* The deployment names of your `o3-deep-research-model` and `gpt-4o` models. You can find them in **Models + Endpoints** in the left navigation menu.
 
-    :::image type="content" source="../../media/tools/deep-research/model-deployments.png" alt-text="A screenshot showing the model deployment screen the AI Foundry portal." lightbox="../../media/tools/deep-research/model-deployments.png":::
+   :::image type="content" source="../../media/tools/deep-research/model-deployments.png" alt-text="A screenshot showing the model deployment screen the AI Foundry portal." lightbox="../../media/tools/deep-research/model-deployments.png":::
     
-    Save the name of your `o3-deep-research-model` deployment name as an environment variable named `DEEP_RESEARCH_MODEL_DEPLOYMENT_NAME` and Azure OpenAI GPT model deployment name as an environment variable named `MODEL_DEPLOYMENT_NAME`. 
+    Save the name of your `o3-deep-research` deployment name as an environment variable named `DEEP_RESEARCH_MODEL_DEPLOYMENT_NAME` and the `gpt-4o` deployment name as an environment variable named `MODEL_DEPLOYMENT_NAME`.
 
 > [!NOTE]
-> Limitation: The Deep Research tool is currently recommended only in nonstreaming scenarios. Using it with streaming can work, but it might occasionally time out and is therefore not recommended.
+> Other GPT-series models including GPT-4o-mini and the GPT-4.1 series are not supported for scope clarification.
 
 ## Create an agent with the Deep Research tool
 
@@ -197,6 +197,9 @@ with project_client:
         print("Deleted agent")
 ```
 
+> [!NOTE]
+> Limitation: The Deep Research tool is currently recommended only in nonstreaming scenarios. Using it with streaming can work, but it might occasionally time out and is therefore not recommended.
+
 ## Next steps
 
 * [Reference documentation](https://aka.ms/azsdk/azure-ai-projects/python/reference)

articles/ai-foundry/agents/how-to/tools/deep-research.md

@@ -47,11 +47,14 @@ The Deep Research tool is supported in the following regions where the deep rese
 |---------|---------|
 | ✔️ | ✔️ | 
 
-## GPT model for clarifying research scope
+## GPT-4o model for clarifying research scope
 
-The Deep Research tool uses a GPT model to clarify the question contained in the user prompt, gather additional context if needed, and precisely scope the research task. This model is deployed during configuration of the Deep Research tool and can be one of the GPT-series models including GPT-4o, **except** the GPT-4.1 family, The 4.1 family is not supported by the Agents service.
+The Deep Research tool uses the `gpt-4o` model to clarify the question contained in the user prompt, gather additional context if needed, and precisely scope the research task. This model is deployed during configuration of the Deep Research tool. 
 
-## Deep research model for deep analysis
+> [!NOTE]
+> Other GPT-series models including GPT-4o-mini and the GPT-4.1 series are not supported for scope clarification.
+
+## Deep research model for analysis
 
 - **Model name**: `o3-deep-research`
 - **Deployment type**: Global Standard
@@ -64,7 +67,7 @@ The Deep Research tool uses a GPT model to clarify the question contained in the
 - [Grounding with Bing Search tool](./bing-grounding.md) resource for connecting to your Azure AI Foundry project.
 - [Model deployments](../../../model-inference/how-to/create-model-deployments.md) for the following models
     - `o3-deep-research` version `2025-06-26`. This model is available in `West US` and `Norway East`.
-    - Any Azure OpenAI GPT model like `gpt-4o` for intent clarification. Deploy in the same regions.
+    - The `gpt-4o` model for intent clarification. Deploy this model in the same region.
 
 ## Research tool setup 
 

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.