Depure agentes com o Agent Inspector no Microsoft Foundry Toolkit

O Agent Inspector no Microsoft Foundry Toolkit para Visual Studio Code permite-lhe enviar pedidos a um agente local, inspecionar a atividade do modelo e da ferramenta, e depurar o seu código. Utilize-o para investigar respostas inesperadas antes de implementar uma alteração.

Este fluxo de trabalho é útil para agentes alojados, que executam o seu código personalizado no Foundry Agent Service. A inspeção local ajuda-te a depurar esse código. Antes da utilização em produção, teste também o agente implementado/em execução com a sua identidade em tempo de execução, configuração e acesso à rede.

Neste artigo, liga-se a um agente local, investiga um pedido e guarda eventos de diagnóstico. O caminho principal utiliza o protocolo Responses. As vistas disponíveis dependem do protocolo e dos diagnósticos que o seu servidor agente fornece.

Prerequisites

• Visual Studio Code com a atual extensão pública Foundry Toolkit. Consulte Instalar o Foundry Toolkit.
• Um projeto de agente local com as suas dependências, configuração de modelos e credenciais configuradas. Para começar a partir de uma amostra, siga o quickstart do agente hospedado através de testes locais.
• O depurador necessário para o seu projeto. O exemplo de Python utiliza a extensão Python e debugpy. Outras línguas e exemplos têm requisitos diferentes.

Para um projeto existente, as ferramentas Foundry Toolkit Copilot podem ajudar a preparar a configuração. Revise os ficheiros gerados e siga o README.mdprojeto. Não substituas os seus ficheiros de lançamento por uma configuração genérica.

Ligar e depurar

Inicia o servidor do agente antes de ligares ao Inspector. Utilize a configuração de lançamento gerada pelo seu projeto para alinhar o servidor, diretório de trabalho, interpretador e depurador.

1. Inicie o agente com a sua configuração de depuração documentada. Para o exemplo de Python com agente hospedado, selecione Debug Local Agent HTTP Server e pressione F5.
2. Se o Inspector não estiver aberto, selecione Foundry Toolkit na Barra de Atividades, depois Developer Tools>Build>Agent Inspector.
3. Verifique o endpoint no cabeçalho do Inspector. O scaffold atual do Python utiliza http://localhost:8088. Para uma porta de servidor diferente, selecione o botão lápis ao lado do endpoint, introduza a porta e selecione Conectar.
4. Confirme que o cabeçalho mostra Ligado. O Inspector deteta automaticamente o protocolo Respostas ou Invocações quando o ponto final está acessível.
5. Define um ponto de interrupção no código do teu agente e envia uma mensagem no playground. Inspecione as variáveis quando a execução pausar, depois continue e reveja a resposta.

Abrir o Inspector sozinho não inicia um servidor nem anexa um depurador. A configuração gerada em Python utiliza a porta 5679 para o depurador e a porta 8088 para pedidos HTTP do agente. Estas portas são separadas das portas de rastreamento OTLP.

Liga-te a um endpoint genérico de Respostas

O Inspector pode ligar-se a um endpoint genérico local de Respostas sem a interface completa de diagnóstico de desenvolvimento. Podes inspecionar os eventos de Respostas que o servidor envia, mas o grafo de workflow e a sua vista de entrada e saída não estão disponíveis.

Uma conexão bem-sucedida não significa que o servidor forneça as localizações de origem, o uso do token ou o raciocínio.

Enviar uma invocação HTTP

Use invocações HTTP quando o seu agente aceita um corpo de pedido personalizado em vez de uma mensagem conversacional. O formato do pedido e o protocolo de resposta do servidor determinam como o Inspector envia e apresenta o resultado.

1. Liga-te ao teu servidor de invocações HTTP a correr. O inspetor deteta o protocolo automaticamente.
2. Introduza o corpo do pedido exigido pelo seu agente. Se o servidor expor uma especificação OpenAPI compatível, o Inspector pode preencher um exemplo. Revise-o antes de enviar, ou siga o formato do pedido do exemplo se não houver um exemplo disponível.
3. Selecione o ícone de engrenagem Definições de pedido ao lado da entrada para definir Content-Type e Accept conforme exigido pelo servidor. Por exemplo, use application/json para um corpo JSON e text/event-stream quando o servidor suporta uma resposta de streaming.
4. Selecione Enviar e inspecione o estado e o corpo da resposta.
5. Alterna entre Pré-visualização para saída formatada e Raw para a resposta subjacente. O painel de detalhes inclui também I/O e Chamadas LLM. Os detalhes do modelo, ferramenta e token dependem de eventos reconhecidos do servidor, por isso nem todas as respostas preenchem todas as abas.

O Inspetor lida com uma resposta HTTP normal, um fluxo de eventos enviados pelo servidor ou uma resposta assíncrona. Para uma resposta assíncrona 202 Accepted , interroga a invocação até à conclusão ou falha. Selecionar um formato de resposta não adiciona suporte de streaming ou assíncrono ao teu servidor.

Para uma resposta em fluxo, Stop desliga o fluxo do cliente. Para uma invocação sondada, Cancel envia um pedido de cancelamento para o servidor. Nenhuma das ações garante que o processo agente ou uma operação de ferramenta externa tenha sido interrompido.

Esta vista não é um cliente WebSocket. Os exemplos do Protocolo de Atividade utilizam um playground diferente. Veja Escolha outro protocolo ou amostra para o caminho de teste local apropriado.

Use o Inspetor

Começa com um pedido que exerça o comportamento que queres compreender. Para uma ferramenta meteorológica, por exemplo, peça informação que exija essa ferramenta, em vez de uma resposta geral que o modelo pode fornecer sem ela.

1. Envia o pedido no playground e revê a resposta do streaming.
2. Use os separadores de detalhes para encontrar a operação lenta ou falhada.
3. Inspecione o evento ou chamada de ferramenta relevante, altere o seu código ou configuração e repita o pedido.

Prima Enter para enviar ou Shift+Enter para adicionar uma nova linha. Para recordar um pedido anterior, coloque o caret no início da entrada e pressione Seta para Cima. Pressione Seta para baixo no final para avançar para pedidos mais recentes e volte ao rascunho não enviado.

Pode editar um pedido recuperado antes de o enviar. O histórico de entrada é uma conveniência dentro do Inspector, não um armazenamento duradouro de prompts guardados.

O rodapé de resposta mostra o modelo, duração, utilização do token e informação de carimbo temporal quando fornecido. O texto de raciocínio e os resumos de raciocínio aparecem em secções dobráveis separadas quando o agente os emite. O Inspector não gera raciocínios em falta nem expõe informações que o fornecedor modelo não devolve.

Inspecionar ferramentas e permissões

Utilize Ferramentas para verificar se o agente chamou a ferramenta esperada com os argumentos esperados e obteve um resultado. Uma resposta bem-sucedida do modelo não prova que uma ferramenta funcionou. Se o teu código usar um mock, o resultado apresentado continua a ser um mock.

Quando uma resposta é colocada em pausa para aprovação do Protocolo de Contexto de Modelo (MCP) ou consentimento OAuth, os pedidos em espera aparecem acima do campo de introdução da mensagem. Conceda apenas o acesso que pretende conceder.

Para uma chamada de ferramenta MCP, selecione Mostrar argumentos, reveja as entradas e depois selecione Aprovar ou Rejeitar. Aprovar tudo e Negar tudo aplicam-se aos pedidos pendentes, não uma política permanente de aprovação de ferramentas.

Para consentimento OAuth, complete tanto a autorização do navegador como a confirmação do Inspector:

1. Selecione Open consent para o pedido pendente.
2. Completar a autorização no navegador, voltar ao Inspetor e selecionar Consent done. Para recusar autorização, selecione Cancelar em vez disso.
3. Resolver os pedidos de consentimento restantes. Use All done, quando disponível, apenas após concluir a autorização para todos os pedidos abertos.

Abrir uma página de consentimento sozinho não retoma a solicitação. O inspetor espera uma decisão sobre cada consentimento pendente antes de verificar novamente o servidor. Os pedidos podem reaparecer se o servidor ainda precisar de autorização.

Verifique o resultado subsequente da ferramenta, não apenas a aprovação, para confirmar a conclusão. Para configuração de ligação e autenticação, consulte Catálogo de Ferramentas. Não mudes credenciais ou permissões da ferramenta apenas para fazer desaparecer um erro de diagnóstico.

Inspecionar fluxos de trabalho e código-fonte

Para fluxos de trabalho suportados pelo Microsoft Agent Framework, o servidor de desenvolvimento pode fornecer diagnósticos de workflow e localizações de origem. O Inspector usa esta informação para mostrar o gráfico de execução e ajudá-lo a navegar até ao seu código.

1. Selecione um nó de fluxo de trabalho para inspecionar as entradas e saídas disponíveis.
2. Clique duas vezes no nó para abrir o seu local de origem.
3. Defina um ponto de interrupção e repita a solicitação para inspecionar a operação no depurador.

Podes testar fluxos de trabalho LangGraph no playground, mas a visualização de workflow não é suportada para eles. Um servidor sem metadados de workflow pode ainda assim devolver eventos de resposta úteis.

Investigar falhas com o Copilot

Use as ações de erro em Eventos para preparar um pedido focado para o GitHub Copilot em vez de copiar toda a conversa.

1. Encontre o evento falhado e reveja os seus detalhes para conteúdos sensíveis antes de os partilhar.
2. Selecione Fix ao lado do evento falhado para preparar um prompt para essa falha. Para várias falhas, reduza a lista com filtros de pesquisa e categoria, depois selecione Resolver com Copilot. Esta ação inclui as falhas visíveis.
3. Revise o prompt preparado no GitHub Copilot Chat antes de o enviar. Revise quaisquer alterações propostas e depois execute novamente o pedido original do agente para confirmar o resultado.

Estas ações não requerem o coletor OTLP. Preparar um prompt de diagnóstico não corrige o agente nem reexecuta a operação falhada.

Salvar eventos de diagnóstico

Guarde uma captura do evento para comparar uma falha com uma execução posterior ou partilhar uma reprodução específica.

1. Em Eventos, reduza a lista com o campo de pesquisa e o filtro por categoria.
2. Selecione Copiar eventos visíveis para copiar os eventos filtrados como JSONL. Alternativamente, selecione Descarregar eventos visíveis para abrir o ficheiro exportado no VS Code.
3. Para o ficheiro exportado aberto, use o File>Save As para guardar uma cópia num local que controla antes de fechar o documento. A exportação que abriu é um ficheiro temporário, não um download permanente.

O snapshot contém os eventos visíveis quando selecionas a ação, não os eventos futuros do agente em execução. Não guarda uma versão do agente, não faz o deployment do código nem cria histórico de traços na cloud.

Comece uma nova conversa

Selecione Limpar Chat para iniciar uma nova conversa e limpar o estado de chat, Eventos e Detalhes. Exporta primeiro quaisquer eventos de diagnóstico de que precisar. Atualizar o mesmo agente ligado preserva o seu estado de inspeção, enquanto mudar de agente elimina o estado obsoleto.

Para Respostas, o Clear Chat está desativado enquanto uma resposta está a ser transmitida ativamente. Permanece disponível quando a interação faz pausa para aprovação ou consentimento. Não é uma ordem geral para parar o teu agente.

Não confie no estado local do Inspector como um arquivo de conversas duradouro. O servidor é responsável pela persistência da conversação, que pode variar entre desenvolvimento local e um agente alojado em produção. O Clearing Inspector não apaga vestígios já recolhidos localmente ou armazenados no Application Insights.

Em que diferem o Inspector e o rastreio

O Inspector comunica com o seu servidor local via HTTP e transmite os eventos de resposta. Um servidor de desenvolvimento compatível também fornece um fluxo de diagnóstico separado para detalhes do fluxo de trabalho e navegação por código-fonte. O debugger liga-se ao teu processo em execução de forma independente.

Estes diagnósticos em tempo real não requerem o coletor OTLP local. O separador Rastreios do Inspetor abre o visualizador de rastreio separado. Não transforma eventos de protocolo em spans OpenTelemetry armazenados.

Para recolher spans para análise posterior, configure rastreio local. Para agentes implantados, use rastreios de agente alojado.

Após testes locais, implemente o agente hospedado. Teste-o separadamente porque a sua identidade, ambiente e acesso à rede diferem do teu processo local.

Troubleshooting

Conteúdo relacionado

• Recolha e inspecione os rastreios no Foundry Toolkit.
• Criar fluxos de trabalho de agentes alojados no VS Code.
• Inicie o Agent Inspector baseado em navegador com a CLI do Azure Developer.