Usar seus próprios recursos

Por padrão, o Serviço do Foundry Agent gerencia o armazenamento para arquivos, conversas e repositórios de vetores. Se sua organização exigir a propriedade total de dados, o CMK (chaves gerenciadas pelo cliente) ou o isolamento de rede, você poderá conectar seus próprios recursos Azure. Este artigo mostra como configurar os modelos de implantação para usar os recursos de Azure OpenAI, Armazenamento do Azure, Azure Cosmos DB e Pesquisa de IA do Azure  existentes com o Serviço do Agente.

Limitações

Há algumas limitações que você deve estar ciente quando planeja usar recursos existentes com o Serviço do Foundry Agent.

Se você estiver usando um projeto baseado em hub ou Azure OpenAI Assistants

No momento, não há nenhum caminho de atualização direta para migrar agentes existentes ou seus ativos de dados associados, como arquivos, conversas ou repositórios de vetores de um projeto baseado em hub para um projeto do Microsoft Foundry. Também não há um caminho de atualização para converter os Assistentes Azure OpenAI existentes em Agentes do Foundry, nem formas automáticas de migrar os arquivos, conversas ou armazenamento de vetores dos Assistentes.

Você pode reutilizar as suas implantações de modelos e cotas já existentes das Ferramentas do Foundry ou dos recursos do Azure OpenAI dentro de um projeto do Foundry.

Uso do SDK com projetos baseados em hub

A partir de maio de 2025, o Serviço de Agente de IA do Azure usará um ponto de extremidade para projetos do Foundry, em vez da cadeia de conexão era usada para projetos baseados em hub antes desse tempo. As cadeias de conexão não têm mais suporte nas versões atuais dos SDKs e da API REST. Recomendamos a criação de um novo projeto de fábrica.

Se você quiser continuar usando seu projeto baseado em hub e a cadeia de conexão, precisará:

  • Use a cadeia de conexão do seu projeto localizada em Connection string na visão geral do projeto.

    A captura de tela mostrando a cadeia de conexão herdada de um projeto.

  • Use uma das versões anteriores do SDK e o código de exemplo associado:

    • C#: 1.0.0-beta.2 ou anterior
    • Python: 1.0.0b10 ou anterior

Azure Cosmos DB para NoSQL para armazenar conversas

  • Sua conta existente de Azure Cosmos DB para NoSQL, utilizada em uma configuração padrão, precisa ter um limite de taxa de transferência total de pelo menos 3.000 RU/s. Tanto o throughput provisionado quanto o serverless são compatíveis.
  • Três a cinco contêineres serão provisionados em sua conta existente do Cosmos DB, cada um exigindo 1.000 RU/s. Três são criados durante o provisionamento do host de capacidade, e até outros dois podem ser criados dinamicamente quando você cria agentes que usam a API Responses.

Nota

  • Verifique se seu Azure recurso OpenAI e a conta e o projeto do Foundry estão na mesma região.

Pré-requisitos

  • Uma assinatura Azure – Criar uma gratuitamente.

  • CLI do Azure (versão 2.64 ou posterior).

  • Verifique se quem cria a conta e o projeto tem a função Responsável pela conta da Foundry no escopo da assinatura

    Importante

    As funções RBAC do Foundry foram renomeadas recentemente. Foundry User, Foundry Owner, Foundry Account Owner e Foundry Project Manager eram anteriormente chamados de Usuário do Azure AI, Proprietário do Azure AI, Proprietário da conta do Azure AI e Gerente de Projeto do Azure AI. Você ainda pode ver os nomes anteriores em alguns lugares enquanto essa mudança de nome está sendo implementada. Os IDs das funções e as permissões principais não são alterados com a mudança de nome.

  • Se estiver configurando uma configuração padrão, o mesmo indivíduo também deverá ter permissões para atribuir funções aos recursos necessários (Cosmos DB, Pesquisa, Armazenamento). Para obter mais informações sobre o RBAC na Foundry, consulte RBAC in Foundry.

    • A função interna necessária é Administrador de Acesso Baseado em Funções.
    • Como alternativa, ter a função Proprietário no nível da assinatura também atende a esse requisito.
    • A permissão de chave necessária é: Microsoft.Authorization/roleAssignments/write

  • Registre provedores. Os seguintes provedores devem ser registrados:

    • Microsoft.KeyVault
    • Microsoft.CognitiveServices
    • Microsoft.Storage
    • Microsoft.MachineLearningServices
    • Microsoft.Search
    • Microsoft.App
    • Microsoft.ContainerService

Para usar o Grounding com a ferramenta pesquisa do Bing o seguinte provedor deve ser registrado: Microsoft.Bing

az provider register --namespace 'Microsoft.KeyVault'
az provider register --namespace 'Microsoft.CognitiveServices'
az provider register --namespace 'Microsoft.Storage'
az provider register --namespace 'Microsoft.MachineLearningServices'
az provider register --namespace 'Microsoft.Search'
az provider register --namespace 'Microsoft.App'
az provider register --namespace 'Microsoft.ContainerService'
# only to use Grounding with Bing Search tool
az provider register --namespace 'Microsoft.Bing'

Escolha a configuração básica ou padrão do agente

Para usar seus próprios recursos, você pode editar os parâmetros nos modelos de implantação fornecidos. Para começar, determine se você deseja editar o modelo de configuração básico do agente ou o modelo de configuração do agente padrão.

Configuração básica

Essa configuração é compatível com assistentes openai e gerencia estados de agente usando o armazenamento interno da plataforma. Ele inclui as mesmas ferramentas e funcionalidades que a API de Assistentes, com suporte adicional para modelos e ferramentas não OpenAI, como Pesquisa de IA do Azure  e Bing.

Configuração Padrão

Inclui tudo na configuração básica e controle refinado sobre seus dados, permitindo que você use seus próprios recursos de Azure. Todos os dados do cliente, incluindo arquivos, conversas e repositórios de vetores, são armazenados em seus próprios recursos de Azure, oferecendo total propriedade e controle.

Configuração básica do agente: usar um recurso do OpenAI Azure existente

Substitua o valor do parâmetro de existingAoaiResourceId no template pela ID completa do recurso ARM do recurso Azure OpenAI que você deseja usar.

  1. Para obter a ID do recurso da conta Azure OpenAI, faça login no CLI do Azure e selecione a assinatura com sua conta de Ferramentas Foundry.

    az login

  2. Substitua <your-resource-group> pelo grupo de recursos que contém seu recurso e <your-ai-service-resource-name> pelo nome do recurso Azure OpenAI ou serviços de IA e execute:

    az cognitiveservices account show --resource-group <your-resource-group> --name <your-ai-service-resource-name> --query "id" --output tsv

    O valor retornado é o existingAoaiResourceId que você precisa usar no modelo.

  3. No arquivo de modelo básico do agente, substitua o seguinte marcador de posição:

    existingAoaiResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{serviceName}

Configuração do agente padrão: usar recursos de serviço e contas de armazenamento existentes

Use uma conta existente do Azure OpenAI, Armazenamento do Azure, Azure Cosmos DB para conta NoSQL, e/ou recurso Pesquisa de IA do Azure , fornecendo a ID completa do recurso ARM no arquivo de modelo do agente padrão.

Usar um recurso Azure OpenAI existente

  1. Siga as etapas na configuração básica do agente para obter a ID do recurso da conta do Foundry Tools.

  2. No arquivo de modelo de agente padrão, substitua os seguintes espaços reservados:

    existingAoaiResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{serviceName}

Usar uma conta de Armazenamento do Azure existente para armazenamento de arquivos

  1. Para obter a ID do recurso da conta de armazenamento, entre no CLI do Azure e selecione a assinatura com sua conta de armazenamento:

    az login

  2. Em seguida, execute o comando:

    az storage account show --resource-group <your-resource-group> --name <your-storage-account> --query "id" --output tsv

    A saída é o azureStorageAccountResourceId que você precisa usar no modelo.

  3. No arquivo de modelo do agente padrão, substitua o seguinte marcador de posição:

    azureStorageAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}

Use uma conta existente do Azure Cosmos DB for NoSQL para armazenamento de conversas

Uma conta do Azure Cosmos DB de NoSQL é criada para cada conta do Foundry.

Para cada projeto em uma conta do Foundry, três a cinco contêineres são implantados na mesma conta do Cosmos DB. Cada contêiner requer um mínimo de 1000 RU/s. Os nomes de contêiner são prefixados com a ID do projeto:

  • <project-id>-thread-message-store, <project-id>-system-thread-message-store e <project-id>-agent-entity-store são criados durante o provisionamento do host de capacidade.
  • <project-id>-agent-definitions-v1 e <project-id>-run-state-v1 são criados dinamicamente quando o primeiro agente do projeto que usa a API de Respostas é invocado.

Por exemplo, se dois projetos forem implantados na mesma conta do Foundry e ambos usarem agentes da API de Respostas, a conta do Cosmos DB deverá ser configurada com pelo menos 10.000 RU/s (5 contêineres × 1.000 RU/s × 2 projetos) para garantir uma taxa de transferência suficiente. Se os projetos usarem apenas agentes clássicos (API de Assistentes), 6.000 RU/s serão suficientes.

Há suporte para a taxa de transferência provisionada e os modos sem servidor.

Nota

A capacidade insuficiente de RU/s na conta do Cosmos DB causa falhas no provisionamento do host de capacidade durante a implantação.

  1. Para obter sua ID de recurso de conta Azure Cosmos DB, entre no CLI do Azure e selecione a assinatura com sua conta:

    az login

  2. Em seguida, execute o comando:

    az cosmosdb show --resource-group <your-resource-group> --name <your-cosmosdb-account> --query "id" --output tsv

    A saída é o azureCosmosDBAccountResourceId que você precisa usar no modelo.

  3. No arquivo de modelo do agente padrão, substitua o seguinte marcador de posição:

    azureCosmosDBAccountResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.DocumentDB/databaseAccounts/{cosmosDbAccountName}

Usar um recurso de Pesquisa de IA do Azure  existente

  1. Para obter sua ID do recurso Pesquisa de IA do Azure , entre no CLI do Azure e selecione a assinatura com o recurso de pesquisa:

    az login

  2. Em seguida, execute o comando:

    az search service show --resource-group <your-resource-group> --name <your-search-service> --query "id" --output tsv

  3. No arquivo de modelo do agente padrão, substitua o seguinte marcador de posição:

    aiSearchResourceId:/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}

Consulte também

  • Saiba mais sobre as diferentes ferramentas que os agentes podem usar.
  • Last updated on