Probar y solucionar problemas de A2A

Soluciones para errores comunes al probar llamadas A2A entrantes o salientes en Orchestrator, incluidos fallos de autenticación, agentes faltantes y tiempos de espera.

Nota:

Esta funcionalidad está en vista previa.

Prueba un agente A2A con llamadas directas antes de utilizarlo desde un agente de UiPath o un cliente externo. Llamar al agente tú mismo te muestra la solicitud y la respuesta sin procesar, que te indica si un problema está en el agente, en tu autenticación o en la aplicación que llama.

Las llamadas entrantes y salientes fallan por diferentes razones, por lo que esta página cubre lo que se aplica primero a ambas direcciones y luego se divide por dirección. La URL a la que llamas identifica qué mitad es la tuya:

• .../agenthub_/a2a/{folderKey}/{agentReleaseId} es entrante: un cliente externo está llamando a un agente conversacional implementado en la plataforma.
• .../agenthub_/a2a/remote/{folderKey}/{slug} es saliente: UiPath está llamando a un agente alojado en otro lugar en nombre de la persona que llama.

Probar un agente con llamadas directas

Los ejemplos utilizan cURL, pero las mismas solicitudes funcionan desde Postman, el Python A2A o .NET SDK (kit de desarrollo de software) o un cliente gráfico A2A.

Dirección	URL	Dónde conseguirlo
Entrante	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}	Automatizaciones > Procesos > Copiar URL de tarjeta A2A. {folderKey} es la clave de la carpeta en la que se implementa el agente, y {agentReleaseId} es el ID de versión del agente conversacional implementado.
Saliente	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}	Agent Gateway > Agentes A2A y, a continuación, Copiar URL en la fila del agente.

1. Establece TOKEN como un token al portador y AGENT_URL como la URL de tu dirección.
2. Solicite primero la tarjeta de agente. Una respuesta correcta confirma que el agente existe, la carpeta se resuelve para tu identidad y se acepta tu token:

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

3. Envía un mensaje al punto final JSON-RPC (llamada a procedimiento remoto JSON), que es la misma dirección sin el sufijo /.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"}]
         }
       }
     }'
   

La respuesta lleva un contextId. Incluirlo en el siguiente mensaje continúa la misma conversación; el ID de la conversación, el ID de la tarea y contextId tienen el mismo valor. message/stream devuelve la respuesta como un flujo SSE (Eventos enviados por el servidor): añade -N para evitar que cURL se almacene en búfer, y -H "Accept: text/event-stream".

Si una llamada saliente a través de UiPath falla, enviar la misma solicitud directamente al agente remoto, utilizando las credenciales que el agente espera, te indica si el problema está en UiPath o en el propio agente.

Errores comunes a ambas direcciones

401 No autorizado

La solicitud ha llegado a UiPath, pero no se ha aceptado el token.

Causa	Resolución
El token ha caducado	Obtenga un nuevo token. Los tokens de inicio de sesión interactivos caducan después de una hora; un token de acceso personal tiene una caducidad configurable.
El token se emitió para un tenant diferente	Comprueba que la organización y el tenant en la URL del agente coincidan con aquellos para los que se emitió el token.
El encabezado tiene un formato incorrecto	El formato es Authorization: Bearer <your-access-token>.
No se ha enviado ningún token	Cada solicitud, incluida la solicitud de tarjeta de agente, debe incluir un token.

Tiempos de espera

Límite	SeAplicaA	Qué sucede
15 minutos	Cualquier solicitud única a través de UiPath.	La solicitud se ha cortado. Dentro de esa ventana, una respuesta transmitida continúa mientras ambos lados mantengan abierta la conexión.
5 minutos	Un turno de una conversación entrante.	El turno falla. La tarea sigue siendo utilizable y el turno se puede volver a intentar.
30 segundos	Iniciar la sesión del agente detrás de un turno entrante.	Como arriba.
5 minutos	Un agente saliente llamado como herramienta desde un agente de UiPath.	La llamada a la herramienta falla y el texto de error llega al agente de UiPath como salida de la herramienta.

Para el trabajo que se ejecuta más tiempo de lo que permite una sola solicitud, transmite la respuesta o utiliza tareas A2A: toma el identificador de la tarea de la primera respuesta y sondea para ver su resultado.

Versiones de protocolo y tarjeta

Ambas direcciones seleccionan la versión del protocolo A2A con el encabezado A2A-Version, incluso en la solicitud de tarjeta de agente. Establécelo en 1.0 para la versión 1.0 u omítelo para la versión 0.3 (un valor vacío o en blanco se trata de la misma manera).

Entrante, el valor coincide exactamente, por lo que 1.0 se reconoce y 1.0.0 no. El punto final entrante acepta cualquier formato de transferencia, sea cual sea la tarjeta que hayas obtenido, por lo que el encabezado solo cambia la tarjeta que obtienes.

Saliente, solo se leen la versión principal y secundaria, por lo que 1.0 y 1.0.0 seleccionan v1.0. UiPath reenvía una solicitud solo a un punto final que coincida con la versión solicitada, por lo que una solicitud de una versión que la tarjeta almacenada no puede satisfacer se rechaza con 400.

Entrante (externo a UiPath)

No hay nada que registrar en esta dirección, por lo que cada fallo se produce en una llamada. tasks/get devuelve el estado actual y el historial de una conversación. Para lo que requiere la dirección, marca Entrante (externo a UiPath).

No se encuentra la carpeta o el agente (404)

Mensaje	Causa	Resolución
Folder with key {folderKey} not found	La clave de la carpeta es incorrecta o nombra una carpeta a la que la persona que llama no puede acceder.	Comprueba la URL y el acceso a la carpeta de la persona que llama.
Conversational agent with release ID {agentReleaseId} not found in folder {folderId}	No se implementa ningún agente conversacional con ese ID de versión en esa carpeta.	Comprueba el ID de la versión con la entrada del agente en Automatizaciones > Procesos.

Una clave de carpeta que se resuelve se almacena en caché durante 30 minutos. Una clave que no se resuelve no se almacena en caché, por lo que conceder acceso a un usuario a una carpeta entra en vigor en su próxima llamada. Una carpeta que se ha eliminado, o cuyo acceso se ha retirado, sigue resolviéndose hasta que caduque su entrada en caché.

Solo el punto final de la tarjeta de agente valida el ID de versión antes de responder, por lo que solicita primero la tarjeta de agente al diagnosticar. El message/send, un ID de versión incorrecto no se informa tan claramente.

El agente rechaza a la persona que llama

Pasar la búsqueda de carpetas no es lo mismo que estar autorizado. Para lo que necesita la persona que llama, consulta Qué necesita la persona que llama.

La conversación no continúa

Síntoma	Causa	Resolución
Un mensaje de seguimiento inicia una nueva conversación	contextId no coincide con una tarea que UiPath retiene.	Enviar taskId junto con contextId; un ID no reconocido se informa como Task not found.
Task not found, para un ID que funcionaba antes	La tarea expiró después de siete días de inactividad, o la solicitud fue a una carpeta o ID de versión diferente.	Envía la solicitud a la carpeta y procesa la tarea en la que se creó, o inicia una nueva tarea.
Cannot send a message to a task in a terminal state.	La tarea es completed, canceled, failed o rejected.	Iniciar una nueva tarea.
Task is in a terminal state and cannot be canceled.	La tarea ya ha alcanzado un estado terminal y tasks/cancel solo se aplica a una tarea que aún está en curso.	No se necesita ninguna acción. La tarea ya se ha detenido.

Solicitudes que no son compatibles

Estos devuelven un error JSON-RPC dentro de una respuesta HTTP correcta.

Solicitud	Qué obtienes	Utilizar en su lugar
tasks/resubscribe, task/subscribe	UnsupportedOperation	message/stream
tasks/list	UnsupportedOperation	Realizar un seguimiento de los ID de las tareas en el cliente
tasks/pushNotificationConfig/*	PushNotificationNotSupported	message/stream. La tarjeta anuncia pushNotifications: false
La tarjeta de agente ampliada	ExtendedAgentCardNotConfigured	La tarjeta normal

Un historyLength negativo en tasks/get se rechaza con InvalidParams.

Saliente (UiPath a externo)

Una llamada en esta dirección se autentica dos veces: una por la persona que llama a UiPath y otra por UiPath al agente. La mayoría de los fallos provienen del segundo salto. Las llamadas relacionadas se agrupan en Seguimientos por contextId. Para la configuración, marca Saliente (UiPath a externo).

Error al guardar un agente

Síntoma	Causa	Resolución
Conflicto 409	Otro agente en la carpeta ya utiliza ese nombre o slug.	Elija un nombre o slug diferente; ambos deben ser únicos dentro de la carpeta. El slug no se puede cambiar después de su creación.
Se requiere la tarjeta del agente	No se ha proporcionado ni la URL de la tarjeta ni el JSON de la tarjeta.	Proporcione uno de ellos.
La tarjeta de agente no es válida	El JSON no es un objeto de tarjeta o no publica ningún punto final JSON-RPC.	Proporciona la tarjeta tal como la publicó el agente remoto.
La URL de la tarjeta de agente no es válida	La URL no tiene esquema o no es accesible a través de Internet público.	Introduzca una URL absoluta http o https , o establezca Tipo de conexión en Privada (Relay).

La persona que llama no tiene permiso para utilizar el agente (403)

Causa	Resolución
La persona que llama carece del permiso Ver en servidores MCP	Habilita Ver en servidores MCP para el rol asignado.
La persona que llama no está asignada a la carpeta	Asigna la persona que llama a la carpeta que contiene el agente.
No hay ninguna licencia disponible	Consulta Admin > Licencias.

Para recuperar la tarjeta de agente se necesita acceso a la carpeta, pero no el permiso Ver en servidores MCP. Si la tarjeta se carga pero el envío de un mensaje devuelve 403, el permiso que falta es Ver en servidores MCP.

No se ha encontrado el agente (404)

Causa	Resolución
La URL contiene el nombre para mostrar del agente en lugar de su slug	Utilice el slug, no el nombre para mostrar.
La clave de la carpeta es incorrecta	El agente se busca en la carpeta nombrada en la URL. Copia la URL de la fila del agente.
Se eliminó el agente	Confirme que sigue apareciendo en Agent Gateway > Agentes A2A.

La solicitud no está permitida (400)

La solicitud ya pasó por el proxy A2A de la plataforma, y una solicitud que llega de esa manera se rechaza para que las llamadas no puedan repetirse. Esto sucede cuando una URL de agente UiPath A2A se registra como agente remoto. Registra la propia dirección del agente remoto en su lugar.

Falta la tarjeta almacenada o está obsoleta

La tarjeta almacenada no se vuelve a recuperar en llamadas posteriores, por lo que una tarjeta que cambia en sentido ascendente sigue sirviendo sus contenidos anteriores. Para actualizarlo, abre el agente, selecciona Editar y proporciona la tarjeta actual. La misma pantalla muestra la tarjeta tal como la publicó el agente remoto, antes de que UiPath reescriba los puntos finales anunciados.

Dos fallos se derivan de una tarjeta que falta o está obsoleta:

Síntoma	Causa	Resolución
404 en la tarjeta de agente, 400 en message/send	No se almacena ninguna tarjeta para el agente, por lo que no hay nada que servir.	Abre el agente en Agent Gateway > Agentes A2A y proporciona la tarjeta.
400, sin punto final para la versión A2A solicitada	No se envió ningún encabezado A2A-Version, pero el agente solo admite v1.0; o se envió 1.0 y el agente solo admite v0.3; o la tarjeta no publica ningún punto final JSON-RPC; o el agente remoto ha cambiado y la tarjeta almacenada ya no coincide.	Envía u omite el encabezado para que coincida con lo que admite el agente, o proporciona la tarjeta actual. Los agentes A2A remotos deben exponer un punto final JSON-RPC; no se admiten otros tipos de interfaz.

502, UiPath no puede conectarse o autenticarse en el agente remoto

UiPath responde 502 cuando falla el salto al agente remoto, ya sea mientras guardas el agente o mientras se llama.

Al guardar, UiPath recupera la tarjeta del agente y el agente no se crea si eso falla:

Causa	Resolución
No se puede acceder a la URL desde UiPath	Confirma que la URL se resuelve públicamente o utiliza Private (Relay).
El agente requiere una autenticación que no está configurada	Añada el encabezado o la conexión que el agente espera y, a continuación, guárdelo de nuevo.

En una llamada, una conexión que está adjunta pero no puede proporcionar un token falla en la llamada, ya que la conexión es la única fuente del encabezado Authorization. Abre Configuraciones de usuario en la fila del agente y comprueba el estado de la conexión (consulta Conexiones por usuario para saber qué significa cada estado). Un estado Inactivo significa que la conexión está deshabilitada, así que compruébalo en la pestaña Conexiones .

Si las credenciales se resuelven pero aún no se puede contactar con el agente:

Causa	Resolución
El agente está en una red privada	Establece Tipo de conexión en Privada (Relay).
No se puede resolver la dirección o no se acepta el certificado	Comprueba el punto final publicado en la tarjeta del agente, que a menudo es un host diferente de la URL de la tarjeta.
El agente no se está ejecutando	Llame al agente directamente para confirmar.
El agente se ha movido	La tarjeta almacenada aún apunta a la dirección anterior. Proporciona la tarjeta actual.

No se puede resolver un encabezado que hace referencia a un activo

Un valor de encabezado en el formulario %ASSETS/AssetName% se resuelve antes de enviar la solicitud, y si el activo no se puede leer, la llamada falla sin enviar nunca el valor no resuelto.

Causa	Resolución
El activo no existe en la carpeta del agente	Créalo en Orchestrator o haz referencia a un activo que lo haga.
La persona que llama no puede leer el activo	Concede el permiso Ver en los activos.
El tipo de activo no es compatible	Un encabezado debe resolverse en un solo valor, por lo que se rechazan los activos de lista de valores-clave. Para ver los tipos que funcionan, consulta Referenciar un activo de Orchestrator.

Se agota el tiempo de espera de la llamada (504)

En una llamada directa, el agente remoto no comenzó a responder a tiempo. El límite se aplica al tiempo que tarda el agente en comenzar a responder; una vez que comienza, una transmisión puede continuar mucho más allá de ese punto. message/streamUsa, o devuelve una tarea y sondea el resultado, para un agente que necesite más tiempo para empezar a responder. Si sigue agotando el tiempo de espera, llámalo directamente para confirmar que es accesible y comprueba sus propios registros.

La respuesta es demasiado grande

Las respuestas de un agente remoto están sujetas a un límite de tamaño. Se rechaza una respuesta que la supera, y una respuesta transmitida que la supera se detiene parcialmente, después de que la aplicación que llama ya haya recibido algunos eventos. Si un agente devuelve contenido grande, haz que devuelva una referencia como una URL en su lugar.

Llamar a un agente desde un agente de UiPath

Cuando un agente registrado se adjunta como herramienta en Agent Builder o en un flujo de Maestro, se devuelve un error del agente remoto al agente de UiPath como salida de herramienta, con un estado de tarea de error, y la ejecución continúa. El agente de UiPath continúa con ese texto como entrada, por lo que un error parece un resultado de herramienta ordinario para el modelo. Para diagnosticar una llamada fallida, abre Seguimientos para la ejecución y selecciona la llamada de herramienta para el agente; el seguimiento registra el mensaje enviado y la respuesta o error devuelto.

Los agentes de UiPath llaman a los agentes remotos con message/send, así que utilízalo cuando reproduzcas lo que hace un agente de UiPath. La transmisión solo está disponible cuando llamas tú mismo a la URL de UiPath del agente.

En esta ruta, la plataforma espera cinco minutos para la respuesta completa, y la salida producida gradualmente no extiende esa espera. Para un agente que necesite más tiempo, haz que devuelva una tarea que aún esté en curso: la plataforma mantiene la tarea entre turnos, para que el agente de UiPath pueda continuarla en un turno posterior. Una tarea que ya ha alcanzado completed, canceled, failed o rejected no puede continuar y la siguiente llamada inicia una nueva tarea dentro de la misma conversación.

Si la tarjeta almacenada no publica ni una interfaz JSON-RPC v1.0 ni un punto final v0.3 utilizable, la herramienta no se puede crear en absoluto y la ejecución informa de que no hay ningún punto final compatible disponible. Abre el agente, selecciona Editar y confirma que la tarjeta expone un punto final JSON-RPC sobre http o https.

Las llamadas se realizan correctamente, pero se comportan de forma inesperada

Estos son los fallos en los que no hay ningún error, por lo que no hay código de estado para continuar.

Síntoma	Causa	Resolución
Las llamadas utilizan una identidad incorrecta	Una conexión configurada para el usuario que llama tiene prioridad sobre la conexión predeterminada del agente.	Consulta Configuraciones de usuario para una conexión que no esperabas.
Parece que se ha ignorado un encabezado Authorization configurado	Se adjunta una conexión y la conexión proporciona ese encabezado.	Esperado. Cada dos encabezados que configuraste se siguen enviando.
Falta una conexión que espera en la lista	Las conexiones se filtran por la dirección publicada en la tarjeta del agente, que a menudo es un host diferente de la URL de la tarjeta que registraste.	Comprueba que la conexión está habilitada y que está en una carpeta compartida o en el espacio de trabajo personal del usuario seleccionado.
Un agente de UiPath describe incorrectamente las capacidades del agente remoto o no las utiliza cuando se espera	La descripción de la herramienta y la lista de habilidades provienen de la tarjeta de agente almacenada.	Actualiza la tarjeta almacenada, luego abre el agente de UiPath y confirma la descripción actualizada.
Una llamada no se agrupa con el resto de su conversación en Traces	El primer mensaje de una conversación aún no tiene contextId.	No se necesita ninguna acción. Se agrupan los mensajes posteriores de la conversación.