Hosts de capacidade

Os "capability hosts" são sub-recursos que você configura tanto na conta do Microsoft Foundry quanto nos escopos de projeto do Foundry. Eles informam ao Serviço do Foundry Agent onde armazenar e processar dados do agente, incluindo:

• Histórico de conversas (tópicos)
• Envios de arquivo
• Repositórios de vetores

Pré-requisitos

• Um projeto Microsoft Foundry
• Se você usar seus próprios recursos para dados do agente (configuração de agente padrão), crie os recursos e conexões da Azure necessários:
  • Usar seus próprios recursos
  • Adicionar uma nova conexão ao seu projeto
• Permissões necessárias:
  • Função Colaborador na conta do Foundry para criar hosts de capacidade
  • função User Access Administrator ou Owner para atribuir acesso a recursos do Azure (para configuração do agente padrão)
  • Para obter detalhes, consulte Permissões necessárias e Controle de acesso baseado em funções (RBAC) no Microsoft Foundry.

Por que usar hosts de capacidade?

Os hosts de funcionalidade permitem que você traga seus próprios recursos do Azure em vez de usar os recursos de plataforma padrão gerenciados pela Microsoft. Isso lhe dá:

• soberania de dados – mantenha todos os dados do agente em sua assinatura Azure.
• Controle de segurança – Use suas próprias contas de armazenamento, bancos de dados e serviços de pesquisa.
• Conformidade – atender a requisitos regulatórios ou organizacionais específicos.

Como funcionam os hosts de funcionalidade?

A criação de hosts de funcionalidade não é necessária. Se você quiser que os agentes usem seus próprios recursos do Azure, crie hosts de recurso nos escopos da conta e do projeto.

Comportamento padrão (recursos gerenciados por Microsoft)

Se você não criar hosts de funcionalidade, o Serviço de Agente usará automaticamente recursos de Azure gerenciados por Microsoft para:

• Armazenamento de threads (histórico de conversa, definições de agente)
• Armazenamento de arquivos (documentos carregados)
• Pesquisa de vetor (inserções e recuperação)

Traga seus próprios recursos

Quando você cria hospedagens de capacidade nos níveis de conta e projeto, seus recursos do Azure armazenam e processam dados dos agentes. Esta é a configuração do agente padrão. Para proteger seu serviço de agente, consulte Configurar a rede privada do Foundry Agent Service.

Para saber mais sobre a configuração do agente padrão, consulte a preparação corporativa interna com a configuração do agente padrão.

Hierarquia de configuração

Os hosts de funcionalidade operam em dois escopos distintos:

1. Padrões de serviço (Pesquisa e armazenamento gerenciados pela Microsoft) — Usado quando nenhum host de capacidade está configurado.
2. Hospedagem de recursos no nível da conta - Habilita o Agent Service no nível da conta.
3. Project-level capability host – define quais recursos BYO o Serviço de Agente usa para esse project específico.

Entender as restrições de capacidade do host

Ao criar hosts de funcionalidade, lembre-se dessas restrições importantes para evitar conflitos:

• Um host de funcionalidade por escopo: cada conta e cada projeto podem ter apenas um host de funcionalidade ativa. Se você tentar criar um segundo host de funcionalidade com um nome diferente no mesmo escopo, receberá um erro 409.

• Você não pode atualizar as configurações: se precisar alterar a configuração, exclua o host de funcionalidade existente e recrie-o.

• Pré-requisito para o host de recursos de conta: não é possível criar um host de recursos de projeto a menos que já exista um host de recursos no nível da conta.

Criar conexões para hosts de recurso

Os hosts de recurso fazem referência aos nomes de conexão que você cria em sua conta e projeto do Foundry. Antes de configurar um host de funcionalidade de projeto para a instalação do agente padrão, crie conexões para recursos que armazenam dados do agente:

• Armazenamento de thread: conexão Azure Cosmos DB
• File storage: conexão Armazenamento do Azure
• Vector store: Conexão do Pesquisa de IA do Azure 

Se você quiser usar implantações de modelo de seu próprio recurso Azure OpenAI, crie também uma conexão Azure OpenAI.

Para adicionar conexões no portal do Foundry, consulte Adicionar uma nova conexão ao seu projeto.

Propriedades de conexão necessárias

Para que o Serviço de Agente resolva e use corretamente seus recursos em runtime, cada conexão referenciada por um host de funcionalidade deve ter as seguintes propriedades preenchidas:

O exemplo a seguir mostra uma conexão de Armazenamento do Azure configurada corretamente:

{
  "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 funcionalidade

Atualmente, você gerencia hosts de funcionalidade usando a API REST. O suporte do SDK para o gerenciamento de hosts de capacidade não está disponível.

Propriedades obrigatórias (host de capacidade do projeto)

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

Propriedade opcional

Host de capacidade da conta

Use um host de funcionalidade de conta para habilitar o Serviço do Agente no 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 gerenciamento de conta do Foundry

Host de funcionalidade do projeto

O host de capacidades do projeto é o que o Agent Service lê para determinar quais recursos BYO devem ser usados para um projeto. Todos os agentes neste projeto usarão os recursos referenciados aqui:

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: Hosts de Recurso do Projeto – Criar ou atualizar

Opcional: conexões em nível de conta com hosts com capacidade de projeto

Você também pode definir conexões no nível da conta. Quando um novo projeto é criado nessa conta, essas conexões são herdadas pelo projeto. No entanto, a configuração do host de funcionalidade do projeto não é herdada– você ainda deve criar um host de funcionalidade de projeto explicitamente e referenciar as conexões que deseja que o Serviço de Agente use para esse 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"]
  }
}

Verificar sua configuração

Use estas etapas para confirmar se os hosts de funcionalidade estão configurados corretamente:

1. Obtenha o host de funcionalidade da conta e confirme se ele 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 funcionalidade do projeto e confirme se ele faz referência aos 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. Teste sua configuração criando um agente de teste e executando uma conversa. Confirme se:

   • Os tópicos de conversa aparecem em seu Azure Cosmos DB
   • Arquivos carregados aparecem em sua conta de Armazenamento do Azure
   • Os dados do vetor são exibidos no índice Pesquisa de IA do Azure 

4. Se você atualizar conexões ou quiser alterar onde os dados são armazenados, exclua e recrie os hosts de funcionalidade com a configuração atualizada.

Excluir hosts de funcionalidade

Excluir um host de funcionalidade no 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

Excluir um host de funcionalidade no 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

Solucionando problemas

Se você estiver enfrentando problemas ao criar hosts de funcionalidade, esta seção fornecerá soluções para os problemas e erros mais comuns.

Erros de conflito HTTP 409

Problema: vários hosts de capacidade por escopo

Sintomas: Você 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 funcionalidade ativo. Você está tentando criar um host de funcionalidade com um nome diferente quando já existe um no mesmo escopo.

Solução:

1. Verificar hosts de capacidade existentes — Consulta o escopo para ver o que já existe
2. Usar nomenclatura consistente – verifique se você está usando o mesmo nome em todas as solicitações para o mesmo escopo
3. Examinar seus requisitos – Determinar se o host de funcionalidade existente atende às suas necessidades

Etapas de validação: Use as solicitações GET em Verificar sua configuração para confirmar se um host de funcionalidade já existe no escopo de destino.

Problema: operações simultâneas em andamento

Sintomas: Você recebe um erro 409 Conflict indicando que outra operação está em execução no momento.

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: Você está tentando criar um host de funcionalidade enquanto outra operação (atualizar, excluir, modificar) está em andamento no mesmo escopo.

Solução:

1. Aguardar a conclusão da operação atual - Verifique o status das operações em andamento
2. Monitorar o progresso da operação – Usar a API de operações para acompanhar a conclusão
3. Implementar lógica de repetição – Usar recuo exponencial para conflitos temporários

Monitoramento da operação:

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

Práticas recomendadas para prevenção de conflitos

1. Validação de pré-solicitação

Sempre verifique o estado atual antes de fazer alterações:

• Consultar hosts de capacidade existentes no escopo de destino
• Verificar se há operações em andamento
• Entender a configuração atual

2. Implementar lógica de repetição com recuo 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. Entender o comportamento idempotente

O sistema oferece suporte para solicitações de criação idempotentes:

• Mesmo nome + mesma configuração → Retorna recurso existente (200 OK)
• Mesmo nome + configuração diferente → Retorna 400 Solicitação Incorreta
• Nome diferente → Retorna Conflito 409

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

Como não há suporte para atualizações, siga esta sequência para alterações de configuração:

1. Excluir o host de capacidade existente
2. Aguarde a conclusão da exclusão
3. Criar um novo host de capacidade com a configuração desejada

Cenários comuns

• Desenvolvimento e testes: use recursos gerenciados pela Microsoft. Nenhuma configuração de host de capacidade é necessária.
• Produção com requisitos de conformidade: crie hosts de capacidade com seu próprio Azure Cosmos DB, Armazenamento e Pesquisa de IA.
• Recursos compartilhados entre projetos: configure conexões no nível da conta e, em seguida, crie um host de funcionalidade de projeto para cada projeto que referencie explicitamente essas conexões.

Próximas etapas

• Configuração do agente padrão
• Configurar seu ambiente
• Adicionar uma nova conexão ao seu projeto