Depurador A2A

A2A (Agent2Agent) é um protocolo aberto para comunicação entre Agentes. Através do A2A, diferentes Agentes podem descobrir as capacidades uns dos outros, enviar mensagens e devolver resultados de execução.

Depurador A2A é uma ferramenta visual para depurar Agentes A2A. Pode ligar-se a um Agente A2A, enviar mensagens de teste, ver o conteúdo devolvido pelo Agente, o estado de execução e os registos de depuração, ajudando os programadores a resolver rapidamente problemas de integração de Agentes, entrega de mensagens e resultados devolvidos.

O Depurador A2A é adequado para os seguintes cenários:

Verificar se um Agente A2A consegue ligar-se normalmente

Ver o nome, a descrição, as capacidades e as Competências do Agente

Enviar texto ou anexos ao Agente para verificar a sua resposta

Resolver problemas de ligação ou de pedido, tais como autenticação, Cabeçalho, tipos de ficheiro, etc.

Ver detalhes do pedido e da resposta para identificar a causa de conteúdo devolvido anómalo

Se estiver a desenvolver ou integrar um Agente A2A, pode utilizar o Depurador A2A para verificar primeiro se o Agente consegue ligar-se e responder normalmente antes de o integrar em fluxos de trabalho empresariais formais.

Recomendamos a utilização do cliente Apidog mais recente para experimentar todas as funcionalidades do Depurador de Agentes de IA.

Ligar-se a um Agente A2A

Introduza o URL do Cartão do Agente na parte superior da página e, em seguida, clique em Ligar.

Após uma ligação bem-sucedida, o estado na parte superior será apresentado como Ligado. Neste momento, pode ver as informações do Agente e começar a enviar mensagens.

Se precisar de mudar para outro Agente, pode clicar em Desligar e, em seguida, voltar a introduzir o URL do Cartão do Agente.

Escrever Mensagens de Teste

Escreva a entrada de teste a enviar ao Agente no separador Mensagens.

A área de edição de mensagens está dividida em secções esquerda e direita:

Lado esquerdo: introduzir texto da mensagem, carregar anexos, configurar Metadados

Lado direito: ver o conteúdo bruto do pedido correspondente

Normalmente, apenas precisa de introduzir texto no lado esquerdo e clicar em Enviar. O conteúdo bruto do pedido no lado direito é utilizado principalmente para cenários de depuração avançada, por exemplo, quando precisa de confirmar a estrutura de dados real que está a ser enviada ou ajustar manualmente o conteúdo do pedido.

Enviar Mensagens

Depois de concluir a configuração da mensagem, clique em Enviar.

Se não houver atualmente nenhum Agente ligado, o Depurador A2A tentará primeiro estabelecer ligação; enviará a mensagem após a ligação ser bem-sucedida.

Após o envio, pode ver a mensagem do utilizador e o conteúdo devolvido pelo Agente na área de mensagens.

Ver Mensagens de Resposta

A área de mensagens apresenta mensagens do utilizador e respostas do Agente na sessão atual.

O conteúdo devolvido pelo Agente pode ser texto simples, ou pode incluir estado da tarefa, resultados de execução ou artefactos gerados. Pode determinar rapidamente se o Agente compreendeu e processou corretamente o pedido através da área de apresentação de mensagens.

Clique em qualquer mensagem de depuração para ver os detalhes à direita. O painel de detalhes suporta três vistas:

Pré-visualização: apresentar o conteúdo principal de forma mais legível

Conteúdo: ver texto ou dados principais na mensagem

Dados Brutos: ver o JSON bruto completo

A captura de ecrã abaixo mostra uma resposta para a pergunta:

What is the distance between the Earth and the Moon?

Pode clicar em Limpar para eliminar os registos de depuração atuais.

Ver o Cartão do Agente

O separador Cartão do Agente no painel de depuração é utilizado para ver a descrição das capacidades do Agente atualmente ligado.

Este painel apresenta:

Nome e descrição do Agente

Endereço do Agente, versão do protocolo, número da versão

Capacidades suportadas pelo Agente, como, por exemplo, se suporta respostas em streaming, notificações push, histórico de estados, etc.

Tipos de entrada e tipos de saída predefinidos

Competências declaradas pelo Agente

Erros de validação do Cartão do Agente

Conteúdo bruto do Cartão do Agente

Se o Cartão do Agente tiver campos em falta ou problemas de formatação, pode ver os erros de validação neste painel e resolver o problema comparando com o conteúdo bruto.

Adicionar Anexos

Se o Agente atual suportar entrada de ficheiros, pode clicar no botão de anexo por baixo da área de entrada de mensagens para carregar ficheiros.

O Depurador A2A determina se o carregamento de anexos é permitido com base nos tipos de entrada declarados pelo Agente:

Se o Agente suportar apenas entrada de texto, o botão de anexo fica indisponível

Se o Agente suportar apenas tipos de ficheiro específicos, só pode carregar ficheiros de tipos correspondentes

Se o Agente suportar qualquer tipo de ficheiro, pode carregar qualquer ficheiro

Após um carregamento bem-sucedido, o anexo será enviado ao Agente juntamente com a mensagem.

Configurar Autenticação

Se o Agente A2A exigir autenticação, pode configurar o método de autenticação no separador Autenticação.

São suportados os seguintes tipos de autenticação:

Método de Autenticação	Descrição
Nenhum	Não é adicionada informação de autenticação
Bearer Token	Autenticar utilizando um token
Basic Auth	Autenticar utilizando nome de utilizador e palavra-passe
API Key	Passar a API Key através de um Cabeçalho especificado

Se for devolvido um erro de não autorizado ao enviar uma mensagem, verifique se o método de autenticação, o token, o nome de utilizador/palavra-passe ou a API Key estão corretos.

Configurar Cabeçalhos

No separador Cabeçalho, pode adicionar Cabeçalhos de pedido personalizados.

Cabeçalhos personalizados são frequentemente utilizados nos seguintes cenários:

Passagem de parâmetros empresariais, tais como ID do inquilino, identificador de ambiente, etc.

Autenticação através de gateways, proxies ou serviços internos

Depuração de serviços de Agente que exigem cabeçalhos de pedido especiais

O número no separador Cabeçalho indica o número de Cabeçalhos válidos atualmente configurados.

Adicionar Metadados

Expanda Metadados por baixo da área de edição de mensagens para adicionar pares chave-valor personalizados a esta mensagem.

Os metadados são adequados para transmitir identificadores de contexto, parâmetros empresariais ou marcadores de depuração. Por exemplo, pode adicionar informações como nome do ambiente, ID de utilizador ou origem do pedido.

Perguntas Frequentes

O que devo fazer se a ligação falhar?

Verifique o seguinte:

Se o URL do Cartão do Agente está correto e acessível a partir do ambiente atual.

Se o serviço do Agente está em execução.

Se for necessária autenticação, se as informações de autenticação corretas foram configuradas no separador Autenticação.

Se são necessários Cabeçalhos adicionais, tais como ID do inquilino, identificador de ambiente ou informações de autenticação de gateway.

Se o conteúdo devolvido pelo Cartão do Agente é JSON válido.

Não consegue carregar anexos após uma ligação bem-sucedida?

Isto acontece normalmente porque o Agente atual não declarou suporte para entrada de ficheiros, ou permite apenas o carregamento de tipos de ficheiro específicos.

Veja os tipos de entrada suportados pelo Agente no separador Cartão do Agente e confirme se o tipo de ficheiro carregado corresponde.

Como posso ver o pedido e a resposta completos?

Clique no registo de pedido ou resposta correspondente no separador Mensagens do painel de depuração e, em seguida, mude para a vista Dados Brutos para ver o JSON completo.

O que devo fazer se o conteúdo devolvido pelo Agente for apresentado de forma anómala?

Pode resolver o problema pela seguinte ordem:

Verifique o conteúdo de pré-visualização na mensagem de depuração para confirmar se o Agente devolveu um resultado.

Mude para a vista Dados Brutos para ver a resposta completa.

Verifique se os tipos de entrada, os tipos de saída e as Competências declaradas no Cartão do Agente correspondem ao esperado.

Verifique se existem avisos de erro de validação na mensagem ou nos detalhes de depuração.

Ligar-se a um Agente A2A#

Escrever Mensagens de Teste#

Enviar Mensagens#

Ver Mensagens de Resposta#

Ver o Cartão do Agente#

Adicionar Anexos#

Configurar Autenticação#

Configurar Cabeçalhos#

Adicionar Metadados#

Perguntas Frequentes#

O que devo fazer se a ligação falhar?#

Não consegue carregar anexos após uma ligação bem-sucedida?#

Como posso ver o pedido e a resposta completos?#

O que devo fazer se o conteúdo devolvido pelo Agente for apresentado de forma anómala?#

Ligar-se a um Agente A2A

Escrever Mensagens de Teste

Enviar Mensagens

Ver Mensagens de Resposta

Ver o Cartão do Agente

Adicionar Anexos

Configurar Autenticação

Configurar Cabeçalhos

Adicionar Metadados

Perguntas Frequentes

O que devo fazer se a ligação falhar?

Não consegue carregar anexos após uma ligação bem-sucedida?

Como posso ver o pedido e a resposta completos?

O que devo fazer se o conteúdo devolvido pelo Agente for apresentado de forma anómala?