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
• 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:

• Gespreksopslag (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. Zie Privénetwerken instellen voor Foundry Agent Service voor het beveiligen van uw agentservice.

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

Configuratiehiërarchie

Mogelijkheids-hosts functioneren binnen twee verschillende niveaus:

1. Service defaults (Microsoft-managed search and storage) - wordt gebruikt wanneer er geen capability host is ingesteld.
2. Host voor mogelijkheden op accountniveau - Schakelt Agent Service in op accountniveau.
3. Host voor mogelijkheden op projectniveau - Definieert welke BYO-resources Agent Service voor dat specifieke project gebruikt.

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 capability-host met een andere naam binnen hetzelfde bereik te maken, krijgt u een 409-fout.

• 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 resources die agentgegevens opslaan:

• Gespreksopslag: Azure Cosmos DB verbinding
• Bestandsopslag: Azure Storage-verbinding
• Vectoropslag: Verbinding met Azure AI Zoeken

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.

Vereiste verbindingseigenschappen

Om Agent Service uw resources tijdens runtime correct te laten vinden en gebruiken, moet elke verbinding waarnaar door een capability host wordt verwezen, de volgende eigenschappen hebben ingevuld:

In het volgende voorbeeld ziet u een correct geconfigureerde Azure Storage verbinding:

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

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 op accountniveau in te schakelen.

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

De host voor projectmogelijkheden is de host die Agent Service leest om te bepalen welke BYO-resources voor een project moeten worden gebruikt. Alle agents in dit project gebruiken de resources waarnaar hier wordt verwezen:

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: verbindingen op accountniveau met projectondersteuningshosts

U kunt ook verbindingen definiëren op accountniveau. Wanneer een nieuw project wordt gemaakt onder dat account, worden deze verbindingen overgenomen door het project. De hostconfiguratie van de projectmogelijkheid wordt echter niet overgenomen. U moet nog steeds expliciet een projectondersteuningshost maken en verwijzen naar de verbindingen die agentservice voor dat project moet gebruiken.

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:

   • Gesprekken 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: Configureer verbindingen op accountniveau en maak vervolgens een projectondersteuningshost voor elk project dat expliciet naar deze verbindingen verwijst.

Volgende stappen

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