Merge pull request #6457 from MicrosoftDocs/main

Auto Publish – main to live - 2025-08-07 22:03 UTC

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

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

@@ -50,6 +50,14 @@ Capability hosts follow a hierarchy where more specific configurations override
 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. 
 
+## Understand capability host constraints
+
+When creating capability hosts, be aware of these important constraints to avoid conflicts:
+
+- **One capability host per scope**: Each account and each project can only have one active capability host. Attempting to create a second capability host with a different name at the same scope will result in a 409 conflict.
+
+- **Configuration updates are not supported**: If you need to change configuration, you must delete the existing capability host and recreate it.
+
 
 ## Recommended setup 
 
@@ -79,6 +87,7 @@ PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{
   }
 }
 ```
+
 **Project capability host**
 
 This configuration overrides service defaults and any account-level settings. All agents in this project will use your specified resources:
@@ -134,6 +143,120 @@ DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroup
 DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01
 ```
 
+## Troubleshooting
+
+If you're experiencing issues when creating capability hosts, this section provides solutions to the most common problems and errors.
+
+### HTTP 409 Conflict errors
+
+#### Problem: Multiple capability hosts per scope
+
+**Symptoms:** You receive a 409 Conflict error when trying to create a capability host, even though you believe the scope is empty.
+
+**Error message:**
+```json
+{
+  "error": {
+    "code": "Conflict",
+    "message": "There is an existing Capability Host with name: existing-host, provisioning state: Succeeded for workspace: /subscriptions/.../workspaces/my-workspace, cannot create a new Capability Host with name: new-host for the same ClientId."
+  }
+}
+```
+
+**Root cause:** Each account and each project can only have one active capability host. You're trying to create a capability host with a different name when one already exists at the same scope.
+
+**Solution:**
+1. **Check existing capability hosts** - Query the scope to see what already exists
+2. **Use consistent naming** - Ensure you're using the same name across all requests for the same scope
+3. **Review your requirements** - Determine if the existing capability host meets your needs
+
+**Validation steps:**
+```http
+# For account-level capability hosts
+GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01
+
+# For project-level capability hosts  
+GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01
+```
+
+#### Problem: Concurrent operations in progress
+
+**Symptoms:** You receive a 409 Conflict error indicating that another operation is currently running.
+
+**Error message:**
+```json
+{
+  "error": {
+    "code": "Conflict", 
+    "message": "Create: Capability Host my-host is currently in non creating, retry after its complete: /subscriptions/.../workspaces/my-workspace"
+  }
+}
+```
+
+**Root cause:** You're trying to create a capability host while another operation (update, delete, modify) is in progress at the same scope.
+
+**Solution:**
+1. **Wait for current operation to complete** - Check the status of ongoing operations
+2. **Monitor operation progress** - Use the operations API to track completion
+3. **Implement retry logic** - Add exponential backoff for temporary conflicts
+
+**Operation monitoring:**
+```http
+GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01
+```
+
+### Best practices for conflict prevention
+
+#### 1. Pre-request validation
+Always verify the current state before making changes:
+- Query existing capability hosts in the target scope
+- Check for any ongoing operations
+- Understand the current configuration
+
+#### 2. Implement retry logic with exponential backoff
+```csharp
+try 
+{
+    var response = await CreateCapabilityHostAsync(request);
+    return response;
+}
+catch (HttpRequestException ex) when (ex.Message.Contains("409"))
+{
+    if (ex.Message.Contains("existing Capability Host with name"))
+    {
+        // Handle name conflict - check if existing resource is acceptable
+        var existing = await GetExistingCapabilityHostAsync();
+        if (IsAcceptable(existing))
+        {
+            return existing; // Use existing resource
+        }
+        else
+        {
+            throw new InvalidOperationException("Scope already has a capability host with different name");
+        }
+    }
+    else if (ex.Message.Contains("currently in non creating"))
+    {
+        // Handle concurrent operation - implement retry with backoff
+        await Task.Delay(TimeSpan.FromSeconds(30));
+        return await CreateCapabilityHostAsync(request); // Retry once
+    }
+}
+```
+
+#### 3. Understand idempotent behavior
+The system supports idempotent create requests:
+- **Same name + same configuration** → Returns existing resource (200 OK)
+- **Same name + different configuration** → Returns 400 Bad Request  
+- **Different name** → Returns 409 Conflict
+
+#### 4. Configuration change workflow
+Since updates aren't supported, follow this sequence for configuration changes:
+1. Delete the existing capability host
+2. Wait for deletion to complete  
+3. Create a new capability host with the desired configuration
+
+
 ## 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/tools/azure-ai-search-samples.md

@@ -535,3 +535,144 @@ curl --request GET \
 ```
 
 :::zone-end
+
+:::zone pivot="java"
+
+## Code example
+
+```java
+package com.example.agents;
+
+import com.azure.ai.agents.persistent.MessagesClient;
+import com.azure.ai.agents.persistent.PersistentAgentsAdministrationClient;
+import com.azure.ai.agents.persistent.PersistentAgentsClient;
+import com.azure.ai.agents.persistent.PersistentAgentsClientBuilder;
+import com.azure.ai.agents.persistent.RunsClient;
+import com.azure.ai.agents.persistent.ThreadsClient;
+import com.azure.ai.agents.persistent.models.AISearchIndexResource;
+import com.azure.ai.agents.persistent.models.AzureAISearchToolDefinition;
+import com.azure.ai.agents.persistent.models.AzureAISearchToolResource;
+import com.azure.ai.agents.persistent.models.CreateAgentOptions;
+import com.azure.ai.agents.persistent.models.CreateRunOptions;
+import com.azure.ai.agents.persistent.models.MessageImageFileContent;
+import com.azure.ai.agents.persistent.models.MessageRole;
+import com.azure.ai.agents.persistent.models.MessageTextContent;
+import com.azure.ai.agents.persistent.models.PersistentAgent;
+import com.azure.ai.agents.persistent.models.PersistentAgentThread;
+import com.azure.ai.agents.persistent.models.RunStatus;
+import com.azure.ai.agents.persistent.models.ThreadMessage;
+import com.azure.ai.agents.persistent.models.ThreadRun;
+import com.azure.ai.agents.persistent.models.ToolResources;
+import com.azure.ai.agents.persistent.models.MessageContent;
+import com.azure.core.http.rest.PagedIterable;
+import com.azure.identity.DefaultAzureCredentialBuilder;
+
+import java.net.URL;
+import java.io.File;
+import java.io.FileNotFoundException;
+import java.net.URISyntaxException;
+import java.nio.file.Path;
+import java.util.Arrays;
+
+public class AgentExample {
+
+    public static void main(String[] args) throws FileNotFoundException, URISyntaxException {
+
+        // variables for authenticating requests to the agent service 
+        String projectEndpoint = System.getenv("PROJECT_ENDPOINT");
+        String modelName = System.getenv("MODEL_DEPLOYMENT_NAME");
+        String aiSearchConnectionId = System.getenv("AZURE_AI_CONNECTION_ID");
+        String indexName = "my-index";
+        
+        PersistentAgentsClientBuilder clientBuilder = new PersistentAgentsClientBuilder().endpoint(projectEndpoint)
+            .credential(new DefaultAzureCredentialBuilder().build());
+        PersistentAgentsClient agentsClient = clientBuilder.buildClient();
+        PersistentAgentsAdministrationClient administrationClient = agentsClient.getPersistentAgentsAdministrationClient();
+        ThreadsClient threadsClient = agentsClient.getThreadsClient();
+        MessagesClient messagesClient = agentsClient.getMessagesClient();
+        RunsClient runsClient = agentsClient.getRunsClient();
+
+        AISearchIndexResource indexResource = new AISearchIndexResource()
+            .setIndexConnectionId(aiSearchConnectionId)
+            .setIndexName(indexName);
+        ToolResources toolResources = new ToolResources()
+            .setAzureAISearch(new AzureAISearchToolResource()
+                .setIndexList(Arrays.asList(indexResource)));
+
+        String agentName = "ai_search_example";
+        CreateAgentOptions createAgentOptions = new CreateAgentOptions(modelName)
+            .setName(agentName)
+            .setInstructions("You are a helpful agent")
+            .setTools(Arrays.asList(new AzureAISearchToolDefinition()))
+            .setToolResources(toolResources);
+        PersistentAgent agent = administrationClient.createAgent(createAgentOptions);
+
+        PersistentAgentThread thread = threadsClient.createThread();
+        ThreadMessage createdMessage = messagesClient.createMessage(
+            thread.getId(),
+            MessageRole.USER,
+            "<question about information in search index>");
+
+        try {
+            //run agent
+            CreateRunOptions createRunOptions = new CreateRunOptions(thread.getId(), agent.getId())
+                .setAdditionalInstructions("");
+            ThreadRun threadRun = runsClient.createRun(createRunOptions);
+
+            waitForRunCompletion(thread.getId(), threadRun, runsClient);
+            printRunMessages(messagesClient, thread.getId());
+
+        } catch (InterruptedException e) {
+            throw new RuntimeException(e);
+        } finally {
+            //cleanup
+            threadsClient.deleteThread(thread.getId());
+            administrationClient.deleteAgent(agent.getId());
+        }
+    }
+    // A helper function to print messages from the agent
+    public static void printRunMessages(MessagesClient messagesClient, String threadId) {
+
+        PagedIterable<ThreadMessage> runMessages = messagesClient.listMessages(threadId);
+        for (ThreadMessage message : runMessages) {
+            System.out.print(String.format("%1$s - %2$s : ", message.getCreatedAt(), message.getRole()));
+            for (MessageContent contentItem : message.getContent()) {
+                if (contentItem instanceof MessageTextContent) {
+                    System.out.print((((MessageTextContent) contentItem).getText().getValue()));
+                } else if (contentItem instanceof MessageImageFileContent) {
+                    String imageFileId = (((MessageImageFileContent) contentItem).getImageFile().getFileId());
+                    System.out.print("Image from ID: " + imageFileId);
+                }
+                System.out.println();
+            }
+        }
+    }
+
+    // a helper function to wait until a run has completed running
+    public static void waitForRunCompletion(String threadId, ThreadRun threadRun, RunsClient runsClient)
+        throws InterruptedException {
+
+        do {
+            Thread.sleep(500);
+            threadRun = runsClient.getRun(threadId, threadRun.getId());
+        }
+        while (
+            threadRun.getStatus() == RunStatus.QUEUED
+                || threadRun.getStatus() == RunStatus.IN_PROGRESS
+                || threadRun.getStatus() == RunStatus.REQUIRES_ACTION);
+
+        if (threadRun.getStatus() == RunStatus.FAILED) {
+            System.out.println(threadRun.getLastError().getMessage());
+        }
+    }
+    private static Path getFile(String fileName) throws FileNotFoundException, URISyntaxException {
+        URL resource = AgentExample.class.getClassLoader().getResource(fileName);
+        if (resource == null) {
+            throw new FileNotFoundException("File not found");
+        }
+        File file = new File(resource.toURI());
+        return file.toPath();
+    }
+}
+```
+:::zone-end

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

@@ -6,7 +6,7 @@ services: azure-ai-agent-service
 manager: nitinme
 ms.service: azure-ai-agent-service
 ms.topic: how-to
-ms.date: 7/28/2025
+ms.date: 08/07/2025
 author: aahill
 ms.author: aahi
 ms.custom: azure-ai-agents
@@ -36,9 +36,9 @@ You can have indexes without a specified search type. By default, the Azure AI S
 
 ## Usage support
 
-|Azure AI foundry support  | Python SDK |	C# SDK | JavaScript SDK | REST API | Basic agent setup | Standard agent setup |
-|---------|---------|---------|---------|---------|---------|---------|
-| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
+|Azure AI foundry support  | Python SDK |	C# SDK | JavaScript SDK | Java SDK | REST API | Basic agent setup | Standard agent setup |
+|---------|---------|---------|---------|---------|---------|---------|---------|
+| ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ | ✔️ |
 
 ## Setup