Capaciteitshosts

Mogelijkheidshosts zijn subresources die u configureert binnen zowel het Microsoft Foundry-account als het Foundry-projectbereik. Ze vertellen Foundry Agent Service waar agentgegevens moeten worden opgeslagen en verwerkt, waaronder:

• Gespreksgeschiedenis (discussielijnen)
• Bestandsuploads
• Vector opslag

Voorwaarden

• Een Microsoft Foundry-project
• Als u uw eigen resources gebruikt voor agentgegevens (standaardagentinstallatie), maakt u de vereiste Azure resources en verbindingen:
  • Gebruik uw eigen middelen
  • Een nieuwe verbinding toevoegen aan uw project
• Vereiste machtigingen:
  • Bijdrager-rol voor het Foundry-account om capaciteitshosts te maken
  • Gebruiker-toegangsbeheerder of Owner rol om toegang toe te wijzen aan Azure resources (voor het instellen van de standaardagent)
  • Zie Required permissions and Role-based access control (RBAC) in Microsoft Foundry voor meer informatie.

Waarom capaciteitshosts gebruiken?

Met capabilityhosts kunt u uw eigen Azure-resources gebruiken in plaats van de standaard Microsoft-beheerde platformbronnen te gebruiken. Dit geeft u het volgende:

• Datasoevereiniteit - Bewaar alle agentgegevens binnen uw Azure-abonnement.
• Beveiligingsbeheer : gebruik uw eigen opslagaccounts, databases en zoekservices.
• Naleving : voldoen aan specifieke wettelijke of organisatievereisten.

Hoe werken capaciteitshosts?

Het maken van capability hosts is niet vereist. Als u wilt dat agents uw eigen Azure-resources gebruiken, moet u "capability hosts" aanmaken op zowel account- als projectniveau.

Standaardgedrag (Microsoft-beheerde resources)

Als u geen mogelijkheidshosts maakt, gebruikt agentservice automatisch Microsoft beheerde Azure resources voor:

• Threadopslag (gespreksgeschiedenis, agentdefinities)
• Bestandsopslag (geüploade documenten)
• Vectorzoekopdrachten (insluiten en ophalen)

Breng-je-eigen middelen

Wanneer u capaciteitshosts maakt op zowel het account- als projectniveau, gebruiken uw Azure-resources opslag- en verwerkingscapaciteit voor agentgegevens. Dit is de standaardinstelling van de agent. Implementeer voor het instellen van met het netwerk beveiligde standaardagent alle gerelateerde resources in dezelfde regio als uw virtuele netwerk (VNet). Zie Een nieuwe door het netwerk beveiligde omgeving maken met door de gebruiker beheerde identiteit.

Zie Built-in enterprise readiness with standard agent setup voor informatie over standaard agentconfiguratie.

Configuratiehiërarchie

Mogelijkheidshosts volgen een hiërarchie waarbij specifiekere configuraties bredere configuraties overschrijven:

1. Service defaults (door Microsoft beheerde zoekopdrachten en opslag) - Gebruikt wanneer er geen functionaliteitshost is geconfigureerd.
2. Mogelijkheidshost op accountniveau : biedt gedeelde standaardinstellingen voor alle projecten onder het account.
3. Project-level capability-host - overschrijft standaardinstellingen op accountniveau en serviceniveau voor het specifieke project.

Inzicht in beperkingen voor capaciteitshosts

Wanneer u capaciteitshosts maakt, moet u rekening houden met deze belangrijke beperkingen om conflicten te voorkomen:

• Eén capabiliteitshost per bereik: elk account en elk project kunnen slechts één actieve capabiliteitshost hebben. Als u probeert een tweede capaciteitshost met een andere naam binnen hetzelfde bereik te maken, krijgt u een 409-conflict.

• U kunt configuraties niet bijwerken: als u de configuratie wilt wijzigen, verwijdert u de bestaande mogelijkheidshost en maakt u deze opnieuw.

Verbindingen maken voor capaciteitenhosts

Capaciteitshosts verwijzen naar verbindingsnamen die u maakt in uw Foundry-account en -project. Voordat u een projectondersteuningshost configureert voor het instellen van de standaardagent, maakt u verbindingen voor de resources die agentgegevens opslaan:

• Thread-opslag: Azure Cosmos DB-verbinding
• Bestandsopslag: Azure Storage-verbinding
• Vector store: Azure AI Zoeken connection

Als u modelimplementaties wilt gebruiken vanuit uw eigen Azure OpenAI-resource, maakt u ook een Azure OpenAI-verbinding.

Zie Een nieuwe verbinding toevoegen aan uw project om verbindingen toe te voegen in de Foundry-portal.

Capaciteitshosts configureren

Momenteel beheert u 'capability hosts' via de REST API. SDK-ondersteuning voor functieshostbeheer is niet beschikbaar.

Vereiste eigenschappen (host voor projectondersteuning)

Als u uw eigen resources wilt gebruiken voor agentgegevens (standaardagentinstallatie), configureert u de host van de projectmogelijkheid met de volgende eigenschappen:

Optionele eigenschap

Host van accountmogelijkheid

Gebruik een accountondersteuningshost om agentservice in te schakelen en (optioneel) standaardwaarden te definiëren die projecten kunnen overnemen.

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

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

Naslaginformatie: REST API voor Foundry-accountbeheer

Project capaciteitenhost

Deze configuratie overschrijft de standaardinstellingen van de service en eventuele instellingen op accountniveau. Alle agents in dit project gebruiken de opgegeven resources:

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

Naslaginformatie: Project Capability Hosts - Maken of bijwerken

Optioneel: standaardinstellingen op accountniveau met projectoverschrijvingen

Stel gedeelde standaardinstellingen in op accountniveau die van toepassing zijn op alle projecten:

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

Uw configuratie controleren

Gebruik deze stappen om te controleren of de capaciteits-hosts correct zijn geconfigureerd:

1. Haal de host van de accountmogelijkheid op en bevestig dat deze bestaat.

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

2. Haal de capaciteitshost van het project op en bevestig dat deze de verwachte verbindingsnamen correct aangeeft.

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

3. Test uw configuratie door een testagent te maken en een gesprek uit te voeren. Bevestig dat:

   • Gespreksthreads worden weergegeven in uw Azure Cosmos DB
   • Geüploade bestanden worden weergegeven in uw Azure Storage-account
   • Vectorgegevens worden weergegeven in uw Azure AI Zoeken-index

4. Als u verbindingen bijwerkt of wilt wijzigen waar gegevens worden opgeslagen, verwijdert u de hosts voor deze mogelijkheden en maakt u ze opnieuw aan met de bijgewerkte configuratie.

Functionaliteitshosts verwijderen

Een capaciteitshost van een accountniveau verwijderen

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

Een projectniveau-mogelijkheidshost verwijderen

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

Probleemoplossing

Als u problemen ondervindt bij het maken van capaciteitshosts, biedt deze sectie oplossingen voor de meest voorkomende problemen en fouten.

HTTP 409 conflictfouten

Probleem: Hosts met meerdere functionaliteiten per bereik

Symptomen: U ontvangt een 409 Conflict-fout bij het maken van een capaciteitshost, ook al denkt u dat de scope leeg is.

Foutbericht:

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

Hoofd oorzaak: Elk account en elk project kunnen slechts één actieve capability host hebben. U probeert een capaciteitshost onder een andere naam te maken, terwijl er al een bestaat binnen dezelfde omgeving.

Oplossing:

1. Bestaande capaciteitshosts controleren : voer een query uit op het bereik om te zien wat er al bestaat
2. Gebruik consistente naamgeving : zorg ervoor dat u dezelfde naam gebruikt voor alle aanvragen voor hetzelfde bereik
3. Controleer uw vereisten - Bepalen of de bestaande capaciteitshost aan uw behoeften voldoet

Validatiestappen: Gebruik de GET-aanvragen in De configuratie controleren om te controleren of er al een capaciteitshost bestaat binnen het doelbereik.

Probleem: Gelijktijdige bewerkingen worden uitgevoerd

Symptomen: Er wordt een 409-conflictfout weergegeven die aangeeft dat er momenteel een andere bewerking wordt uitgevoerd.

Foutbericht:

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

Oorzaak: U bent bezig een mogelijkhedenhost te maken, terwijl er een andere bewerking (bijwerken, verwijderen, wijzigen) binnen hetzelfde bereik gaande is.

Oplossing:

1. Wacht tot de huidige bewerking is voltooid - Controleer de status van lopende bewerkingen
2. Voortgang van de bewerking bewaken - De bewerkings-API gebruiken om de voltooiing bij te houden
3. Logica voor opnieuw proberen implementeren - Exponentieel uitstel gebruiken voor tijdelijke conflicten

Bewaking van bewerkingen:

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

Aanbevolen procedures voor conflictpreventie

1. Validatie vooraf aanvragen

Controleer altijd de huidige status voordat u wijzigingen aanbrengt:

• Query's uitvoeren op bestaande capaciteitshosts in het doelbereik
• Controleer op lopende processen
• Inzicht in de huidige configuratie

2. Implementeer logica voor herhaalpogingen met exponentieel uitstel

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. Inzicht in idempotent gedrag

Het systeem ondersteunt idempotent create-aanvragen:

• Dezelfde naam + dezelfde configuratie → retourneert bestaande resource (200 OK)
• Dezelfde naam + andere configuratie → retourneert 400 Ongeldige aanvraag
• Andere naam → retourneert 409 Conflict

4. Werkstroom voor configuratiewijziging

Aangezien updates niet worden ondersteund, volgt u deze volgorde voor configuratiewijzigingen:

1. De bestaande mogelijkheidshost verwijderen
2. Wachten tot het verwijderen is voltooid
3. Een nieuwe capability host maken met de gewenste configuratie

Algemene scenario's

• Ontwikkeling en testen: gebruik Microsoft beheerde resources. Er is geen mogelijkheid voor hostconfiguratie nodig.
• Productie met nalevingsvereisten: maak capaciteitshosts met uw eigen Azure Cosmos DB, Opslag en AI Search.
• Gedeelde resources in projecten: standaardinstellingen op accountniveau configureren en vervolgens indien nodig overschrijven op projectniveau.

Volgende stappen

• Standaardagent instellen
• Uw omgeving instellen
• Een nieuwe verbinding toevoegen aan uw project