Depurar agentes com o Inspetor de Agente no Microsoft Foundry Toolkit

O Agent Inspector no Microsoft Foundry Toolkit for Visual Studio Code permite enviar solicitações a um agente local, inspecionar o modelo e a atividade de ferramentas e depurar seu código. Use isso para investigar respostas inesperadas antes de implantar uma alteração.

Esse fluxo de trabalho é útil para agentes hospedados, que executam seu código personalizado no Foundry Agent Service. A inspeção local ajuda você a depurar esse código. Antes do uso em produção, teste também o agente implantado com sua identidade de runtime, configuração e acesso à rede.

Neste artigo, você se conecta a um agente local, investiga uma solicitação e salva eventos de diagnóstico. O caminho principal usa o protocolo Responses. As visualizações disponíveis dependem do protocolo e dos diagnósticos que o servidor do agente fornece.

Prerequisites

  • Visual Studio Code com a extensão pública atual do Foundry Toolkit. Consulte Install Foundry Toolkit.
  • Um projeto de agente local com suas dependências, configuração de modelo e credenciais configuradas. Para começar a partir de um exemplo, siga o início rápido do agente hospedado por meio de testes locais.
  • O depurador exigido pelo seu projeto. O exemplo de Python usa a extensão Python e debugpy. Outros idiomas e exemplos têm requisitos diferentes.

Para um projeto existente, as ferramentas do Foundry Toolkit Copilot podem ajudar a preparar a configuração. Examine os arquivos gerados e siga o README.md do projeto. Não substitua seus arquivos de inicialização por uma configuração genérica.

Importante

Um agente local pode chamar modelos de nuvem e ferramentas em tempo real. Use entradas de teste não confidenciais, verifique as permissões da ferramenta e contabilize os encargos dos serviços configurados. O Inspetor não substitui as ferramentas por mocks.

Conectar e depurar

Inicie o servidor do agente antes de se conectar ao Inspector. Use a configuração de inicialização gerada do projeto para alinhar o servidor, o diretório de trabalho, o interpretador e o depurador.

  1. Inicie o agente com sua configuração de depuração documentada. Para o exemplo de Python do agente hospedado, selecione Depurar Servidor HTTP do Agente Local e pressione F5.
  2. Se o Inspetor não estiver aberto, selecione o Kit de Ferramentas do Foundry na Barra de Atividades, depois Ferramentas para Desenvolvedores>>.
  3. Verifique o endpoint no cabeçalho do Inspector. O scaffold Python atual usa http://localhost:8088. Para uma porta de servidor diferente, selecione o botão lápis ao lado do endpoint, insira a porta e selecione Conectar.
  4. Confirme se o cabeçalho mostra Conectado. O Inspector detecta automaticamente o protocolo Responses ou Invocations quando o endpoint está acessível.
  5. Defina um ponto de interrupção no código do agente e envie uma mensagem no playground. Inspecione as variáveis quando a execução for pausada e, em seguida, continue e examine a resposta.

Captura de tela da configuração de depuração do agente local e do Inspetor do Agente conectado ao localhost na porta 8088 com uma resposta bem-sucedida.

Abrir o Inspetor sozinho não inicia um servidor nem anexa um depurador. A configuração de Python gerada usa a porta 5679 para o depurador e a porta 8088 para solicitações HTTP do agente. Essas portas são separadas das portas de rastreamento OTLP.

Conectar-se a um endpoint Responses genérico

O Inspetor pode se conectar a um endpoint local genérico de Responses sem a interface de diagnóstico de desenvolvimento completa. Você pode inspecionar os eventos de respostas que o servidor envia, mas o grafo de fluxo de trabalho e sua exibição de entrada e saída não estão disponíveis.

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

Enviar uma invocação HTTP

Use invocações HTTP quando o agente aceitar um corpo de solicitação personalizado em vez de uma mensagem de conversa. O formato de solicitação e o protocolo de resposta do servidor determinam como o Inspetor envia e exibe o resultado.

  1. Conecte-se ao servidor de invocações HTTP em execução. O Inspetor detecta o protocolo automaticamente.
  2. Insira o corpo da solicitação exigido pelo seu agente. Se o servidor expor uma especificação OpenAPI compatível, o Inspector poderá preencher um exemplo. Revise-o antes de enviar ou siga o formato de solicitação do exemplo se nenhum exemplo estiver disponível.
  3. Selecione a engrenagem de configurações de solicitação ao lado do campo de 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 dá suporte a uma resposta de streaming.
  4. Selecione Enviar e inspecione o status e o corpo da resposta.
  5. Alterne entre Visualização para saída formatada e Raw para a resposta subjacente. O painel de detalhes também inclui E/S e Chamadas de LLM. Os detalhes de modelo, ferramenta e token dependem de eventos de servidor reconhecidos, portanto, nem todas as respostas preenchem todas as guias.

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

Para uma resposta de streaming, Parar desconecta o fluxo do cliente. Para uma invocação sondada, Cancel envia uma solicitação de cancelamento para o servidor. Nenhuma ação garante que o processo do agente ou uma operação de ferramenta externa tenha parado.

Essa exibição não é um cliente WebSocket. As amostras do Protocolo de Atividade usam um playground diferente. Consulte Escolha outro protocolo ou exemplo para o caminho de teste local apropriado.

Usar o Inspetor

Comece com uma solicitação que testa o comportamento que você deseja entender. Para uma ferramenta de clima, por exemplo, solicite informações que exijam essa ferramenta, em vez de uma resposta geral que o modelo possa produzir sem ela.

  1. Envie a solicitação no playground e examine a resposta de streaming.
  2. Use as guias de detalhes para localizar a operação lenta ou com falha.
  3. Inspecione o evento ou a chamada de ferramenta relevante, altere seu código ou configuração e repita a solicitação.

Pressione Enter para enviar ou Shift+Enter para adicionar uma nova linha. Para relembrar uma solicitação anterior, coloque o cursor no início da entrada e pressione Seta para cima. Pressione Seta para baixo no final para se mover em direção a solicitações mais recentes e retornar ao rascunho não enviado.

Você pode editar uma solicitação recuperada antes de enviá-la. O histórico de entrada é uma conveniência dentro do Inspetor, não um repositório durável de prompts salvos.

View Utilize-o para
Overview Siga a cascata de latência e a linha do tempo de execução ordenada. Selecione todas as execuções ou uma execução para diferenciar a atividade do modelo e da ferramenta do tempo entre as execuções.
Tokens Analise o uso relatado de tokens de entrada e saída. Dados de uso ausentes não são um resultado de token zero.
Eventos Inspecione os eventos de Responses analisados, incluindo erros, chamadas de função e resultados. Pesquise por tipo de evento ou conteúdo JSON e filtre por categoria.
Ferramentas Inspecione as chamadas de ferramenta agrupadas por execução de resposta, incluindo status, ID de chamada, argumentos e resultados.

O rodapé de resposta mostra as informações de modelo, duração, uso de token e carimbo de data/hora quando fornecidas. Os resumos de raciocínio e texto de raciocínio aparecem em seções recolhidas separadas quando o agente os emite. O Inspetor não gera raciocínio ausente nem expõe informações que o provedor de modelos não retorna.

Inspecionar ferramentas e permissões

Use Tools para verificar se o agente chamou a ferramenta esperada com os argumentos esperados e recebeu um resultado. Uma resposta de modelo bem-sucedida não prova que uma ferramenta foi executada. Se o código usar um mock, o resultado exibido ainda será um resultado de mock.

Captura de tela da guia Ferramentas com chamadas agrupadas por execução e uma chamada de ferramenta expandida mostrando seus argumentos e resultados.

Quando uma resposta fica aguardando aprovação do PROTOCOLO MCP (Model Context Protocol) ou consentimento do OAuth, as solicitações pendentes aparecem acima da entrada da mensagem. Conceda apenas o acesso que você pretende permitir.

Para uma chamada de ferramenta MCP, selecione Mostrar argumentos, examine as entradas e selecione Aprovar ou Negar. Aprovar tudo e negar tudo se aplicam às solicitações pendentes, não a uma política de aprovação de ferramenta permanente.

Para consentimento do OAuth, conclua a autorização do navegador e a confirmação do Inspetor:

  1. Selecione Open consent para a solicitação pendente.
  2. Conclua a autorização no navegador, retorne ao Inspetor e selecione Consent done. Para recusar a autorização, selecione Cancelar em vez disso.
  3. Resolva as solicitações de consentimento restantes. Quando disponível, use Tudo pronto somente após concluir a autorização de todas as solicitações em aberto.

Abrir uma página de consentimento, por si só, não retoma a solicitação. O inspetor aguarda uma decisão sobre cada consentimento pendente antes de verificar o servidor novamente. As solicitações poderão reaparecer se o servidor ainda precisar de autorização.

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

Inspecionar fluxos de trabalho e código-fonte

Para fluxos de trabalho compatíveis do Microsoft Agent Framework, o servidor de desenvolvimento pode fornecer diagnósticos de fluxo de trabalho e localizações no código-fonte. O Inspetor usa essas informações para mostrar o grafo de execução e ajudá-lo a navegar até 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 local de origem.
  3. Defina um ponto de interrupção e repita a solicitação para inspecionar a operação no depurador.

Você pode testar fluxos de trabalho do LangGraph no playground, mas eles não oferecem suporte à visualização dos fluxos de trabalho. Um servidor sem metadados de fluxo de trabalho ainda pode retornar eventos de resposta úteis.

Investigar falhas com Copilot

Use as ações de erro em Eventos para preparar uma solicitação objetiva para o GitHub Copilot, em vez de copiar toda a conversa.

  1. Localize o evento com falha e examine seus detalhes em busca de conteúdo sensível antes de compartilhá-los.
  2. Selecione Fix ao lado do evento com falha para preparar um prompt para essa falha. No caso de várias falhas, refine a lista com os filtros de busca e de categoria e selecione Resolve with Copilot. Essa ação inclui as falhas visíveis.
  3. Revise o prompt preparado no GitHub Copilot Chat antes de enviá-lo. Examine as alterações propostas e execute novamente a solicitação do agente original para confirmar o resultado.

Essas ações não exigem o coletor OTLP. Preparar um prompt de diagnóstico não corrige o agente nem executa novamente a operação com falha.

Captura de tela da guia Eventos com respostas com falha, controles de pesquisa e filtro, ações de exportação e detalhes de diagnóstico preparados em Copilot Chat.

Salvar eventos de diagnóstico

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

  1. Em Eventos, refine a lista com o campo de pesquisa e o filtro de categoria.
  2. Selecione Copiar eventos visíveis para copiar os eventos filtrados como JSONL. Alternativamente, selecione Baixar eventos visíveis para abrir a exportação no VS Code.
  3. Para o arquivo exportado aberto, use Arquivo>Salvar como para salvar uma cópia em um local que você controla antes de fechar o documento. O arquivo de exportação aberto é um arquivo temporário, não um download permanente.

O instantâneo contém os eventos visíveis quando você seleciona a ação, não eventos futuros do agente em execução. Não salva uma versão do agente, implantações de código nem cria histórico do Cloud Trace.

Cuidado

Os eventos podem incluir prompts, respostas, argumentos de ferramenta, resultados e detalhes do erro. Examine e oculte conteúdo sensível antes de salvar ou compartilhar uma exportação.

Iniciar uma nova conversa

Selecione Limpar Chat para iniciar uma nova conversa e limpar o estado de chat, Eventos e Detalhes. Exporte quaisquer eventos de diagnóstico de que você precisar primeiro. Atualizar o mesmo agente conectado preserva seu estado de inspeção, enquanto a alteração de agentes limpa o estado obsoleto.

Para respostas, o Clear Chat é desabilitado enquanto uma resposta é transmitida ativamente. Ele permanece disponível quando a etapa pausa para aprovação ou consentimento. Não é um comando geral para parar seu agente.

Não confie no estado do Inspetor local como um arquivo de conversa durável. O servidor é responsável pela persistência da conversa, que pode ser diferente entre o desenvolvimento local e um agente hospedado implantado. O Clearing Inspector não exclui rastreamentos já coletados localmente ou armazenados no Application Insights.

Como o Inspector e o rastreamento diferem

O Inspector se comunica com o servidor local por http e transmite 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 no código-fonte. O depurador se conecta ao processo em execução de forma independente.

Esses diagnósticos em tempo real não exigem o coletor OTLP local. A guia Rastreamentos do Inspetor abre o visualizador de rastreamento separado. Ele não transforma eventos de protocolo em spans do OpenTelemetry armazenados.

Para coletar spans para análise posterior, configure o rastreamento local. Para agentes em execução, use rastreamentos de agentes hospedados.

Após o teste local, implante o agente hospedado. Teste-o separadamente porque sua identidade, ambiente e acesso à rede diferem do seu processo local.

Troubleshooting

Issue O que verificar
O inspetor não consegue se conectar. Verifique se há erros de inicialização no terminal do agente. Confirme o interpretador, as dependências e a porta HTTP e reconecte-se à porta informada pelo servidor. Abrir o Inspetor não inicia o processo.
Uma solicitação é bem-sucedida, mas os pontos de interrupção não são atingidos. Confirme se o depurador está associado ao processo que atende à solicitação e se ele usa o diretório de código-fonte correto. Para Python, consulte a resolução de problemas de depuração.
O gráfico ou a navegação de origem está ausente. Confirme se o servidor e o fluxo de trabalho fornecem diagnóstico de desenvolvimento e locais de origem. A inspeção de Respostas Genéricas não fornece esses recursos. Os fluxos de trabalho do LangGraph funcionam no playground sem visualização de fluxo de trabalho.
Os resultados da ferramenta estão ausentes. Verifique Events para falhas e aprovações pendentes. Confirme se a solicitação requer uma ferramenta e se a ferramenta está configurada e acessível.
Os detalhes do token ou do raciocínio estão ausentes. Verifique o que o modelo e o servidor emitem. O inspetor só pode exibir as informações que eles fornecem.
Imagens remotas estão bloqueadas. Selecione Carregar Imagens Remotas somente se desejar que o Inspetor as busque de hosts remotos. Essa permissão de visualização não é uma aprovação de ferramenta. Urls ou conteúdo sem suporte ainda podem falhar ao carregar. Uma imagem ausente não significa necessariamente que a solicitação do agente falhou.
O fluxo de resposta foi interrompido. Examine a resposta parcial e os detalhes da falha. Reconecte-se se necessário e examine as aprovações pendentes antes de tentar novamente. Uma nova tentativa pode repetir ações da ferramenta em tempo real.
O Inspetor tem eventos, mas o visualizador de rastreamento está vazio. Eventos de protocolo e spans OTLP são diferentes. Configure a instrumentação e inicie o coletor.

Conteúdo relacionado

  • Última atualização em