Hostitelé funkcí

Poznámka

Aktualizace hostitelů funkcí není podporována. Pokud chcete upravit capability host, musíte odstranit stávající host a vytvořit jej znovu s novou konfigurací.

Hostitelé schopností jsou dílčí prostředky, které konfigurujete jak na úrovni účtu Microsoft Foundry, tak i na úrovni projektu Foundry. Sdělí službě Foundry Agent Service, kam se mají ukládat a zpracovávat data agenta, včetně:

  • Historie konverzací
  • Nahrávání souborů
  • Vektorová úložiště

Požadavky

Proč používat hostitele schopností?

Hostitelé schopností vám umožňují použít vlastní prostředky Azure místo použití výchozích prostředků platformy spravovaných Microsoftem. Získáte tyto možnosti:

  • Data sovereignty – Zachovejte všechna data agenta v rámci předplatného Azure.
  • Řízení zabezpečení – používejte vlastní účty úložiště, databáze a vyhledávací služby.
  • Dodržování předpisů – Splnění konkrétních zákonných nebo organizačních požadavků

Jak fungují hostitelé schopností?

Vytváření capability hosts se nevyžaduje. Pokud chcete, aby agenti používali vaše vlastní prostředky Azure, vytvořte hostitele schopností jak na úrovni účtu, tak i projektu.

Výchozí chování (Microsoft spravované prostředky)

Pokud nevytvoříte hostitele funkcí, služba agenta automaticky používá Microsoft spravované Azure prostředky pro:

  • Úložiště konverzací (historie konverzací, definice agentů)
  • Úložiště souborů (nahrané dokumenty)
  • Vektorové vyhledávání (vkládání a načítání)

Přineste si vlastní prostředky

Když vytváříte hostitele schopností na úrovni účtu i projektu, vaše Azure prostředky ukládají a zpracovávají data agenta. Toto je standardní nastavení agenta. Informace o zabezpečení služby agenta naleznete v tématu Nastavení privátní sítě pro Foundry Agent Service.

Další informace o standardním nastavení agenta najdete v tématu Připravenost integrovaného podniku s nastavením standardního agenta.

Poznámka

Pro standardní nastavení agenta a základní nastavení agenta doporučujeme používat samostatné účty a projekty Foundry. Vyhněte se kombinování typů nastavení ve stejném účtu Foundry.

Hierarchie konfigurace

Hostitelé funkcí fungují ve dvou odlišných oborech platnosti:

  1. Výchozí hodnoty služby (Microsoft-spravované vyhledávání a úložiště) – Používá se, když není nakonfigurovaný žádný hostitelský server.
  2. Hostitelská funkce na úrovni účtu – Povolí službu Agent na úrovni účtu.
  3. Hostitel funkcí na úrovni projektu – určuje, které prostředky BYO služba Agent Service používá pro daný konkrétní projekt.

Important

Hostitel funkcí na úrovni projektu slouží službě Agent Service k určení, které prostředky pro úložiště, konverzace a vektorové úložiště se mají pro projekt použít. Neexistuje žádná automatická dědičnost konfigurace prostředků BYO z hostitele funkcí účtu do projektu. I když hostitel schopností účtu odkazuje na připojení, Agent Service je pro projekt nepoužívá, pokud na tato připojení není explicitně odkazováno v hostiteli schopností projektu.

Pochopit omezení hostitele schopností

Při vytváření hostitelů schopností mějte na paměti tato důležitá omezení, abyste se vyhnuli konfliktům:

  • Jeden poskytovatel funkce pro každý rozsah: Každý účet a každý projekt může mít pouze jednoho aktivního poskytovatele funkce. Pokud se pokusíte vytvořit druhého hostitele schopností s jiným názvem ve stejném oboru, zobrazí se chyba 409.

  • Nemůžete aktualizovat konfigurace: Pokud potřebujete změnit konfiguraci, odstraňte existujícího hostitele funkcí a vytvořte ho znovu.

  • Předpoklad pro hostitele kapacit na úrovni účtu: Nemůžete vytvořit hostitele kapacit projektu, pokud hostitel kapacit na úrovni účtu již neexistuje.

Vytvoření připojení pro hostitele funkcí

Funkce hostuje referenční názvy připojení, které vytvoříte v účtu a projektu Foundry. Než nakonfigurujete hostitele funkcí projektu pro standardní nastavení agenta, vytvořte připojení pro prostředky, které ukládají data agenta:

  • Úložiště konverzací: připojení Azure Cosmos DB
  • Souborové úložiště: připojení Azure Storage
  • Vectorové úložiště: připojení služby Azure AI Vyhledávač

Pokud chcete použít nasazení modelu z vašeho vlastního prostředku Azure OpenAI, vytvořte také připojení k Azure OpenAI.

Pokud chcete přidat připojení na portálu Foundry, přečtěte si téma Přidání nového připojení k projektu.

Požadované vlastnosti připojení

Aby služba Agent Service mohla za běhu správně rozpoznat a používat vaše prostředky, musí mít každé připojení, na které odkazuje hostitel schopností, vyplněné následující vlastnosti:

Vlastnost Description
authType Typ ověřování pro připojení (například AAD)
category Typ prostředku Azure (například AzureStorageAccount, AzureCosmosDb, CognitiveSearch)
target Adresa URL koncového bodu služby pro prostředek (ne ID prostředku)
metadata.ResourceId Úplné ID prostředku Azure

Important

Pole metadata.ResourceId je povinné, aby služba Agent Service mohla za běhu správně vyhledat vaše prostředky. To platí pro připojení na úrovni projektu i na úrovni účtu, na něž odkazuje hostitel funkce.

Následující příklad ukazuje správně nakonfigurované připojení Azure Storage:

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

Poznámka

Přestože šablony připojení mohou obsahovat další pole metadat, funkčními požadavky na správné rozlišení a chování za běhu jsou platné metadata.ResourceId a správně vyplněné vlastnosti authType, category a target.

Konfigurace hostitelů funkcí

V současné době spravujete hostitele schopností pomocí rozhraní REST API. Podpora sady SDK pro správu hostitelů funkcí není dostupná.

Požadované vlastnosti (hostitel schopností projektu)

Pokud chcete použít vlastní prostředky pro data agenta (standardní nastavení agenta), nakonfigurujte hostitele funkcí projektu s následujícími vlastnostmi:

Vlastnost Účel Požadovaný prostředek Azure Příklad názvu připojení
threadStorageConnections Ukládá definice agenta a historii konverzací. Azure Cosmos DB "my-cosmosdb-connection"
vectorStoreConnections Zpracovává vektorové úložiště pro načítání a vyhledávání. Azure AI Vyhledávač "my-ai-search-connection"
storageConnections Spravuje nahrávání souborů a úložiště blobů. účet Azure Storage "my-storage-connection"

Volitelná vlastnost

Vlastnost Účel Požadovaný prostředek Azure Kdy použít
aiServicesConnections Použijte vlastní nasazení modelů Azure OpenAI Pokud chcete použít modely z existujícího modelu Azure OpenAI místo předdefinovaných modelů na úrovni účtu.

Hostitel funkcí účtu

Pomocí hostitele funkcí účtu povolte službu agenta na úrovni účtu.

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

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

Referenční informace: Rozhraní REST API pro správu účtů Foundry

Hostitel schopností projektu

Hostitel schopností pro projekt je to, z čeho služba Agent Service zjišťuje, které zdroje BYO má pro projekt použít. Všichni agenti v tomto projektu budou používat zdroje odkazované zde:

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

Referenční informace: Hostitelé schopností projektu - Vytvořit nebo aktualizovat

Volitelné: Připojení na úrovni účtu s hostiteli funkcí projektu

Můžete také definovat připojení na úrovni účtu. Při vytvoření nového projektu v rámci tohoto účtu jsou tato připojení zděděna projektem. Konfigurace hostitele schopností projektu se však nedědí – stále musíte explicitně vytvořit hostitele schopností projektu a odkázat na připojení, která má Agent Service pro daný projekt používat.

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

Poznámka

Připojení definovaná na úrovni účtu jsou zděděna novými projekty. Konfigurace hostitele pro schopnosti projektu se však nedědí. Pokud chcete tato připojení použít se službou Agent Service, musíte vytvořit hostitele schopností projektu, který explicitně odkazuje na připojení na úrovni projektu.

Ověření konfigurace

Pomocí těchto kroků ověřte, že jsou hostitelé schopností správně nakonfigurovaní:

  1. Získejte hostitele funkcí účtu a ověřte, že existuje.

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

  2. Získejte hostitele schopností projektu a potvrďte, že odkazuje na očekávané názvy připojení.

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

  3. Otestujte konfiguraci vytvořením testovacího agenta a spuštěním konverzace. Potvrďte, že:

    • Konverzace se zobrazí ve vašem Azure Cosmos DB.
    • Nahrané soubory se zobrazí ve vašem účtu Azure Storage
    • Vektorová data se zobrazí v indexu Azure AI Vyhledávač

  4. Pokud aktualizujete připojení nebo chcete změnit umístění uložení dat, odstraňte a znovu vytvořte hostitele funkcí s aktualizovanou konfigurací.

Smazat hostitele schopností

Upozornění

Odstranění hostitele schopností ovlivňuje všechny agenty, kteří na něm závisejí. Než budete pokračovat, ujistěte se, že rozumíte dopadu. Pokud například odstraníte hostitele funkcí projektu a účtu, agenti v projektu už nemají přístup k souborům, konverzacím a úložištím vektorů, ke kterým dříve přistupovali.

Odstranění hostitele schopností na úrovni účtu

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

Odstranit hostitele schopností na úrovni projektu

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

Řešení potíží

Pokud při vytváření hostitelů funkcí dochází k problémům, najdete v této části řešení nejběžnějších problémů a chyb.

Chyby konfliktu HTTP 409

Problém: Několik hostitelů schopností na jeden rozsah

Příznaky: Při pokusu o vytvoření hostitele schopností se zobrazí chyba 409 Konflikt, i když se domníváte, že obor je prázdný.

Chybová zpráva:

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

Kořenová příčina: Každý účet a každý projekt může mít pouze jednoho aktivního hostitele schopností. Pokoušíte se vytvořit host schopností s jiným názvem, když už ve stejném oboru existuje.

Řešení:

  1. Kontrola existujících hostitelů schopností – Prozkoumejte možnosti a zjistěte, co už existuje.
  2. Použití konzistentního pojmenování – Ujistěte se, že používáte stejný název ve všech požadavcích na stejný obor.
  3. Kontrola požadavků – Zjistěte, jestli stávající hostitel schopností splňuje vaše potřeby.

Postup ověření: Pomocí požadavků GET v části Ověření konfigurace, ověřte, jestli hostitel funkcí již v cílovém oboru existuje.

Problém: Probíhající souběžné operace

Příznaky: Zobrazí se chyba 409 Konflikt označující, že je aktuálně spuštěna jiná operace.

Chybová zpráva:

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

Příčina: Pokoušíte se vytvořit hostitele funkcí, zatímco probíhá jiná operace (aktualizace, odstranění, úprava) ve stejném rozsahu.

Řešení:

  1. Počkejte na dokončení aktuální operace – Zkontrolujte stav probíhajících operací.
  2. Monitorování průběhu operace – Sledování dokončení pomocí rozhraní API operací
  3. Implementovat logiku opakování – Použití exponenciálního zpoždění pro dočasné konflikty

Monitorování operací:

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

Osvědčené postupy pro prevenci konfliktů

1. Ověření předběžné žádosti

Před provedením změn vždy ověřte aktuální stav:

  • Dotazování stávajících hostitelů funkcí v cílovém rozsahu
  • Kontrola probíhajících operací
  • Vysvětlení aktuální konfigurace

2. Implementace logiky opakování s exponenciálním zpožováním

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. Vysvětlení idempotentního chování

Systém podporuje idempotentní požadavky na vytváření:

  • Stejný název + stejná konfigurace → Vrátí existující prostředek (200 OK)
  • Stejný název + jiná konfigurace → Vrátí chybu 400 Chybný požadavek
  • Jiný název → Vrátí konflikt 409

4. Pracovní postup změny konfigurace

Vzhledem k tomu, že aktualizace nejsou podporované, postupujte podle této sekvence změn konfigurace:

  1. Odstranění existujícího hostitele schopností
  2. Počkejte na dokončení odstranění.
  3. Vytvořte nového hosta s požadovanou konfigurací schopností

Běžné scénáře

  • Vývoj a testování: Používejte prostředky spravované Microsoft. Není potřeba žádná konfigurace hostitele možností.
  • Production s požadavky na dodržování předpisů: Vytvářejte funkční hostitele s vašimi Azure Cosmos DB, úložišti a vyhledáváním AI.
  • Sdílené prostředky napříč projekty: Nakonfigurujte připojení na úrovni účtu a pak vytvořte hostitele schopností projektu pro každý projekt, který tato připojení explicitně odkazuje.

Další kroky

  • Last updated on