Hosts de funcionalidade

Nota

Não há suporte para a atualização de hosts de capacidade. Para modificar um host de funcionalidade, você deve excluir o existente e recriá-lo com a nova configuração.

Os hosts de funcionalidade são sub-recursos que você configura na conta do Microsoft Foundry e 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

Por que usar hosts de capacidade?

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

  • soberania de dados – mantenha todos os dados do agente dentro da sua assinatura do 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 funcionalidade 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, os seus recursos do Azure armazenam e processam dados de agentes. Esta é a configuração do agente padrão. Para a instalação do agente padrão protegido pela rede, implante todos os recursos relacionados na mesma região que sua VNet (rede virtual). Para obter diretrizes, consulte Criar um novo ambiente protegido pela rede com identidade gerenciada pelo usuário.

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.

Nota

É recomendável usar contas e projetos do Foundry separados para configuração de agente padrão e configuração básica do agente. Evite misturar tipos de instalação na mesma conta do Foundry.

Hierarquia de configuração

Os hosts de funcionalidade seguem uma hierarquia em que configurações mais específicas substituem as mais amplas:

  1. padrões Service (pesquisa e armazenamento gerenciados por Microsoft) – usado quando nenhum host de funcionalidade está configurado.
  2. Host de funcionalidade no nível da conta – Fornece padrões compartilhados para todos os projetos na conta.
  3. Project-level capability host – substitui os padrões de nível de conta e serviço para o projeto 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, obterá um conflito 409.

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

Criar conexões para hosts de funcionalidade

Os hosts de funcionalidade 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 os recursos que armazenam dados do agente:

  • Thread storage: a conexão com o "Azure Cosmos DB"
  • File storage: conexão Armazenamento do Azure
  • Vector store: conexão com o 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.

Configurar hosts de capacidade

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

Propriedades necessárias (host de funcionalidade 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 Propósito Recurso de Azure necessário Nome da conexão de exemplo
threadStorageConnections Armazena definições de agente, histórico de conversas e threads de chat Azure Cosmos DB "my-cosmosdb-connection"
vectorStoreConnections Manipula o armazenamento de vetores para recuperação e pesquisa Pesquisa de IA do Azure  "my-ai-search-connection"
storageConnections Gerencia uploads de arquivos e armazenamento de blobs Conta do Armazenamento do Azure "my-storage-connection"

Propriedade opcional

Propriedade Propósito Recurso de Azure necessário Quando usar
aiServicesConnections Usar suas próprias implantações de modelo OpenAI do Azure Quando você quiser usar modelos do seu recurso Azure OpenAI existente em vez dos modelos de nível da conta internos.

Host de funcionalidade da conta

Use um host de funcionalidade de conta para habilitar o Serviço do Agente e (opcionalmente) definir padrões 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 gerenciamento de conta do Foundry

Anfitrião de funcionalidade do projeto

Essa configuração substitui os padrões de serviço e as configurações de nível de conta. Todos os agentes neste projeto usarão seus 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: Hospedagem de Capacidades do Projeto – Criar ou atualizar

Opcional: padrões de nível de conta com sobreposições de projeto

Defina padrões compartilhados no nível da conta que se aplicam 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"]
  }
}

Nota

Todos os projetos do Foundry herdarão essas configurações. Em seguida, substitua configurações específicas no nível do projeto, conforme necessário.

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

Aviso

Excluir um host de funcionalidade afetará todos os agentes que dependem dele. Certifique-se de entender o impacto antes de continuar. Por exemplo, se você excluir o host de recursos do projeto e da conta, os agentes em seu projeto não terão mais acesso aos arquivos, threads e repositórios de vetores que ele fez anteriormente.

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 funcionalidade 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 funcionalidade existentes – Consultar 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 nova tentativa – Usar retrocesso 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 funcionalidade 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 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. Entender o comportamento idempotente

O sistema suporta 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 host de funcionalidade com a configuração desejada

Cenários comuns

  • Desenvolvimento e teste: Use recursos gerenciados por Microsoft. Nenhuma configuração de host de funcionalidade é necessária.
  • Produção com requisitos de conformidade: crie hosts de funcionalidade com seus próprios Azure Cosmos DB, Armazenamento e Pesquisa de IA.
  • Recursos compartilhados entre projetos: configure os padrões no nível da conta e, em seguida, ajuste no nível do projeto conforme necessário.

Próximas etapas

  • Last updated on