Merge pull request #6118 from MicrosoftDocs/main

Auto Publish – main to live - 2025-07-18 05:04 UTC

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

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/toc.yml

@@ -120,6 +120,8 @@ items:
           href: ../../ai-services/openai/how-to/content-filters.md?context=/azure/ai-services/agents/context/context
         - name: Use virtual networks
           href: how-to/virtual-networks.md
+        - name: Capability hosts
+          href: concepts/capability-hosts.md
     - name: Multi-agent workflows
       items:
         - name: Connected agents

articles/ai-services/document-intelligence/index.yml

@@ -10,7 +10,7 @@ metadata:
   ms.topic: landing-page
   author: laujan
   ms.author: lajanuar
-  ms.date: 11/19/2024
+  ms.date: 07/17/2025
   monikerRange: '<=doc-intel-4.0.0'
 # linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new
 # Limits: https://learn.learn.microsoft.com/help/contribute/contribute-how-to-write-landing-page?branch=main#limits
@@ -87,10 +87,6 @@ landingContent:
         links:
            - text: Transparency notes
              url: /azure/ai-foundry/responsible-ai/document-intelligence/transparency-note?toc=/azure/ai-services/document-intelligence/toc.json&bc=/azure/ai-services/document-intelligence/breadcrumb/toc.json
-           - text: Characteristics and limitations
-             url:  /azure/ai-foundry/responsible-ai/document-intelligence/characteristics-and-limitations?toc=/azure/ai-services/document-intelligence/toc.json&bc=/azure/ai-services/document-intelligence/breadcrumb/toc.json
-           - text: Guidance for integration and responsible use
-             url: /azure/ai-foundry/responsible-ai/document-intelligence/guidance-integration-responsible-use?toc=/azure/ai-services/document-intelligence/toc.json&bc=/azure/ai-services/document-intelligence/breadcrumb/toc.json
            - text: Data privacy, compliance, and security
              url: /azure/ai-foundry/responsible-ai/document-intelligence/data-privacy-security?toc=/azure/ai-services/document-intelligence/toc.json&bc=/azure/ai-services/document-intelligence/breadcrumb/toc.json#Card 5
 

articles/ai-services/document-intelligence/quickstarts/includes/rest-api.md

@@ -6,7 +6,7 @@ author: laujan
 manager: nitinme
 ms.service: azure-ai-document-intelligence
 ms.topic: include
-ms.date: 04/11/2025
+ms.date: 07/17/2025
 ms.author: lajanuar
 ---
 
@@ -30,10 +30,7 @@ In this quickstart, learn to use the Document Intelligence REST API to analyze a
 
 * Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services)
 
-* curl command line tool installed.
-
-  * [Windows](https://curl.haxx.se/windows/)
-  * [Mac or Linux](https://learn2torials.com/thread/how-to-install-curl-on-mac-or-linux-(ubuntu)-or-windows)
+* cURL command-line tool installed.
 
 * **PowerShell version 7.*+** (or a similar command-line application.):
   * [Windows](/powershell/scripting/install/installing-powershell-on-windows)