Traga seu próprio modelo para o Serviço de Agente do Foundry

O Serviço Foundry Agent permite que você se conecte e use modelos hospedados por trás dos seus gateways de IA, como Gerenciamento de API do Azure ou outros gateways de modelos de IA gerenciados fora do Azure. Essa capacidade, chamada traga seu próprio modelo, permite que você mantenha o controle sobre os pontos de extremidade do modelo ao usar as capacidades do agente do Foundry.

Importante

Para fins desta documentação, os modelos BYOM referem-se a modelos de terceiros que você traz para o Foundry e não inclui Azure Modelos Diretos. O Serviço de Agente do Foundry dá suporte à capacidade de trazer seu próprio modelo (BYOM). Se você usar o Serviço do Foundry Agent para interagir com modelos BYOM, faça isso por sua conta e risco. Os modelos BYOM são considerados Produtos não Microsoft nos Termos do Produto Microsoft e são regidos por seus próprios termos de licença.

Ao utilizar o Serviço de Agente do Foundry para interagir com modelos BYOM, será responsável por implementar suas próprias mitigações de IA responsáveis no Serviço de Agente do Foundry, como metaprompt, filtros de conteúdo ou outros sistemas de segurança.

Se você usar o Serviço do Foundry Agent para interagir com modelos BYOM, será responsável por garantir que o uso do modelo BYOM esteja em conformidade com seus requisitos de tratamento de dados. Você é responsável por revisar todos os dados compartilhados com modelos BYOM e entender práticas de terceiros para retenção e localização de dados. É sua responsabilidade gerenciar se seus dados fluirão fora dos limites geográficos e de conformidade Azure da sua organização e quaisquer implicações relacionadas ao usar modelos BYOM.

Essa funcionalidade permite que as organizações:

  • Mantenha o controle sobre os endpoints de modelo por trás da infraestrutura corporativa existente.
  • Integre-se com segurança aos gateways empresariais usando políticas de segurança existentes.
  • Crie agentes que usam modelos sem expô-los publicamente.
  • Aplique requisitos de conformidade e governança ao acesso ao modelo de IA.

Diagrama que mostra a arquitetura do gateway de IA com fluxos do Serviço do Agente para seu gateway e modelos por trás dele.

Neste artigo, você cria uma conexão de gateway com o ponto de extremidade do modelo de IA, implanta um agente de solicitação que roteia solicitações por meio do gateway e verifica o fluxo de ponta a ponta.

Pré-requisitos

  • Uma assinatura Azure. Criar um gratuitamente.
  • Um projeto Microsoft Foundry.
  • Acesse credenciais para seu gateway de IA empresarial, como uma chave de assinatura de Gerenciamento de API, uma chave de API para outro gateway de modelo de IA não Azure ou credenciais para um provedor OAuth 2.0 usando credenciais de cliente.
  • Para gerenciar conexões por meio da linha de comando:

Permissões necessárias

Você precisa das seguintes atribuições de função:

Resource Função necessária
Projeto de fundição Usuário do Azure AI ou superior
Grupo de recursos (para implantação da conexão) Contributor

Criar uma conexão de modelo

Use o portal do Foundry para criar uma conexão com seu modelo.

Você pode escolher modelos em um recurso já existente do API Management do Azure ou em um gateway de modelo que não seja da IA do Azure. Usando essas etapas, você pode adicionar vários modelos implementando a API de conclusões de chat do OpenAI.

Para adicionar uma conexão de modelo no portal do Foundry:

  1. Entre no Microsoft Foundry.

  2. Selecione Operar>console do Administrador.

  3. Abra a guia Todos os projetos .

  4. Na lista de projetos, localize seu projeto e selecione o link na coluna recurso pai.

  5. Selecione a guia Modelos conectados ao Administrador e, em seguida, selecione Adicionar. Captura de tela de modelos externos no portal do Foundry.

    O assistente Adicionar conexão de modelo é aberto.

  6. Na página Connection Type, selecione Gerenciamento de API do Azure e selecione um nome de recurso de Gerenciamento de API existente e uma implantação de modelo. O modelo deve implementar a API compatível com OpenAI para conclusões de chat.

    Captura de tela da seleção de um recurso de Gerenciamento de API no portal do Foundry.

  7. Na página Autenticação , selecione uma opção para autenticar no Gerenciamento de API.

    Selecione uma chave de API , como uma chave de assinatura de Gerenciamento de API ou Identidade Gerenciada , se uma estiver configurada em seu projeto do Foundry.

    • Chave de API: insira o valor da chave no campo fornecido. Opcionalmente, especifique um nome de cabeçalho de chave de API a ser usado ao passar a chave de API se o gateway exigir um cabeçalho personalizado.

    • Identidade Gerenciada: na audiência, insira o serviço de destino para o token de identidade gerenciada, como https://cognitiveservices.azure.com/. Para a configuração necessária do Gerenciamento de API, consulte Configurar a autenticação de identidade gerenciada para o Gerenciamento de API.

  8. Na página Configuração do modelo , configure pelo menos uma implantação de modelo que será exibida na Foundry para uso com agentes.

    1. Selecione + Adicionar modelo.
    2. Insira um nome de implantação (usado em chamadas à API) e o nome correspondente e o nome de exibição.
    3. Salve a configuração do modelo.

    Repita as etapas anteriores para adicionar mais modelos à conexão, se necessário.

  9. Na página Avançado , opcionalmente, execute as seguintes etapas:

    1. Insira uma versão da API se necessário para suas implantações de modelo.
    2. Habilite a configuração Include deployment name in URL path se o seu gateway expõe a API de conclusão de chat em um caminho ao estilo Azure OpenAI que inclui o nome de implantação (por exemplo, /deployments/{deploymentName}/chat/completions). Deixe a configuração desabilitada se o gateway usar um caminho no estilo OpenAI sem o nome da implantação (por exemplo /chat/completions) e depender de outros mecanismos de roteamento para direcionar solicitações para a implantação correta do modelo.
    3. Selecione + Adicionar cabeçalho para adicionar um cabeçalho estático que deve ser incluído em solicitações ao gateway. Repita para adicionar vários cabeçalhos, se necessário.

  10. Selecione Adicionar.

Configurar a autenticação de identidade gerenciada para o Gerenciamento de API

Para configurar a autenticação Managed Identity no Gerenciamento de API, conclua a seguinte configuração no Azure:

  1. Habilite a identidade gerenciada no recurso de projeto do Foundry.

    1. No portal do Azure, vá para o recurso Foundry.

    2. Vá para Projetos>, selecione a > do projeto.

    3. Habilite um dos seguintes:

      • Identidade gerenciada atribuída pelo sistema ou
      • Identidade gerenciada atribuída pelo usuário .

    4. Para validação de token no Gerenciamento de API, obtenha a ID do aplicativo (cliente) da identidade gerenciada.

      1. Primeiro, obtenha o ID do objeto de identidade gerenciada da configuração de identidade gerenciada em seu projeto.
      2. Pesquise essa ID de objeto nos aplicativos empresariais do Microsoft Entra ID para localizar o ID de cliente correspondente.

  2. Valide o token de identidade gerenciada no Gerenciamento de API.

    Em sua política de entrada do Gerenciamento de API, use a política validate-azure-ad-token para impor a validação de token para solicitações do Microsoft Foundry.

    • Defina o elemento audience com o mesmo valor que foi configurado no campo Audiência da conexão do Foundry.
    • Configure o ID do aplicativo de identidade gerenciada em client-application-ids.

    Exemplo:

    <validate-azure-ad-token tenant-id="{{your-tenant-id}}" header-name="Authorization" failed-validation-httpcode="401" failed-validation-error-message="Unauthorized">
   <client-application-ids>
      <application-id>{{managed-identity-client-id}}</application-id>
   </client-application-ids>
   <audiences>
      <audience>{{audience-configured-in-foundry-connection}}</audience>
   </audiences>
</validate-azure-ad-token>

A conexão é criada e aparece na lista na guia Modelos conectados ao Administrador .

Implantações de modelo conectadas ao administrador

A Foundry implanta automaticamente os modelos que você adiciona por meio de uma conexão, para que você possa usá-los em seus projetos.

  • Cada modelo que você adiciona no assistente de conexão corresponde a uma implantação no Foundry.

  • Você pode selecionar uma implantação conectada ao administrador ao configurar o modelo de um agente. A Foundry roteia automaticamente solicitações de agentes para essas implantações por meio do gateway conectado.

Criar uma conexão de modelo

Use o CLI do Azure para criar uma conexão com modelos por trás do gateway de IA.

O Serviço de Agente dá suporte a dois tipos de conexão: conexões de Gerenciamento de API e conexões de Gateway de Modelo .

Escolha o tipo de conexão que corresponde ao gateway:

Tipo de conexão Usar quando Valor da categoria
Gerenciamento de API Você já usa Gerenciamento de API do Azure para roteamento de modelo e deseja padrões inteligentes de Gerenciamento de API. ApiManagement
Gateway Modelo Você usa OpenAI, MuleSoft ou um gateway personalizado e precisa de descoberta de modelo estático ou dinâmico. ModelGateway

Para obter especificações de conexão detalhadas, consulte os exemplos de conexão em GitHub.

Implantar a conexão

  1. Clone ou baixe o repositório de exemplos do Foundry e localize o modelo Bicep para o tipo de conexão em infrastructure/infrastructure-setup-bicep/01-connections/. O diretório contém arquivos do Bicep separados e arquivos de parâmetros para conexões de API Management e do Gateway de Modelos.

  2. Implante a conexão executando az deployment group create com seu grupo de recursos, o arquivo de modelo Bicep e o arquivo de parâmetros correspondente. Substitua os valores de espaço reservado no arquivo de parâmetros pela URL e credenciais do ponto de extremidade do gateway antes de implantar. Para obter a referência de comando completa, consulte az deployment group create.

    Dica

    Uma implantação bem-sucedida retorna provisioningState: Succeeded na saída do comando.

  3. Verifique a conexão no portal do Foundry. Vá para o portal Foundry e selecione seu projeto. Navegue até Recursos Conectados nas configurações do seu projeto. A nova conexão aparece com um status ativo e a URL do ponto de extremidade do gateway que você especificou.

Criar um agente de prompt com a conexão de modelo

Depois de criar a conexão, crie e execute um agente de prompt que usa modelos por trás do gateway. A principal diferença de um agente padrão é o formato do nome de implantação do modelo: <connection-name>/<model-name>.

  1. Defina as seguintes variáveis de ambiente:

    Variable Valor Example
    FOUNDRY_PROJECT_ENDPOINT A URL do ponto de extremidade do projeto https://<your-ai-services-account>.services.ai.azure.com/api/projects/<project-name>
    FOUNDRY_MODEL_DEPLOYMENT_NAME <connection-name>/<model-name> my-apim-connection/gpt-4o

  2. Inicialize um AIProjectClient com o ponto de extremidade e DefaultAzureCredential, em seguida, chame agents.create_version() com um PromptAgentDefinition. Defina o parâmetro model com o valor FOUNDRY_MODEL_DEPLOYMENT_NAME.

    Uma chamada bem-sucedida retorna um objeto de agente com seus campos id, name e version preenchidos.

  3. Obtenha o cliente OpenAI com project.get_openai_client(), crie uma conversa com conversations.create()e envie uma solicitação com responses.create(). Passe a referência do agente em extra_body como {"agent_reference": {"name": agent.name, "type": "agent_reference"}}.

    Uma resposta bem-sucedida retorna o texto de resposta do modelo, confirmando que o agente está roteando através do seu gateway.

    Observação

    Se a resposta falhar com um model not found erro, verifique se o FOUNDRY_MODEL_DEPLOYMENT_NAME valor usa o formato <connection-name>/<model-name>.

  4. Limpe deletando a conversa e a versão do agente quando o teste for concluído.

Para obter um exemplo de trabalho completo, consulte os exemplos de SDK agent em GitHub. Para obter detalhes da API, consulte AIProjectClient e PromptAgentDefinition.

Verificar a implantação

Após implantar seu agente, verifique se todo o pipeline está funcionando corretamente.

  1. Verificar o status da conexão — No portal da Foundry, vá para recursos conectados nas configurações do projeto. Verifique se a conexão mostra um status ativo . Se o status estiver inativo, verifique a URL e as credenciais do ponto de extremidade do gateway.

  2. Enviar um prompt de teste – use o SDK para criar uma conversa e enviar uma solicitação, conforme descrito na seção anterior. Uma resposta bem-sucedida retorna o texto de resposta do modelo, confirmando que o agente pode alcançar o modelo por meio do gateway.

  3. Examinar os logs do gateway — confirme se as solicitações são roteadas corretamente. Para gerenciamento de API, verifique API Management Analytics no portal Azure. Para outros gateways, examine o log de solicitações do gateway. Você deve ver as solicitações recebidas do ponto de extremidade do Serviço do Agente.

Dica

Se alguma etapa falhar, consulte a seção Solucionar problemas comuns para as etapas de resolução.

Detalhes do tipo de conexão

Esta seção fornece detalhes de referência sobre cada tipo de conexão e suas opções de configuração.

Conexão de Gerenciamento de API

As conexões de Gerenciamento de API fornecem padrões inteligentes e seguem as convenções padrão do Gerenciamento de API:

Configurações Valor padrão
Listar ponto de extremidade de implantações /deployments
Obter ponto de extremidade de implantação /deployments/{deploymentName}
Fornecedor AzureOpenAI

Prioridade de configuração:

  1. Valores de metadados explícitos (prioridade mais alta).
  2. Padrões padrão de fallback para Gerenciamento de API.

Métodos de autenticação:

  • Chave de API – Autenticação de chave de assinatura padrão.
  • Microsoft Entra ID — integração de identidade empresarial.

Modelo de Conexão de Gateway

As conexões de Gateway de Modelos fornecem uma interface unificada para conectar-se a vários provedores de IA. Essas conexões dão suporte à descoberta de modelo estático e dinâmico:

  • Descoberta estática – os modelos são predefinidos nos metadados de conexão. Melhor para implantações fixas e listas de modelos aprovadas pela empresa.
  • Descoberta dinâmica – Os modelos são descobertos em tempo de execução usando endpoints de API. Melhor para implantações que mudam frequentemente e catálogos gerenciados por provedores.

Os tipos de autenticação com suporte são chave de API e OAuth 2.0. As chaves de API são armazenadas com segurança e referenciadas por meio do sistema de credenciais.

Solucionar problemas comuns

Questão Resolução
A conexão mostra o status inativo Verifique se a URL do ponto de extremidade do gateway é acessível e se as credenciais de autenticação são válidas.
Agente retorna model not found erro Confirme se o FOUNDRY_MODEL_DEPLOYMENT_NAME valor usa o formato correto: <connection-name>/<model-name>.
Erros de tempo limite do gateway Verifique se os pontos de extremidade do gateway estão acessíveis da rede do Serviço do Agente. Para redes privadas, consulte as diretrizes de isolamento de rede na seção Limitações.
Falhas de autenticação Para o Gerenciamento de API, verifique sua chave de assinatura. Para o Gateway de Modelo, verifique a chave de API ou a configuração do OAuth 2.0.

Configurações suportadas

  • Somente os agentes de prompt no SDK do Agente dão suporte a esse recurso.
  • Ferramentas de agente com suporte: Interpretador de Código, Funções, Pesquisa de Arquivos, OpenAPI, Foundry IQ, Integração SharePoint, Agente de Dados Fabric, MCP e Automação de Navegador.
  • Configurações de rede com suporte:
    • Rede pública é suportada tanto para o Gerenciamento de API quanto para os gateways auto-hospedados.
    • Para isolamento de rede completo:
      • Gerenciamento de API como seu gateway de IA: implante o Foundry e o Gerenciamento de API juntos usando este modelo do GitHub.
      • Gateway auto-hospedado: Garanta que os pontos de extremidade do gateway estejam acessíveis dentro da rede virtual usada pelo Serviço de Agente.

Conteúdo relacionado

  • Last updated on