Testar, implementar e integrar agentes

  • 9 minutos

Sugestão

Consulte a guia Texto e imagens para obter mais detalhes!

Testar, implementar e publicar agentes são passos críticos na passagem do desenvolvimento para a produção. O Microsoft Foundry oferece capacidades abrangentes para validar o comportamento dos agentes, implementar no seu projeto Foundry e publicar agentes como endpoints chamáveis que consumidores externos e aplicações podem utilizar.

Estratégias de teste para agentes

Testes rigorosos garantem que os seus agentes se comportam de forma fiável em diversos cenários antes de chegarem aos utilizadores. Tanto o portal Foundry como a extensão Visual Studio Code fornecem playgrounds para testes interativos.

Usar o parque infantil de forma eficaz:

  • Happy path testing - Verifica se o agente trata corretamente dos pedidos comuns e esperados.
  • Testes de casos extremo - Experimente entradas ambíguas, informação incompleta e pedidos invulgares para revelar como os agentes lidam com a incerteza.
  • Teste de limites - Confirme que o agente respeita os limites definidos nas suas instruções testando pedidos fora do âmbito.
  • Testes de conversa com múltiplas voltas – Verifique se o agente mantém o contexto em múltiplas trocas e baseia-se em respostas anteriores.
  • Teste de invocação de ferramentas - Verifique se os agentes chamam as ferramentas certas nos momentos certos e incorporam os resultados corretamente.

Registar os resultados dos testes para acompanhar melhorias e detetar regressões.

Implantação de agentes no seu projeto

A Microsoft Foundry suporta a implementação de agentes a partir do portal ou do Visual Studio Code. A implementação guarda a configuração do agente no projeto Foundry para que possas testar e iterar.

Implementação a partir do portal da Foundry

  1. Navegue até ao seu agente no portal da Foundry
  2. Verifique se a configuração e os resultados dos testes são satisfatórios
  3. Selecionar Guardar a partir da página do agente
  4. Confirmar versão e definições de implementação

Implementação a partir do Visual Studio Code

  1. Abra o seu agente no Foundry Toolkit
  2. Selecionar Guardar no Foundry para enviar alterações de configuração
  3. Para agentes alojados, abra o menu +Build nas ferramentas de desenvolvimento e selecione Deploy to Microsoft Foundry
  4. Escolha um método de implementação:
    • Code (ZIP Code Deploy) - Empacota o seu código-fonte e efetua a implementação diretamente sem uma imagem de contentor
    • Container (BYOI) - Implementar usando uma imagem de contentor pré-construída do Azure Container Registry
  5. Selecione o seu modelo e confirme

Ambas as abordagens mantêm o seu agente dentro do espaço de trabalho do projeto, onde os membros da equipa podem aceder e testá-lo.

Agentes de distribuição num endpoint

Quando cria um agente no Microsoft Foundry, ele recebe automaticamente um endpoint estável, a sua própria identidade de agente Entra e um blueprint de agente. Publicar refere-se então à distribuição do agente para que consumidores externos e aplicações — incluindo Microsoft Teams e Microsoft 365 Copilot — possam chamá-lo.

O que cada agente inclui

Cada agente criado no Foundry é aprovisionado com:

  • endpoint estável - Um URL de invocação pronto para produção que se mantém constante mesmo ao atualizar as versões do agente.
  • identidade do agente Entra - Uma identidade Microsoft Entra dedicada com o seu próprio âmbito RBAC, separado da identidade partilhada do projeto.
  • Política de autenticação - Autenticação incorporada do Microsoft Entra ID. Os chamadores devem ter o papel Foundry User no recurso do agente. A autenticação por chave API não é suportada.

Importante

Cada agente recebe a sua própria identidade Entra dedicada. As permissões não são transferidas automaticamente da identidade do projeto. Deve atribuir funções RBAC à identidade do agente para quaisquer recursos que o agente acede. Se saltar este passo, as chamadas de ferramenta que funcionam durante o desenvolvimento falham com erros de autorização quando o agente é publicado.

Publicação para Microsoft Teams e Microsoft 365 Copilot

A partir do portal Foundry, pode publicar agentes para o Microsoft Teams e Microsoft 365 Copilot com um único passo — sem necessidade de reconstrução. O agente move-se através de um pipeline unificado para as aplicações onde os utilizadores já trabalham.

O endpoint do agente

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

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

Este URL mantém-se igual mesmo quando lanças novas versões do agente, para que os consumidores a jusante não sejam perturbados pelas atualizações.

Verificação do endpoint

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

  1. Obtenha 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 receber 403 Forbidden, confirme que o chamador tem o papel Foundry User no recurso do agente.

A atualizar agentes

Para lançar uma nova versão do agente:

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

A URL do endpoint mantém-se inalterada, pelo que as integrações existentes continuam a funcionar.

Geração de código de integração

O Foundry Toolkit for VS Code gera código de integração de exemplo para ligar a sua aplicação a um agente publicado:

  1. Selecione o seu agente destacado na vista Meus Recursos
  2. Selecionar Código de Visualização
  3. Escolha a sua pasta
  4. A extensão gera código para autenticar, ligar, enviar mensagens e processar respostas

Padrões de integração

Padrões comuns para integrar agentes publicados incluem:

  • Aplicações web - Envie mensagens de utilizador para o endpoint da API de Respostas e mostre as respostas na sua interface. Armazenar o histórico de conversas no lado do cliente para interações de múltiplos turnos.
  • Fluxos de trabalho orientados por API - Chamar o endpoint do agente a partir de serviços de back-end ativados por eventos ou programações. Processar respostas de forma programática para impulsionar ações subsequentes.
  • Interfaces de chatbot - Mapear as sessões dos utilizadores para as conversas. Gerir a troca de mensagens em tempo real através do endpoint.
  • Automação em segundo plano - Agendar chamadas de agentes para tarefas recorrentes. Alimente os dados do sistema para os agentes e os resultados dos processos para atualizar os sistemas empresariais.

Considerações sobre a produção

Os agentes em operação em produção requerem atenção a várias áreas operacionais.

  • Monitorização - Acompanhar tempos de resposta, taxas de sucesso de invocação de ferramentas, padrões de erro e consumo de tokens utilizando a integração com o Application Insights.
  • Segurança - Use identidades geridas para autenticação, aplique acesso de privilégio mínimo e defina políticas de retenção de dados.
  • Gestão de custos - Monitorizar o uso dos tokens, definir limites de comprimento de resposta e implementar limitações de taxa para evitar picos inesperados.
  • Gestão de erros - Implementar lógica de retentativa com recuo exponencial para falhas transitórias. Lide com a restrição de taxa usando estratégias de retrocesso. Valide as entradas antes de enviar aos agentes.
  • Gestão de conversas - Os endpoints dos agentes suportam atualmente apenas a API de Respostas sem estado. Guarde o histórico de conversas no seu cliente para experiências de múltiplas interações.