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 Foundry Agent Service 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:
  • Papel de colaborador na conta Foundry para criar hosts de funcionalidades
  • User Access Administrator ou Owner para atribuir acesso a recursos do Azure (para configuração padrão do agente)
  • 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 capacidades permitem-lhe utilizar os seus próprios recursos da Azure em vez de usar os recursos geridos pela plataforma 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 (representações vetoriais e recuperação de informaçã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 proteger o seu serviço de agente, consulte Configurar rede privada para o Foundry Agent Service.

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 capacidade operam em dois escopos distintos:

1. Padrões de serviço (pesquisa e armazenamento geridos por Microsoft) - Usado quando não existe um host de recurso configurado.
2. Alojamento de funcionalidade ao nível da conta - Ativa o Agent Service ao nível da conta.
3. Anfitrião de capacidade ao nível do projeto - Define que recursos BYO o Agent Service utiliza para esse projeto específico.

Compreender as restrições do anfitrião de capacidades

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 tentar criar um segundo host de capacidade com um nome diferente no mesmo escopo, receberá um erro 409.

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

• Pré-requisito para anfitrião de capacidade de conta: Não pode criar um anfitrião de capacidade de projeto a menos que já exista um anfitrião de capacidade ao nível da conta.

Criar conexões para anfitriões com 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 recursos que armazenam dados de agentes:

• Thread storage: ligações de Azure Cosmos DB
• Armazenamento de ficheiros: Ligação ao Armazenamento do Azure
• Vector store: 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.

Propriedades de ligação necessárias

Para que o Agent Service resolva corretamente e utilize os seus recursos em tempo de execução, cada ligação referenciada por um anfitrião de capacidades deve ter as seguintes propriedades preenchidas:

O exemplo seguinte mostra uma ligação Armazenamento do Azure corretamente configurada:

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

Configurar hosts de capacidade

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

Propriedades necessárias (host de capacidade 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

Anfitrião de capacidade da conta

Use um host de capacidade de conta para ativar o Serviço de Agente ao nível da conta.

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

Plataforma de capacidades do projeto

O host de capacidades do projeto é o que o Serviço de Agentes lê para determinar que recursos BYO usar num projeto. Todos os agentes deste projeto irão utilizar os recursos aqui referenciados:

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: Anfitriões de Capacidades do Projeto - Criar ou atualizar

Opcional: ligações ao nível da conta com anfitriões com capacidade de projeto

Também podes definir ligações ao nível da conta. Quando um novo projeto é criado sob essa conta, essas ligações são herdadas pelo projeto. No entanto, a configuração do host de capacidade do projeto não é herdada — deve ainda assim criar explicitamente um host de capacidade do projeto e referenciar as ligações que pretende que o Agent Service use nesse projeto.

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 que existe.

   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 capacidade do projeto e certifique-se de que faz referência aos nomes de ligaçã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.

Hosts com capacidade de eliminar

Eliminar um host de capacidade a nível de 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 capacidade ao nível do 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 capacidade, esta secção apresenta soluções para os problemas e erros mais comuns.

Erros de conflito HTTP 409

Problema: Múltiplos anfitriões 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 requisiçõ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 retroação exponencial em caso de 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é-requisição

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 retentativas 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 idempotente.

• Mesmo nome + mesma configuração → Devolve recurso existente (200 OK)
• Mesmo nome + configuração diferente → Devolve 400 pedidos maus
• Nome diferente → Retorna 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ária a configuração de 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 ligações ao nível da conta e depois crie um anfitrião de capacidades de projeto para cada projeto que faça referência explícita a essas ligações.

Próximos passos

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