Anfitriões de capacidade

Os anfitriões de capacidades são sub-recursos que configuras tanto na conta Microsoft Foundry como no âmbito do projeto Foundry. Eles indicam ao Serviço Foundry Agent onde armazenar e processar os dados do agente, incluindo:

• Histórico de conversas (tópicos)
• Carregamento de ficheiros
• Armazenamentos vetoriais

Pré-requisitos

• Um projeto Microsoft Foundry
• Se usares os teus próprios recursos para dados de agentes (configuração padrão de agente), cria os recursos e ligações Azure necessários:
  • Use os seus próprios recursos
  • Adicione uma nova ligação ao seu projeto
• Permissões necessárias:
  • Função de colaborador na conta Foundry para criar hosts de funcionalidade
  • User Access Administrator ou Owner para atribuir acesso aos recursos do Azure (para a configuração padrão de agentes)
  • Para mais detalhes, veja Permissões necessárias e Controlo de acesso baseado em funções (RBAC) no Microsoft Foundry.

Porque usar hosts com capacidade?

Os hospedeiros de capacidade permitem-lhe trazer os seus próprios recursos Azure em vez de utilizar os recursos da plataforma geridos pela Microsoft. Isto dá-lhe:

• soberania de dados - Mantenha todos os dados do agente dentro da sua subscrição Azure.
• Controlo de segurança - Use as suas próprias contas de armazenamento, bases de dados e serviços de pesquisa.
• Conformidade - Cumprir requisitos regulamentares ou organizacionais específicos.

Como funcionam os anfitriões com capacidade?

Não é necessário criar hosts com capacidade. Se quiser que os agentes usem os seus próprios recursos do Azure, crie hosts de capacidade tanto no âmbito da conta como no do projeto.

Comportamento padrão (recursos geridos pela Microsoft)

Se não criar hosts de capacidade, o Agent Service utiliza automaticamente recursos Azure geridos pela Microsoft para:

• Armazenamento de threads (histórico de conversas, definições de agentes)
• Armazenamento de ficheiros (documentos carregados)
• Pesquisa vetorial (incorporações e recuperação)

Traga os seus próprios recursos

Quando crias hosts de capacidade tanto ao nível da conta como do projeto, os teus recursos do Azure armazenam e processam os dados dos agentes. Isto é uma configuração padrão de agentes. Para a configuração de agentes padrão seguros em rede, implemente todos os recursos relacionados na mesma região da sua rede virtual (VNet). Para orientação, consulte Criar um novo ambiente seguro em rede com identidade gerida pelo utilizador.

Para saber mais sobre a configuração padrão de agentes, consulte Prontidão empresarial incorporada com configuração padrão de agentes.

Hierarquia de configuração

Os anfitriões de capacidades seguem uma hierarquia onde configurações mais específicas sobrepõem-se às mais amplas:

1. Padrões de serviço (pesquisa e armazenamento geridos pela Microsoft) - Usado quando não existe um host de capacidade configurado.
2. Gestor de capacidades a nível de conta - Fornece definições partilhadas por padrão para todos os projetos sob a conta.
3. Host de capacidade ao nível de projeto - Sobrepõe os valores predefinidos ao nível da conta e do serviço para esse projeto específico.

Compreender as limitações do host de capacidade

Ao criar anfitriões de capacidade, esteja ciente destas importantes restrições para evitar conflitos:

• Um host de capacidade por escopo: Cada conta e cada projeto podem ter apenas um host de capacidade ativa. Se tentares criar um segundo host de capacidade com um nome diferente no mesmo âmbito, obtés um conflito 409.

• Não podes atualizar configurações: Se precisares de mudar de configuração, elimina o host de capacidades existente e recria-o.

Criar conetividades para hospedeiros de capacidade

Os anfitriões de capacidades referenciam nomes de ligação que cria na sua conta e projeto Foundry. Antes de configurar um host de capacidades de projeto para a configuração padrão de agentes, crie ligações para os recursos que armazenam dados de agentes:

• Thread storage: Azure Cosmos DB conexão
• Armazenamento de ficheiros: ligação do Armazenamento do Azure
• Armazenamento vetorial: conexão Pesquisa de IA do Azure

Se quiser usar implementações de modelos a partir do seu próprio recurso Azure OpenAI, crie também uma ligação Azure OpenAI.

Para adicionar ligações no portal Foundry, veja Adicionar uma nova ligação ao seu projeto.

Configurar anfitriões de capacidade

Atualmente, gere os hosts de capacidade usando a API REST. O suporte SDK para gestão de hosts de capacidades não está disponível.

Propriedades exigidas (capacidade de anfitrião do projeto)

Para usar os seus próprios recursos para dados de agentes (configuração padrão de agente), configure o host de capacidades do projeto com as seguintes propriedades:

Propriedade opcional

Gestor de capacidades da conta

Use um host de capacidade de conta para ativar o Serviço de Agente e (opcionalmente) definir valores definidos que os projetos podem herdar.

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

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

Referência: API REST de gestão de contas Foundry

Projeto host de capacidade

Esta configuração sobrepõe-se aos valores predefinidos do serviço e a quaisquer definições ao nível da conta. Todos os agentes deste projeto utilizarão os recursos especificados:

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

Referência: Project Anfitriões de Capacidade - Criar ou atualizar

Opcional: configurações padrão ao nível da conta, permitindo substituições ao nível do projeto

Defina predefinições partilhadas ao nível da conta aplicáveis a todos os projetos.

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

Verifica a tua configuração

Use estes passos para confirmar que os anfitriões de capacidade estão configurados corretamente:

1. Obtenha o host da funcionalidade da conta e confirme a sua existência.

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

2. Obtenha o host de capacidades do projeto e confirme que referencia os nomes de conexão esperados.

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

3. Testa a tua configuração criando um agente de teste e conduzindo uma conversa. Confirme que:

   • Os tópicos de conversa aparecem no teu Azure Cosmos DB
   • Os ficheiros carregados aparecem na sua conta Armazenamento do Azure
   • Os dados vetoriais aparecem no seu índice do Pesquisa de IA do Azure

4. Se atualizares ligações ou quiseres mudar onde os dados estão armazenados, elimina e recria os hosts de capacidades com a configuração atualizada.

Eliminar capacidade dos hosts

Eliminar um host de funcionalidade ao nível da conta

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

Eliminar um host de capacidades a nível de projeto

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

Resolução de problemas

Se estiver a ter problemas ao criar hosts de funcionalidades, esta secção apresenta soluções para os problemas e erros mais comuns.

Erros de conflito HTTP 409

Problema: Vários hosts de capacidade por escopo

Sintomas: Recebe um erro de Conflito 409 ao tentar criar um host de funcionalidade, mesmo acreditando que o escopo está vazio.

Mensagem de erro:

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

Causa raiz: Cada conta e cada projeto só podem ter um host de capacidade ativa. Estás a tentar criar um host de capacidade com um nome diferente quando já existe um no mesmo âmbito.

Solução:

1. Verifique os hosts de capacidade existentes - Consulte o escopo para ver o que já existe
2. Use nomes consistentes - Certifique-se de que usa o mesmo nome em todas as solicitações para o mesmo escopo
3. Analise os seus requisitos - Determine se o host com capacidade existente satisfaz as suas necessidades

Passos de validação: Use os pedidos GET em Verificar a sua configuração para confirmar se já existe um host de capacidade no âmbito alvo.

Problema: Operações simultâneas em curso

Sintomas: Recebe um erro de Conflito 409 a indicar que outra operação está atualmente a correr.

Mensagem de erro:

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

Causa raiz: Estás a tentar criar um host de capacidade enquanto outra operação (atualizar, eliminar, modificar) está em curso no mesmo âmbito.

Solução:

1. Aguardar que a operação atual termine - Verifique o estado das operações em curso
2. Monitorizar o progresso da operação - Usar a API de operações para acompanhar a conclusão
3. Implementar lógica de retentativas - Usar retrocesso exponencial para conflitos temporários

Monitorização operacional:

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

Melhores práticas para a prevenção de conflitos

1. Validação pré-requisito

Verifique sempre o estado atual antes de fazer alterações:

• Consultar os hosts de capacidade existentes no âmbito alvo
• Verifique se há operações em curso
• Compreender a configuração atual

2. Implementar lógica de tentativas com retrocesso exponencial

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. Compreender o comportamento dos idempotentes

O sistema suporta pedidos de criação idempotentes.

• Mesmo nome + mesma configuração → Devolve recurso existente (200 OK)
• Mesmo nome + configuração diferente → Devolve 400 pedidos maus
• Nome diferente → Devolve 409 Conflito

4. Fluxo de trabalho de alteração de configuração

Como as atualizações não são suportadas, siga esta sequência para alterações de configuração:

1. Eliminar o host de capacidade existente
2. Esperar que a eliminação termine
3. Crie um novo host de capacidade com a configuração desejada

Cenários comuns

• Desenvolvimento e testes: Utilize recursos geridos Microsoft. Não é necessário configurar o host de capacidade.
• Produção com requisitos de conformidade: Crie hosts de capacidade com o seu próprio Azure Cosmos DB, Armazenamento e Pesquisa por IA.
• Recursos partilhados entre projetos: Configure os valores predefinidos ao nível da conta e depois substitua ao nível do projeto conforme necessário.

Próximos passos

• Configuração padrão do agente
• Configura o teu ambiente
• Adicione uma nova ligação ao seu projeto