Testar e solucionar problemas A2A

Soluções para erros comuns ao testar chamadas A2A de entrada ou saída no Orchestrator, incluindo falhas de autenticação, agentes ausentes e tempos limite.

Observação:

Essa funcionalidade está em visualização.

Teste um agente A2A com chamadas diretas antes de usá-lo a partir de um agente da UiPath ou de um cliente externo. Chamar o agente por conta própria mostra a solicitação e a resposta brutas, que informam se um problema está no agente, em sua autenticação ou no aplicativo de chamada.

As chamadas de entrada e de saída falham por diferentes motivos, portanto, esta página abrange o que se aplica primeiro a ambas as direções e, em seguida, divide por direção. O URL que você está chamando identifica qual metade é sua:

• é .../agenthub_/a2a/{folderKey}/{agentReleaseId} entrada: um cliente externo está chamando um agente de conversa implantado na plataforma.
• é .../agenthub_/a2a/remote/{folderKey}/{slug} saída: a UiPath está chamando um agente hospedado em outro lugar em nome do chamador.

Testar um agente com chamadas diretas

Os exemplos usam cURL, mas as mesmas solicitações funcionam do Postman, do A2A Python ou do .NET SDK (kit de desenvolvimento de software) ou de um cliente A2A gráfico.

Direction	URL	Onde obter
Recebida	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}	Automações > Processos > Copiar URL do cartão A2A. {folderKey} é a chave da pasta na qual o agente é implantado e {agentReleaseId} é o ID da versão do agente de conversa implantado.
Perdida	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}	Agent Gateway > Agentes A2A e, em seguida, Copiar URL na linha do agente.

1. Defina TOKEN como um token de portador e AGENT_URL como o URL para sua direção.
2. Solicite o cartão do agente primeiro. Uma resposta bem-sucedida confirma que o agente existe, a pasta é resolvida para sua identidade e seu token é aceito:

   curl "$AGENT_URL/.well-known/agent-card.json" \
     -H "Authorization: Bearer $TOKEN"
   

3. Envie uma mensagem para o ponto de extremidade JSON-RPC (Chamada de Procedimento Remoto JSON), que é o mesmo endereço sem o sufixo /.well-known/agent-card.json:

   curl -X POST "$AGENT_URL" \
     -H "Authorization: Bearer $TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "message/send",
       "params": {
         "message": {
           "role": "user",
           "messageId": "msg-1",
           "parts": [{"kind": "text", "text": "Hello"}]
         }
       }
     }'
   

A resposta carrega um contextId. Incluí-la na próxima mensagem continua a mesma conversa; o ID da conversa, o ID da tarefa e o contextId têm o mesmo valor. message/stream retorna a resposta como um stream SSE (Eventos enviados pelo servidor): adicione -N para interromper o armazenamento em buffer do cURL e -H "Accept: text/event-stream".

Se uma chamada de saída por meio da UiPath falhar, o envio da mesma solicitação diretamente para o agente remoto, usando as credenciais que o agente espera, informa se o problema é com a UiPath ou com o próprio agente.

Erros comuns a ambas as direções

401 não autorizado

A solicitação chegou à UiPath, mas o token não foi aceito.

Causa	Resolution
O token expirou	Obtenha um novo token. Os tokens de login interativos expiram após uma hora; um token de acesso pessoal tem uma expiração configurável.
O token foi emitido para outro tenant	Verifique se a organização e o tenant no URL do agente correspondem àqueles para os quais o token foi emitido.
O cabeçalho está malformado	O formato é Authorization: Bearer <your-access-token>.
Nenhum token foi enviado	Cada solicitação, incluindo a solicitação de cartão de agente, deve incluir um token.

Tempos limite

Limite	AplicávelA	O que acontece
15 minutos	Qualquer solicitação única feita pela UiPath.	A solicitação é interrompida. Dentro dessa janela, uma resposta transmitida continua enquanto ambos os partes mantenham a conexão aberta.
5 minutos	Uma etapa de uma conversa de entrada.	A vez falha. A tarefa permanece utilizável e o turno pode ser repetido.
30 segundos	Iniciar a sessão do agente atrás de um turno de entrada.	Conforme acima.
5 minutos	Um agente de saída chamado como uma ferramenta de um agente da UiPath.	A chamada de ferramenta falha e o texto do erro chega ao agente da UiPath como saída de ferramenta.

Para trabalhos que são executados por mais tempo do que uma única solicitação permite, transmita a resposta ou use tarefas A2A: tire o identificador da tarefa da primeira resposta e pesquise seu resultado.

Versões do protocolo e do cartão

Ambas as direções selecionam a versão do protocolo A2A com o cabeçalho A2A-Version, incluindo na solicitação do cartão do agente. Defina-o como 1.0 para v1.0 ou omita-o para v0.3 (um valor vazio ou em branco é tratado da mesma maneira).

Na entrada, o valor será correspondente exatamente, então 1.0 será reconhecido e 1.0.0 não. O ponto de extremidade de entrada aceita qualquer formato de conexão, seja qual for o cartão que você obteve, então o cabeçalho só muda qual cartão você obter.

Na saída, apenas a versão principal e a secundária são lidas, portanto, 1.0 e 1.0.0 selecionam v1.0. A UiPath encaminha uma solicitação apenas para um ponto de extremidade que corresponda à versão solicitada, portanto, uma solicitação para uma versão que o cartão armazenado não pode satisfazer é rejeitada com 400.

Entrada (externo para a UiPath)

Não há nada para registrar nessa direção, então cada falha acontece em uma chamada. tasks/get retorna o estado atual e o histórico de uma conversa. Para o que a direção exige, consulte Entrada (externo à UiPath).

A pasta ou o agente não foram encontrados (404)

Mensagem	Causa	Resolution
Folder with key {folderKey} not found	A chave da pasta está errada ou nomeia uma pasta que o chamador não pode acessar.	Verifique o URL e o acesso à pasta do chamador.
Conversational agent with release ID {agentReleaseId} not found in folder {folderId}	Nenhum agente de conversa é implantado sob esse ID de versão nessa pasta.	Verifique o ID da versão na entrada do agente em Automações > Processos.

Uma chave de pasta que resolve é armazenada em cache por 30 minutos. Uma chave que não resolve não é armazenada em cache, portanto, conceder acesso a um usuário a uma pasta entra em vigor em sua próxima chamada. Uma pasta que foi excluída ou cujo acesso foi retirado, continua a ser resolvida até que sua entrada em cache expire.

Apenas o ponto de extremidade do cartão do agente valida o ID da versão antes de responder; portanto, solicite o cartão do agente primeiro ao diagnosticar. Em message/send, um ID de versão incorreto não é relatado com clareza.

O chamador é recusado pelo agente

Passar a pesquisa da pasta não é o mesmo que ser autorizado. Para o que o chamador precisa, consulte O que o chamador precisa.

A conversa não continua

Problema	Causa	Resolution
Uma mensagem de acompanhamento inicia uma nova conversa	O contextId não corresponde a uma tarefa que o UiPath tem.	Enviar taskId ao lado de contextId; um ID não reconhecido é relatado como Task not found.
Task not found, para um ID que funcionava antes	A tarefa expirou após sete dias de inatividade ou a solicitação foi para uma pasta ou ID de versão diferente.	Envie a solicitação para a pasta e o processo em que a tarefa foi criada ou inicie uma nova tarefa.
Cannot send a message to a task in a terminal state.	A tarefa é completed, canceled, failed ou rejected.	Inicie uma nova tarefa.
Task is in a terminal state and cannot be canceled.	A tarefa já atingiu um estado terminal, e tasks/cancel aplica-se apenas a uma tarefa que ainda está em progresso.	Nenhuma ação é necessária. A tarefa já foi interrompida.

Solicitações que não são compatíveis

Eles retornam um erro JSON-RPC dentro de uma resposta HTTP bem-sucedida.

Solicitar	O que você ganha	Usar em vez disso
tasks/resubscribe, task/subscribe	UnsupportedOperation	message/stream
tasks/list	UnsupportedOperation	Acompanhar IDs da tarefa no cliente
tasks/pushNotificationConfig/*	PushNotificationNotSupported	message/stream. O cartão anuncia pushNotifications: false
O cartão de agente estendido	ExtendedAgentCardNotConfigured	O cartão comum

Um historyLength negativo em tasks/get é rejeitado com InvalidParams.

Saída (UiPath para externo)

Uma chamada nessa direção é autenticada duas vezes: uma vez pelo chamador para a UiPath, e uma vez pela UiPath para o agente. A maioria das falhas vem do segundo salto. As chamadas relacionadas são agrupadas em Traces por contextId. Para configuração, consulte Saída (UiPath para externo).

Salvar um agente falha

Problema	Causa	Resolution
409 Conflito	Outro agente na pasta já usa esse nome ou campo de dados dinâmico.	Escolha outro nome ou campo de dados dinâmico; ambos devem ser exclusivos dentro da pasta. Não é possível alterar o campo de dados dinâmico após a criação.
O cartão do agente é necessário	Não foram fornecidos o URL do cartão nem o JSON do cartão.	Forneça um deles.
O cartão do agente não é válido	O JSON não é um objeto de cartão ou não publica nenhum ponto de extremidade JSON-RPC.	Forneça o cartão conforme publicado pelo agente remoto.
A URL do cartão do agente não é válida	O URL não tem esquema ou não é acessível pela internet pública.	Insira um URL absoluto ou http ou defina https Tipo de conexão como Privado (Relay).

O chamador não tem permissão para usar o agente (403)

Causa	Resolution
O chamador não tem a permissão Visualizar em servidores MCP	Habilite a visualização em servidores MCP para a função atribuída.
O chamador não está atribuído à pasta	Atribua o chamador à pasta que contém o agente.
Não há licenças disponíveis	Verifique Admin > Licenças.

A recuperação do cartão do agente precisa de acesso à pasta, mas não a permissão Visualizar nos servidores MCP. Se o cartão carregar, mas o envio de uma mensagem retornar 403, a permissão ausente é Visualizar em servidores MCP.

O agente não foi encontrado (404)

Causa	Resolution
A URL contém o nome de exibição do agente em vez do campo de dados dinâmico	Use o campo de dados dinâmico, não o nome de exibição.
A chave da pasta está errada	O agente é procurado na pasta nomeada no URL. Copie o URL da linha do agente.
O agente foi excluído	Confirme que ele ainda aparece em Agent Gateway > Agentes A2A.

A solicitação não é permitida (400)

A solicitação já passou pelo proxy A2A da plataforma, e uma solicitação que chega dessa forma é recusada para que as chamadas não possam fazer loop. Isso acontece quando um URL do agente UiPath A2A é registrado como um agente remoto. Em vez disso, registre o próprio endereço do agente remoto.

O cartão armazenado está ausente ou desatualizado

O cartão armazenado não é buscado novamente em chamadas posteriores; portanto, um cartão que muda para montante continua servindo seu conteúdo anterior. Para atualizá-lo, abra o agente, selecione Editar e forneça o cartão atual. A mesma tela mostra o cartão como o agente remoto o publicou, antes que a UiPath regrave os pontos de extremidade anunciados.

Duas falhas seguem um cartão que está ausente ou obsoleto:

Problema	Causa	Resolution
404 no cartão do agente, 400 no message/send	Nenhum cartão é armazenado para o agente, então não há nada para servir.	Abra o agente em Agent Gateway > Agentes A2A e forneça o cartão.
400, nenhum ponto de extremidade para a versão A2A solicitada	Nenhum cabeçalho A2A-Version foi enviado, mas o agente suporta apenas a v1.0; ou 1.0 foi enviado e o agente suporta apenas a v0.3; ou o cartão não publica nenhum endpoint JSON-RPC; ou o agente remoto foi alterado e o cartão armazenado não corresponde mais a ele.	Envie ou omita o cabeçalho para corresponder ao que o agente aceita, ou forneça o cartão atual. Os agentes A2A remotos devem expor um ponto de extremidade JSON-RPC; outros tipos de interface não são compatíveis.

502, a UiPath não pode alcançar ou autenticar no agente remoto

O UiPath responde a 502 quando o salto para o agente remoto falha, enquanto você está salvando o agente ou enquanto ele está sendo chamado.

Ao salvar, a UiPath recupera o cartão do agente, e o agente não será criado se falhar:

Causa	Resolution
O URL não é acessível a partir do UiPath	Confirme que o URL é resolvido publicamente ou use Privado (Relay).
O agente requer uma autenticação que não está configurada	Adicione o cabeçalho ou conexão que o agente espera e, em seguida, salve novamente.

Em uma chamada, uma conexão que está anexada, mas não pode fornecer um token falha na chamada, pois a conexão é a única origem do Authorization cabeçalho. Abra Configurações do usuário na linha do agente e verifique o status da conexão (consulte Conexões por usuário para saber o que cada status significa). Um status Inativo significa que a conexão está desabilitada; então, verifique-o na guia Conexões .

Se as credenciais resolverem, mas ainda não for possível alcançar o agente:

Causa	Resolution
O agente está em uma rede privada	Defina Tipo de conexão como Privado (Relay).
Não é possível resolver o endereço ou o certificado não foi aceito	Verifique o ponto de extremidade publicado no cartão do agente, que geralmente é um host diferente do URL do cartão.
O agente não está em execução	Chame o agente diretamente para confirmar.
O agente foi movido	O cartão armazenado ainda aponta para o endereço antigo. Forneça o cartão atual.

Não é possível resolver um cabeçalho que faz referência a um ativo

Um valor de cabeçalho no formulário %ASSETS/AssetName% é resolvido antes que a solicitação seja enviada e, se o ativo não puder ser lido, a chamada falhará sem nunca enviar o valor não resolvido.

Causa	Resolution
O ativo não existe na pasta do agente	Crie-o no Orchestrator ou faça referência a um ativo que faça isso.
O chamador não pode ler o ativo	Conceda a permissão Visualização em Ativos.
O tipo de ativo não é compatível	Um cabeçalho deve ser resolvido em um único valor, então os ativos da lista de valores-chave são rejeitados. Para os tipos que funcionam, consulte Referenciar um ativo do Orchestrator.

A chamada tem tempo limite (504)

Em uma chamada direta, o agente remoto não começou a responder a tempo. O limite aplica-se a quanto tempo o agente leva para começar a responder; após o início, um fluxo pode continuar muito além desse ponto. Use message/stream, ou retorne uma tarefa e pesquise o resultado, para um agente que precisa de mais tempo para começar a responder. Se ele continuar no tempo limite, chame-o diretamente para confirmar que é acessível e verifique seus próprios logs.

A resposta é muito grande

As respostas de um agente remoto estão sujeitas a um limite de tamanho. Uma resposta que a excede é rejeitada, e uma resposta transmitida que passa por ela é interrompida parcialmente, após o aplicativo de chamada já ter recebido alguns eventos. Se um agente retornar um conteúdo grande, faça com que ele retorne uma referência, como um URL.

Chamando um agente a partir de um agente da UiPath

Quando um agente registrado é anexado como uma ferramenta no Agent Builder ou em um fluxo do Maestro, um erro do agente remoto é retornado ao agente da UiPath como saída da ferramenta, com um estado de tarefa de error, e a execução continua. O agente da UiPath continua com esse texto como sua entrada, então um erro parece um resultado de ferramenta comum para o modelo. Para diagnosticar uma chamada com falha, abra Traces para a execução e selecione a chamada de ferramenta para o agente; o trace registra a mensagem enviada e a resposta ou erro retornado.

Os agentes da UiPath chamam agentes remotos com message/send; então, use-o quando estiver reproduzir o que um agente da UiPath faz. O streaming só está disponível quando você chama o URL UiPath do agente por conta própria.

Nesse caminho, a plataforma espera cinco minutos pela resposta completa, e a saída produzida gradualmente não estende essa espera. Para um agente que precisa de mais tempo, faça com que ele retorne uma tarefa que ainda está em progresso: a plataforma mantém a tarefa entre os turnos, para que o agente da UiPath possa Continuá-la em um turno posterior. Uma tarefa que já atingiu completed, canceled, failed ou rejected não pode ser continuada, e a próxima chamada inicia uma nova tarefa dentro da mesma conversa.

Se o cartão armazenado não publicar nem uma interface JSON-RPC v1.0 nem um ponto de extremidade v0.3 utilizável, a ferramenta não poderá ser criada, e a execução relatará que não há nenhum ponto de extremidade compatível disponível. Abra o agente, selecione Editar e confirme que o cartão expõe um ponto de extremidade JSON-RPC sobre http ou https.

As chamadas são bem-sucedidas, mas comportam-se de forma inesperada

Essas são as falhas em que não há erros, portanto, não há código de status para continuar.

Problema	Causa	Resolution
As chamadas usam a identidade errada	Uma conexão configurada para o usuário de chamada tem precedência sobre a conexão padrão do agente.	Verifique as configurações do usuário para uma conexão que você não esperava.
Um cabeçalho Authorization configurado parece ser ignorado	Uma conexão é anexada, e a conexão fornece esse cabeçalho.	Esperado. Todos os outros cabeçalhos que você configurou ainda serão enviados.
Uma conexão que você espera está ausente na lista	As conexões são filtradas pelo endereço publicado no cartão do agente, que muitas vezes é um host diferente do URL do cartão que você registrou.	Verifique se a conexão está habilitada e se está em uma pasta compartilhada ou no espaço de trabalho pessoal do usuário selecionado.
Um agente da UiPath descreve as habilidades do agente remoto incorretamente ou não o usa quando esperado	A descrição da ferramenta e a lista de habilidades vêm do cartão do agente armazenado.	Atualize o cartão armazenado, em seguida, abra o agente da UiPath e confirme a descrição atualizada.
Uma chamada não é agrupada com o restante da conversa em Traces	A primeira mensagem de uma conversa ainda não tem contextId.	Nenhuma ação é necessária. As mensagens posteriores na conversa são agrupadas.