Kapacitetsvärdar

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

• Konversationshistorik (trådar)
• Filuppladdningar
• Vektordatalager

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 på Foundry-kontot för att skapa värdar för funktioner
  • 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 använda kapabilitetsvärdar?

Med kapacitetsvärdar kan du använda dina egna Azure-resurser i stället för att använda standardresurserna för 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?

Det är inte nödvändigt att skapa kapacitetsvärdar. Om du vill att agenter ska använda dina egna Azure-resurser, skapa kapabilitetsvä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:

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

Ta med egna resurser

När du skapar kapacitetsvärdar på både konto- och projektnivå lagrar dina Azure resurser och bearbetar agentdata. Det här är standardkonfigurationen av agenten. För nätverkssäkrad standardagentkonfiguration distribuerar du alla relaterade resurser i samma region som ditt virtuella nätverk (VNet). Vägledning finns i Skapa en ny nätverksskyddad miljö med användarhanterad identitet.

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

Konfigurationshierarki

Kapabilitetsvärdar följer en hierarki där mer specifika konfigurationer åsidosätter de bredare.

1. Servicestandardvärden (Microsoft-hanterad sökning och lagring) – Används när ingen funktionsvärd har konfigurerats.
2. Funktionell värd på kontonivå – Tillhandahåller gemensamma standardinställningar för alla projekt under kontot.
3. Projekt-nivå funktionalitetsvärd – Åsidosätter standardvärden på kontonivå och tjänst för det specifika projektet.

Förstå begränsningar med värdkapacitet

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

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

• Du kan inte uppdatera konfigurationer: Om du behöver ändra konfigurationen tar du bort den befintliga kapabilitetsvärden och återskapar dem.

Skapa anslutningar för kapabilitetsvärdar

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

• Trådlagring: 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.

Konfigurera kapacitetsvärdar

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

Nödvändiga egenskaper (projektkapacitetsvärd)

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

Valfri egenskap

Kontofunktionsvärd

Använd en kontofunktionsvärd för att aktivera Agent Service och (valfritt) definiera standardvärden som projekt kan ärva.

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

Projekt kapacitetshanterare

Den här konfigurationen åsidosätter tjänststandarder och eventuella inställningar på kontonivå. Alla agenter i det här projektet använder dina angivna resurser:

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: Värdar för projektkapabilitet – Skapa eller uppdatera

Valfritt: Standardinställningar på kontonivå med åsidosättningar för projekt

Ange delade standardvärden på den kontonivå som gäller för alla projekt:

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 konfigurationen

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

1. Hämta kontovärdskap för funktioner och bekräfta att det finns.

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

2. Hämta projektkapacitetsvärden och bekräfta att den 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:

   • Konversationstrådar 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 kapacitetsvärdar

Ta bort en funktion 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 värd för kapabilitet på projektnivå

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

Symptom: Du får ett fel 409-konflikt när du försöker skapa en värd för funktioner, ä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."
  }
}

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

Lösning:

1. Kontrollera befintliga funktionsvärdar – Undersök 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 kapacitetsvärd i målomfånget.

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 kapabilitetsvärd medan en annan åtgärd (uppdatera, ta bort, ändra) pågår inom samma område.

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 värdar för kapacitet i 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 har stöd för idempotent skapa-begäranden:

• 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 kapacitetsvärden
2. Vänta tills borttagningen har slutförts
3. Skapa en ny funktionsvärd med önskad konfiguration

Vanliga scenarier

• Utveckling och testning: Använd Microsoft hanterade resurser. Ingen hostkonfiguration krävs.
• Produktion med efterlevnadskrav: Skapa värdar för funktionella enheter med din egen Azure Cosmos DB, lagringstjänster och AI Search.
• Delade resurser mellan projekt: Konfigurera standardvärden på kontonivå och åsidosätt sedan på projektnivå efter behov.

Nästa steg

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