Entrante (externo a UiPath)

Cómo un agente o cliente externo mantiene una conversación con un agente conversacional que implementaste en Orchestrator y cómo se autentican esas llamadas.

Nota:

Esta funcionalidad está en vista previa.

A2A entrante es un agente o cliente externo que mantiene una conversación con un agente conversacional que implementaste en UiPath Platform. UiPath es el destino de la llamada, no una puerta de enlace frente a otra cosa.

No hay nada que registrar para esta dirección. Cada agente conversacional implementado en una carpeta ya habla A2A: Agent Gateway sirve su tarjeta de agente y traduce el tráfico A2A en una conversación nativa con el agente. Cualquier cliente A2A puede utilizar el agente solo con la URL de la tarjeta y un token de UiPath.

Como UiPath es el destino, solo hay que configurar una autenticación: la persona que llama se autentica en UiPath. Las conexiones, encabezados y referencias de activos de Orchestrator que aparecen en la dirección de salida no tienen contrapartida aquí.

Exponer agentes conversacionales implementados

La tarjeta de agente

Cada agente implementado tiene una tarjeta en:

https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}/.well-known/agent-card.json

{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.

La tarjeta se genera a partir de la implementación actual, por lo que su nombre, descripción y versión siempre coinciden con lo que se implementa. Anuncia la transmisión, la entrada/salida de texto y archivos y la autenticación de portador. No hay descubrimiento anónimo: obtener la tarjeta ya requiere un token de UiPath.

Puedes copiar la URL A2A desde Automatizaciones > Procesos > Copiar URL de tarjeta A2A. También puedes inspeccionar tanto la URL de A2A como la tarjeta de agente desde la pestaña Agentes implementados , después de seleccionar el agente conversacional.

Llamar al agente

El punto final JSON-RPC (Llamada a procedimiento remoto JSON) es la URL de la tarjeta sin el sufijo /.well-known/agent-card.json. En la conexión, una llamada tiene este aspecto:

POST https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}
Authorization: Bearer <your-access-token>

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "message/send",
  "params": {
    "message": {
      "messageId": "m1",
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "hi"
        }
      ]
    }
  }
}

Una tarea A2A representa una conversación con el agente. El primer mensaje crea la tarea y la respuesta lleva un contextId; incluir ese ID en el siguiente mensaje continúa la misma conversación. Después de cada respuesta, el estado de la tarea es input-required, manteniendo la conversación abierta para mensajes de seguimiento.

message/stream devuelve la respuesta como un flujo SSE (Eventos enviados por el servidor). tasks/get lee el estado y el historial de una tarea, y tasks/cancel cancela una tarea en ejecución. Las notificaciones push y tasks/resubscribe no son compatibles, por lo que la salida en vivo requiere message/stream.

Autenticación

A2A entrante tiene una única autenticación: la persona que llama se autentica en UiPath. UiPath es el destino de la llamada, por lo que no hay un segundo salto ni credenciales de flujo ascendente que configurar.

Cada solicitud lleva un token al portador en el encabezado Authorization, incluida la solicitud de la tarjeta de agente. No hay descubrimiento anónimo y no se transfiere nada entre turnos: cada mensaje de una conversación se autentica por sí solo.

Qué necesita la persona que llama

El token debe ser válido para la organización y el tenant nombrados en la URL, y la carpeta nombrada en la URL debe ser una que la identidad de la llamada pueda ver. No se requiere nada más: ningún permiso de carpeta, ningún ámbito específico para A2A y ningún equivalente del permiso Ver en servidores MCP que necesita una llamada saliente. La identidad y la carpeta son todo lo que UiPath comprueba aquí, y nada inspecciona el contenido de un mensaje.

Cualquier token que funcione en otro lugar de la plataforma funciona aquí: inicio de sesión interactivo, aplicaciones externas o un token de acceso personal, que es el más simple para las pruebas.

Nota:

Crea un token de acceso personal con el recurso de acceso a la API de Orchestrator seleccionado, porque ese recurso establece la audiencia que comprueba este punto final. Sin él, el token se rechaza antes de que la llamada llegue al agente, y el error nombra a la audiencia en lugar de al token, por lo que no parece un problema de ámbito en absoluto.

Para saber cómo obtener cada tipo de token, consulta Autenticación del servidor MCP.

UiPath valida el token, resuelve la carpeta y reenvía la solicitud al servicio que ejecuta el agente conversacional, con el token de la persona que llama adjunto. Entrante es la única dirección en la que el token de la persona que llama viaja más allá de Agent Gateway. Permanece dentro de UiPath, porque el servicio que ejecuta el agente es un servicio de UiPath. En una llamada saliente, el token se elimina en el límite y se reemplaza por las credenciales configuradas para el agente remoto.

Seleccionar la versión de la tarjeta

Solo el punto final de la tarjeta de agente lee el encabezado A2A-Version opcional; el punto final del mensaje lo ignora. Un cliente v1.0 envía el encabezado por sí mismo, por lo que rara vez necesitas configurarlo tú mismo.

• Envía 1.0 para la tarjeta v1.0 estricta.
• Envíe 0.3 para la tarjeta v0.3 estricta, que no lleva v1.0 y se adapta a un cliente cuyo deserializador rechaza las propiedades desconocidas.
• No envíes nada, o cualquier otro valor, y obtendrás una tarjeta v0.3 con la propiedad v1.0 supportedInterfaces añadida, de modo que un cliente v1.0 que no haya enviado el encabezado aún pueda leerlo.

El punto final del mensaje acepta ambos formatos de conexión independientemente del encabezado, por lo que un cliente v1.0 y un cliente v0.3 pueden hablar con el mismo agente. El valor coincide exactamente, por lo que 1.0.0 no se trata como 1.0. Y omitir el encabezado no te da la tarjeta v0.3 estricta aquí, como lo hace para un agente remoto registrado. Si estás comparando las dos direcciones, es por eso que sus cartas difieren.

Solución de problemas

Para ver los errores que es más probable que encuentres y cómo resolverlos, consulta Probar y solucionar problemas de A2A. Su sección Entrante cubre los fallos en esta ruta.

Para la dirección opuesta, donde UiPath llama a un agente alojado en otro lugar, marca Saliente (UiPath a externo).