Merge pull request #5 from aahill/patch-14

Update capability-hosts.md

Author: fosteramanda

articles/ai-foundry/agents/concepts/capability-hosts.md

@@ -6,12 +6,12 @@ services: cognitive-services
 manager: nitinme
 ms.service: azure-ai-agent-service
 ms.topic: conceptual
-ms.date: 07/7/2025
+ms.date: 07/07/2025
 author: fosteramanda
 ms.author: fosteramanda
 ---
 
-# Capability Hosts
+# 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.
@@ -21,55 +21,55 @@ Capability hosts are sub-resources that you define at both the Azure AI Foundry
 - **File uploads** 
 - **Vector stores** 
 
-## Why use Capability Hosts?
+## Why use capability hosts?
 
-Capability hosts allow you to **bring your own Azure resources** instead of using the default on Microsoft-managed platform resources. This gives you:
+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
+- **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?
+## 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 Agent Service automatically uses Microsoft-managed Azure resources for:
+### 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 the **Standard Agent Setup**.
+### 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 
+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 
+## Recommended setup 
 
-#### Required properties
+### 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 |
+| 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
+### Optional property
 
-| Property | Purpose | Required Azure Resource | When to use |
+| 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 |
+| `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**
+**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
 
@@ -79,7 +79,7 @@ PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{
   }
 }
 ```
-**Project Capability Host**
+**Project capability host**
 
 This configuration overrides service defaults and any account-level settings. All agents in this project will use your specified resources:
 ```http
@@ -91,12 +91,12 @@ PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{
     "threadStorageConnections": ["my-cosmos-db-connection"],
     "vectorStoreConnections": ["my-ai-search-connection"],
     "storageConnections": ["my-storage-account-connection"],
-    "aiServicesConnections": ["my-aoai-connection"]  // Optional
+    "aiServicesConnections": ["my-azure-openai-connection"]  // Optional
   }
 }
 ```
 
-### Optional: Account-level defaults with project overrides
+### Optional: account-level defaults with project overrides
 
 Set shared defaults at the account level that apply to all projects:
 
@@ -114,7 +114,8 @@ PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{
   }
 }
 ```
-Note: all Foundry projects will inherit these setting. Then override specific settings at the project level as needed.
+> [!NOTE]
+> All Azure AI Foundry projects will inherit these setting. Then override specific settings at the project level as needed.
 
 ## Deleting capability hosts
 
@@ -135,4 +136,4 @@ DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroup
 
 ## Next steps
 - Learn more about the [Standard Agent Setup](standard-agent-setup.md) 
-- Get started wth [Agent Service](../environment-setup.md)
+- Get started with [Agent Service](../environment-setup.md)

articles/ai-foundry/agents/toc.yml

@@ -122,6 +122,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