Kapacitetsvärdar

Kapacitetsvärdar är underresurser som du konfigurerar på både Microsoft Foundry-kontot och Foundry-projektnivån. De berättar för Foundry Agent Service var du ska lagra och bearbeta agentdata, inklusive:

• Konversationshistorik
• Filuppladdningar
• Vektorlager

Förutsättningar

• Ett Microsoft Foundry-projekt
• Om du använder dina egna resurser för agentdata (standardagentkonfiguration) skapar du nödvändiga Azure resurser och anslutningar:
  • Använd dina egna resurser
  • Lägga till en ny anslutning till projektet
• Nödvändiga behörigheter:
  • Deltagarroll för Foundry-kontot för att skapa kapacitetsvärdar
  • Användaråtkomstadministratör eller Owner roll för att tilldela åtkomst till Azure resurser (för standardkonfiguration av agent)
  • Mer information finns i Required permissions and Role-based access control (RBAC) i Microsoft Foundry.

Varför ska jag använda funktionsvärdar?

Med kapacitetsvärdar kan du använda egna Azure-resurser i stället för att använda standardresurserna i den Microsoft-hanterade plattformen. Detta ger dig:

• Datasuveränitet – Behåll alla agentdata i din Azure prenumeration.
• Säkerhetskontroll – Använd dina egna lagringskonton, databaser och söktjänster.
• Efterlevnad – Uppfylla specifika regel- eller organisationskrav.

Hur fungerar kapabilitetsvärdar?

Att skapa kapacitetsvärdar är inte nödvändigt. Om du vill att agenter ska använda dina egna Azure-resurser, skapar du kapacitetsvärdar på både konto- och projektnivå.

Standardbeteende (Microsoft hanterade resurser)

Om du inte skapar kapacitetsvärdar använder Agent Service automatiskt Microsoft-hanterade Azure-resurser för:

• Konversationslagring (konversationshistorik, agentdefinitioner)
• Fillagring (uppladdade dokument)
• Vektorsökning (inbäddningar och hämtning)

Ta med egna resurser

När du skapar kapabilitetsvärdar på både konto- och projektnivå lagrar och bearbetar dina Azure-resurser agentdata. Det här är standardkonfigurationen av agenten. Information om hur du skyddar agenttjänsten finns i Konfigurera privata nätverk för Foundry Agent Service.

Mer information om standardkonfiguration av agent finns i Inbyggd företagsberedskap med standardkonfiguration av agent.

Konfigurationshierarki

Kapacitetsvärdar fungerar med två distinkta omfång:

1. Service standardvärden (Microsoft-hanterad sökning och lagring) – Används när ingen funktionsvärd har konfigurerats.
2. Kapacitetsvärd på kontonivå – Aktiverar agenttjänsten på kontonivå.
3. Kapacitetsvärd på projektnivå – Definierar vilka BYO-resurser Agent Service använder för det specifika projektet.

Förstå begränsningar för kapacitetsvärdar

När du skapar funktionella värdar bör du vara medveten om dessa viktiga begränsningar för att undvika konflikter:

• En kapabilitetsvärd per omfång: Varje konto och varje projekt kan bara ha en aktiv kapabilitetsvärd. Om du försöker skapa en andra kapacitetsvärd med ett annat namn inom samma omfång får du ett 409-fel.

• Du kan inte uppdatera konfigurationer: Om du behöver ändra konfigurationen, ta bort den befintliga funktionsvärden och återskapa den.

• Krav för kontokapacitetsvärd: Du kan inte skapa en projektfunktionsvärd om det inte redan finns en kapacitetsvärd på kontonivå.

Skapa anslutningar för värdar för kapabiliteter

Capability-värdar refererar till anslutningsnamn som du skapar i ditt Foundry-konto och i ditt projekt. Innan du konfigurerar en projektfunktionsvärd för standardagentkonfiguration skapar du anslutningar för resurser som lagrar agentdata:

• Konversationslagring: Azure Cosmos DB anslutning
• File storage: Azure Storage anslutning
• Vector store: Azure AI-sökning anslutning

Om du vill använda modelldistributioner från din egen Azure OpenAI-resurs skapar du även en Azure OpenAI-anslutning.

Information om hur du lägger till anslutningar i Foundry-portalen finns i Lägga till en ny anslutning till projektet.

Nödvändiga anslutningsegenskaper

För att Agent Service ska kunna hitta och använda dina resurser korrekt vid körning måste varje anslutning som en kapacitetsvärd refererar till ha följande egenskaper ifyllda:

I följande exempel visas en korrekt konfigurerad Azure Storage anslutning:

{
  "properties": {
    "authType": "AAD",
    "category": "AzureStorageAccount",
    "target": "https://{storageAccountName}.blob.core.windows.net/",
    "metadata": {
      "ResourceId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}"
    }
  }
}

Konfigurera kapabilitetsvärdar

För närvarande hanterar du kapacitetsvärdar med hjälp av REST-API:et. SDK-stöd för hantering av kapacitetsvärdar är inte tillgängligt.

Nödvändiga egenskaper (projektkapabilitetsvärd)

Om du vill använda dina egna resurser för agentdata (standardagentkonfiguration) konfigurerar du projektkapacitetsvärden med följande egenskaper:

Valfri egenskap

Kontofunktionsvärdserver

Använd en värd för kontofunktioner för att aktivera Agent Service på kontonivå.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents"
  }
}

Referens: REST API för foundry-kontohantering

Projektkapabilitetsvärd

Projektkapacitetsvärden är det som Agent Service läser för att avgöra vilka BYO-resurser som ska användas för ett projekt. Alla agenter i det här projektet använder de resurser som refereras här:

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"]
  }
}

Referens: Project Kapacitetsvärdar – Skapa eller uppdatera

Valfritt: anslutningar på kontonivå med värdar med projektstöd

Du kan också definiera anslutningar på kontonivå. När ett nytt projekt skapas under det kontot ärvs dessa anslutningar av projektet. Dock ärvs inte värdkonfigurationen för projektkapacitet – du måste fortfarande skapa en värd för projektkapacitet explicit och referera till de anslutningar som du vill att Agent Service ska använda för det projektet.

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["shared-cosmosdb-connection"],
    "vectorStoreConnections": ["shared-ai-search-connection"],
    "storageConnections": ["shared-storage-connection"]
  }
}

Verifiera din konfiguration

Använd de här stegen för att bekräfta att funktionsvärdar är korrekt konfigurerade:

1. Hämta värden för kontofunktioner och bekräfta att de finns.

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01
   

2. Hämta projektkapabilitetsvärd och bekräfta att värden refererar till de förväntade anslutningsnamnen.

   GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01
   

3. Testa konfigurationen genom att skapa en testagent och köra en konversation. Bekräfta att:

   • Konversationer visas i Azure Cosmos DB.
   • Uppladdade filer visas i ditt Azure Storage-konto
   • Vektordata visas i ditt Azure AI-sökning-index

4. Om du uppdaterar anslutningar eller vill ändra var data lagras tar du bort och återskapar kapacitetsvärdarna med den uppdaterade konfigurationen.

Ta bort kapabilitetsvärdar

Ta bort en värd för kapabiliteter på kontonivå

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

Ta bort en projektvärd för kapacitetshantering

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

Felsökning

Om du har problem med att skapa kapabilitetsvärdar innehåller det här avsnittet lösningar på de vanligaste problemen och felen.

HTTP 409-konfliktfel

Problem: Flera kapacitetsvärdar per omfång

Symtom: Du får ett 409-konfliktfelmeddelande när du försöker skapa en kapabilitetsvärd, även om du tror att omfånget är tomt.

Felmeddelande:

{
  "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."
  }
}

Orsaken: Varje konto och varje projekt kan bara ha en aktiv kapacitetsvärd. Du försöker skapa en kapabilitetsvärd med ett olika namn när en befintlig redan finns i samma omfång.

Lösning:

1. Kontrollera befintliga kapacitetsvärdar – Fråga omfånget för att se vad som redan finns
2. Använd konsekvent namngivning – Se till att du använder samma namn för alla begäranden för samma omfång
3. Granska dina krav – Ta reda på om den befintliga kapacitetsvärden uppfyller dina behov

Verifieringssteg: Använd GET-begäranden i Verifiera konfigurationen för att bekräfta om det redan finns en funktionvärd i målområdet.

Problem: Samtidiga åtgärder pågår

Symtom: Du får ett 409-konfliktfel som anger att en annan åtgärd körs för närvarande.

Felmeddelande:

{
  "error": {
    "code": "Conflict", 
    "message": "Create: Capability Host my-host is currently in non creating, retry after its complete: /subscriptions/.../workspaces/my-workspace"
  }
}

Orsaken: Du försöker skapa en funktionsvärd samtidigt som en annan åtgärd (uppdatera, ta bort, ändra) pågår inom samma omfång.

Lösning:

1. Vänta tills den aktuella åtgärden har slutförts – Kontrollera status för pågående åtgärder
2. Övervaka åtgärdsförlopp – Använd åtgärds-API:et för att spåra slutförande
3. Implementera logik för återförsök – Använd exponentiell backoff för tillfälliga konflikter

Åtgärdsövervakning:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01

Metodtips för konfliktskydd

1. Validering före begäran

Kontrollera alltid det aktuella tillståndet innan du gör ändringar:

• Förfråga befintliga funktionvärdar inom målområdet
• Sök efter pågående åtgärder
• Förstå den aktuella konfigurationen

2. Implementera logik för återförsök med exponentiell backoff

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. Förstå idempotent beteende

Systemet stöder idempotenta skapandeförfrågningar.

• Samma namn + samma konfiguration → Returnerar befintlig resurs (200 OK)
• Samma namn + annan konfiguration → returnerar 400 felaktig begäran
• Annat namn → Returnerar 409-konflikt

4. Arbetsflöde för ändring av konfiguration

Eftersom uppdateringar inte stöds följer du den här sekvensen för konfigurationsändringar:

1. Ta bort den befintliga kapabilitetsvärden
2. Vänta tills borttagningen har slutförts
3. Skapa en ny kapabilitetsvärd med önskad konfiguration

Vanliga scenarier

• Utveckling och testning: Använd Microsoft hanterade resurser. Ingen värdkonfiguration för kapacitet krävs.
• Production med efterlevnadskrav: Skapa värdar med egna Azure Cosmos DB, lagringstjänster och AI Search.
• Delade resurser mellan projekt: Konfigurera anslutningar på kontonivå och skapa sedan en projektfunktionsvärd för varje projekt som uttryckligen refererar till dessa anslutningar.

Nästa steg

• Standardagentkonfiguration
• Konfigurera din miljö
• Lägga till en ny anslutning till projektet