Testar, implantar e integrar agentes

  • 9 minutos

Dica

Consulte a guia Texto e imagens para obter mais detalhes!

Testar, implantar e publicar são etapas críticas na transição do desenvolvimento para a produção. O Microsoft Foundry oferece ferramentas completas para validar o comportamento do agente, implantá-lo dentro do seu projeto e publicá-lo como um ponto de extremidade acessível, que pode ser usado por consumidores e aplicativos externos.

Estratégias de teste para agentes

O teste completo garante que seus agentes se comportem de forma confiável em diversos cenários antes de alcançar os usuários. O portal do Foundry e a extensão Visual Studio Code fornecem playgrounds para testes interativos.

Usando o playground efetivamente:

  • Teste de caminho feliz – verifique se o agente lida com solicitações comuns e esperadas corretamente.
  • Teste de casos-limite – experimente entradas ambíguas, informações incompletas e solicitações incomuns para revelar como os agentes lidam com a incerteza.
  • Teste de limite – confirme se o agente respeita os limites definidos em suas instruções testando solicitações fora do escopo.
  • Teste de conversação em várias etapas — Garante que o agente mantenha o contexto ao longo de múltiplas interações, usando respostas anteriores como referência.
  • Teste de invocação de ferramenta – verifique se os agentes chamam as ferramentas certas nos momentos certos e incorporam os resultados corretamente.

Registre os resultados do teste para acompanhar melhorias e capturar regressões.

Implantando agentes em seu projeto

O Microsoft Foundry dá suporte à implantação de agentes do portal ou do Visual Studio Code. A implantação salva a configuração do agente em seu projeto do Foundry para que você possa testar e iterar.

Implantação a partir do portal Foundry

  1. Navegue até seu agente no portal do Foundry
  2. Verificar se os resultados da configuração e do teste são satisfatórios
  3. Selecione Salvar na página do agente
  4. Confirmar configurações de versão e implantação

Publicação a partir do Visual Studio Code

  1. Abra seu agente no Foundry Toolkit
  2. Selecione Salvar no Foundry para aplicar as alterações de configuração
  3. Para agentes hospedados, abra o menu +Criar nas ferramentas de desenvolvedor e selecione Implantar no Microsoft Foundry
  4. Escolha um método de implantação:
    • Código (ZIP Code Deploy) – empacota seu código-fonte e implanta diretamente sem uma imagem de contêiner
    • Contêiner (BYOI) – Implantar usando uma imagem de contêiner predefinida de Registro de Contêiner do Azure
  5. Selecione seu modelo e confirme

Ambas as abordagens mantêm seu agente dentro do workspace do projeto, onde os membros da equipe podem acessá-lo e testá-lo.

Publicando agentes em um ponto de extremidade

Quando você cria um agente no Microsoft Foundry, ele recebe um ponto de extremidade estável, sua própria identidade de agente do Entra e um blueprint do agente automaticamente. Em seguida, a publicação refere-se à distribuição do agente para que consumidores e aplicativos externos , incluindo Microsoft Teams e Microsoft 365 Copilot, possam chamá-lo.

O que cada agente inclui

Cada agente criado na Foundry é provisionado com:

  • Ponto de extremidade estável – uma URL de invocação pronta para produção que permanece constante mesmo quando você atualiza as versões do agente.
  • Identidade do agente Entra - uma identidade dedicada do Microsoft Entra com seu próprio escopo RBAC, separada da identidade compartilhada do projeto.
  • Política de autenticação - autenticação interna do Microsoft Entra ID. Os autores da chamada devem ter a função Usuário do Foundry no recurso do agente. Não há suporte para autenticação de chave de API.

Importante

Cada agente recebe sua própria identidade Entra dedicada. As permissões não são transferidas automaticamente da identidade do projeto. Você deve atribuir funções RBAC à identidade do agente para quaisquer recursos que o agente acesse. Se você ignorar essa etapa, as chamadas de ferramenta que funcionam durante o desenvolvimento falharão com erros de autorização depois que o agente for publicado.

Publicando em Microsoft Teams e Microsoft 365 Copilot

No portal do Foundry, você pode publicar agentes para Microsoft Teams e Microsoft 365 Copilot com uma única etapa , sem necessidade de recompilação. O agente passa por um pipeline unificado para os aplicativos em que os usuários já trabalham.

O endpoint do agente

Os agentes expõem um endpoint estável usando o protocolo da Responses API:

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/agents/<agent-name>/endpoint/protocols/openai/responses

Essa URL permanece a mesma, mesmo que você implemente novas versões de agente, para que os consumidores downstream não sejam interrompidos por atualizações.

Verificando o ponto de extremidade

Depois de criar e configurar seu agente, verifique se o ponto de extremidade funciona:

  1. Obter um token de acesso:

    az account get-access-token --resource https://ai.azure.com

  2. Chame o endpoint do agente:

    curl -X POST \
  "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/agents/<agent-name>/endpoint/protocols/openai/responses?api-version=2025-11-15-preview" \
  -H "Authorization: ******" \
  -H "Content-Type: application/json" \
  -d '{"input":"Say hello"}'

Se você receber 403 Forbidden, confirme se o chamador tem a função Foundry User no recurso do agente.

Atualizando agentes

Para implantar uma nova versão do agente:

  1. Faça alterações em seu ambiente de desenvolvimento e teste minuciosamente
  2. No portal do Foundry, salve a configuração atualizada do agente
  3. O endpoint roteia o tráfego para a nova versão automaticamente

A URL do ponto de extremidade permanece inalterada, portanto, as integrações existentes continuam funcionando.

Gerando código de integração

O Foundry Toolkit para VS Code gera um código de integração de exemplo para conectar seu aplicativo a um agente publicado:

  1. Selecione seu agente implantado no modo de exibição Meus Recursos
  2. Selecionar Código de Exibição
  3. Escolha sua pasta
  4. A extensão gera código para autenticar, conectar, enviar mensagens e processar respostas

Padrões de integração

Os padrões comuns para integrar agentes publicados incluem:

  • Aplicativos Web – Enviar mensagens de usuário para o ponto de extremidade da API de Respostas e exibir respostas em sua interface do usuário. Armazene o histórico de conversas do lado do cliente para interações de múltiplas etapas.
  • Fluxos de trabalho controlados por API – acione o endpoint do agente a partir de serviços de back-end ativados por eventos ou cronogramas. Processe respostas programaticamente para orientar ações subsequentes.
  • Interfaces de chatbot – mapear sessões de usuário para conversas. Gerenciar a troca de mensagens em tempo real por meio do endpoint.
  • Automação em segundo plano – Agendar chamadas do agente para tarefas recorrentes. Alimente os dados do sistema em agentes e processe saídas para atualizar sistemas de negócios.

Considerações sobre produção

A execução de agentes em produção requer atenção a várias áreas operacionais:

  • Monitoramento – Acompanhe os tempos de resposta, as taxas de êxito da invocação da ferramenta, os padrões de erro e o consumo de tokens usando a integração do Application Insights.
  • Segurança – Use identidades gerenciadas para autenticação, aplique acesso de privilégios mínimos e defina políticas de retenção de dados.
  • Gerenciamento de custos – Monitore o uso do token, defina limites de comprimento de resposta e implemente a limitação de taxa para evitar picos inesperados.
  • Tratamento de erros – implemente a lógica de repetição com retirada exponencial para falhas transitórias. Gerenciar a limitação de taxa com estratégias de backoff. Valide as entradas antes de enviar aos agentes.
  • Gerenciamento de conversa – os pontos de extremidade do agente atualmente dão suporte apenas à API de Respostas sem estado. Para experiências de múltiplas interações, é preciso armazenar o histórico de conversas no lado do cliente.