Capabiliteitshosts

Capaciteitshosts 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 (draadjes)
• Bestandsuploads
• Vectoropslag

Voorwaarden

• Een Microsoft Foundry-project
• Als u uw eigen resources gebruikt voor agentgegevens (standaardagentinstallatie), maakt u de vereiste Azure resources en verbindingen:
  • Uw eigen bronnen gebruiken
  • Een nieuwe verbinding toevoegen aan uw project
• Vereiste toestemmingen:
  • Bijdragerrol op het Foundry-account om capability-hosts 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 capaciteitshosts kunt u uw eigen Azure-resources inbrengen in plaats van de standaard door Microsoft beheerde platformresources te gebruiken. Dit geeft u het volgende:

• Data-soevereiniteit - Bewaar alle gegevens van agenten 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 capaciteitshosts is niet vereist. Als u wilt dat agents uw eigen Azure-resources gebruiken, maakt u capaciteitshosts op zowel het account- als projectbereik.

Standaardgedrag (Microsoft-beheerde resources)

Als u geen mogelijkheidshosts maakt, gebruikt Agentservice automatisch door Microsoft beheerde Azure-resources voor:

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

Breng-eigen-bronnen mee

Wanneer u capaciteits-hosts maakt op zowel het account- als projectniveau, worden uw Azure resources gebruikt om gegevens van agenten te bewaren en verwerken. 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.

Voor meer informatie over het instellen van de standaardagent, zie de ingebouwde bedrijfsgereedheid met de standaardagentinstallatie.

Configuratiehiërarchie

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

1. Service defaults (Microsoft-managed search and storage) - wordt gebruikt wanneer er geen capability host is ingesteld.
2. Mogelijkheidshost op accountniveau : biedt gedeelde standaardinstellingen voor alle projecten onder het account.
3. Capability host op projectniveau - overschrijft accountniveau voor dat 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 capability-host per scope: Elk account en elk project kunnen slechts één actieve capability-host hebben. Als u probeert een tweede functiehost met een andere naam in 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.

• Vereisten voor accountfunctiehost: je kunt geen host voor projectfunctie maken, tenzij er al een functiehost op accountniveau bestaat.

Verbindingen maken voor hosts met mogelijkheden

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.

Mogelijkheidshosts configureren

Momenteel beheert u mogelijkheden hosts via de REST API. SDK-ondersteuning voor capaciteitsbeheer van hosts 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 voor accountfunctionaliteit

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

Referentie: REST API voor Foundry-accountbeheer

Project capaciteit host

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

Referentie: Project Capability Hosts - Maken of bijwerken

Optioneel: standaardinstellingen op accountniveau met projectspecifieke aanpassingen

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 voorzieningshosts correct zijn geconfigureerd:

1. Haal de host voor accountmogelijkheden op en verifieer 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 projectondersteuningshost op en bevestig dat deze verwijst naar de verwachte verbindingsnamen.

   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 mogelijkheden en maakt u ze opnieuw aan met de bijgewerkte configuratie.

Mogelijkheidshosts verwijderen

Een mogelijkheidshost op accountniveau verwijderen

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

Een host voor mogelijkheden op projectniveau 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 capaciteiten per bereik

Symptomen: U ondervindt een 409 Conflict fout tijdens het aanmaken van een capaciteitshost, ook al denkt u dat de omvang 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."
  }
}

Hoofdoorzaak: Elk account en elk project kunnen slechts één actieve capaciteitenhost hebben. Je probeert een capability host met een andere naam te maken terwijl er al een bestaat in dezelfde context.

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 probeert een functionaliteitshost te maken terwijl een andere bewerking (bijwerken, verwijderen, wijzigen) in dezelfde context wordt uitgevoerd.

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
• Controleren op lopende bewerkingen
• Inzicht in de huidige configuratie

2. Herhaallogica implementeren met exponentieel toenemende intervallen

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 functionaliteitshost verwijderen
2. Wachten tot het verwijderen is voltooid
3. Een nieuwe capaciteitshost 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