Saliente (UiPath a externo)

Registra un agente A2A alojado fuera de UiPath en Agent Gateway y configura la autenticación para las llamadas a él.

Nota:

Esta funcionalidad está en vista previa.

A2A saliente es la plataforma que llama a un agente alojado fuera de UiPath, ya sea directamente o como herramienta dentro de un agente de UiPath. Registras el agente una vez en Agent Gateway > Agentes A2A, y UiPath actúa como puerta de enlace gobernada frente a él.

Debido a que hay dos saltos, hay dos autenticaciones independientes: la persona que llama se autentica en UiPath y UiPath se autentica por separado en el agente remoto. Ningún lado ve las credenciales del otro.

Todo lo específico de ese segundo salto se aplica solo a esta dirección: conexiones de Integration Service, encabezados configurados, referencias de activos de Orchestrator y conexiones por usuario.

Registrar un agente A2A remoto

Al registrar un agente, se puede llamar a un agente A2A alojado fuera de UiPath desde la plataforma. Agent Gateway almacena la tarjeta y las credenciales del agente, le asigna una URL de UiPath estable y, a partir de ese momento, cualquier consumidor con capacidad A2A en la plataforma llega al agente a través de esa URL.

Una vez registrado, el agente se comporta como cualquier otro artefacto implementado en UiPath: vive en una carpeta, los permisos de carpeta rigen quién puede llamarlo, las barreras de seguridad pueden filtrar sus mensajes, las llamadas aparecen en Seguimientos y se auditan los cambios en ella.

Un agente A2A registrado también puede ser consumido por clientes externos. Llaman a la URL A2A expuesta a UiPath con un token de UiPath, exactamente como lo harían para un agente alojado en UiPath. Para ver los tokens aceptados y los permisos necesarios, consulta Autenticación.

Requisitos previos

• La tarjeta del agente: ya sea su URL, que normalmente termina en /.well-known/agent-card.json, o el JSON de la tarjeta sin procesar, para agentes cuya tarjeta no se puede recuperar directamente.
• Lo que el agente espera para la autenticación: valores de encabezado estáticos, como una clave API o un token fijo, o una conexión ya creada en Orchestrator.
• El permiso Crear en el nivel de carpeta para servidores MCP en la carpeta de destino. Los agentes A2A remotos comparten el conjunto de permisos Servidores MCP, y los roles Automation Developer, Folder Administrator y Personal Workspace Administrator incluyen Crear. Automation User tiene solo Ver , que es suficiente para llamar a un agente pero no para registrarlo.

Registrar el agente

1. En Agent Gateway > Agentes A2A, selecciona Añadir agente externo.

2. Introduzca un Nombre, Slug y Descripción.

   Nota:

   El slug se convierte en parte de la URL de UiPath del agente y no puede cambiar después de la creación. Utiliza solo letras minúsculas, números y guiones.

3. Proporcione la tarjeta de agente, ya sea por URL o como JSON pegado.

   Nota:

   El JSON pegado rellena automáticamente los campos Nombre y Descripción , si están presentes.

4. Selecciona el Tipo de conexión: Estándar para un agente accesible a través de Internet público, o Privado (Relay) para un agente en una red privada. Para obtener más detalles, consulta Llegar a un agente dentro de una red privada.

5. Configura la autenticación para el agente, utilizando uno o ambos de los siguientes:

   • Conexión: crea una conexión para el conector Agent2Agent y luego selecciónala aquí. Una vez seleccionado, Agent Gateway recupera un nuevo token al portador de la conexión en cada llamada, por lo que las credenciales que caducan no tienen que rotarse manualmente.
   • Encabezados: pares de nombre y valor añadidos a cada solicitud, en el formulario <key>:<value>, por ejemplo Authorization:Bearer <your-api-key>. Los encabezados se almacenan cifrados y enmascarados cuando se vuelven a leer. En lugar de pegar un secreto, un valor de encabezado puede hacer referencia a un activo de Orchestrator, en el formulario Authorization:%ASSETS/AssetName%.

   Si se establecen ambos, la conexión proporciona el encabezado Authorization y los otros encabezados se siguen aplicando.

6. Opcionalmente, expande Barreras y configúralas. Para obtener más detalles, consulta Barreras de seguridad.

7. Selecciona Guardar.

Resultado: Agent Gateway obtiene la tarjeta del agente y la almacena en caché. El agente aparece en la lista Agentes A2A . Si la recuperación falla, el guardado falla con el error de recuperación y no se almacena nada hasta que la tarjeta sea legible.

Qué ven los clientes externos

El agente registrado reside en:

https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}

Puedes copiar esta URL de la lista de agentes A2A . Un cliente externo lo utiliza exactamente como lo haría con cualquier agente A2A: la Agent Gateway sirve la tarjeta del agente en <that URL>/.well-known/agent-card.json, reescrita para que cada punto final anunciado apunte a la puerta de enlace en lugar de al host ascendente, y el cliente se autentica en UiPath en lugar de en el agente ascendente. El propio esquema de autenticación del flujo ascendente nunca se filtra.

En cada llamada, Agent Gateway valida el token de UiPath y el acceso a la carpeta de la persona que llama, lo que requiere el permiso Ver en servidores MCP, ya que A2A comparte el conjunto de permisos de servidores MCP. A continuación, compara la solicitud con las barreras de seguridad del agente, elimina el encabezado Authorization de la persona que llama, inyecta las credenciales configuradas y transmite la respuesta intacta, incluidos SSE (Server-Sent Events). Los mensajes no se analizan ni se reescriben, por lo que tanto los clientes A2A 0.3 como 1.0 funcionan, y un cliente selecciona una versión con el encabezado A2A-Version. Las llamadas aparecen en Traces.

Después del registro

• Actualizar tarjeta vuelve a recuperar la tarjeta cuando cambia el agente remoto, por ejemplo, un nuevo punto final, nuevas habilidades o una descripción actualizada.
• Las configuraciones de usuario permiten a los usuarios individuales adjuntar su propia conexión. Para sus llamadas, tiene prioridad sobre la conexión predeterminada del agente.

Autenticación

Llamar a un agente A2A a través de UiPath implica dos autenticaciones independientes entre sí. UiPath se autentica en el agente al que reenvía la solicitud, utilizando las credenciales configuradas una vez cuando se registra el agente. La persona que llama se autentica en UiPath por separado, con un token de plataforma normal. Ningún lado ve las credenciales del otro.

Registrar un agente configura dos cosas. La tarjeta de agente le dice a UiPath dónde enviar mensajes. Las credenciales permiten a UiPath autenticarse en el agente en cada llamada, ya que el token de la persona que llama nunca se reenvía. Las credenciales pueden proporcionarse como una conexión de Integration Service, como encabezados o como ambos.

La tarjeta de agente

Una tarjeta de agente es el documento JSON que publica un agente A2A para describirse a sí mismo: su nombre, sus habilidades y el punto final que acepta mensajes JSON-RPC (Llamada a procedimiento remoto JSON). UiPath no puede enrutar una llamada sin una, por lo que cada registro persiste en la tarjeta del agente como registro de enrutamiento y autenticación.

El registro de un agente requiere el permiso Crear en servidores MCP en la carpeta de destino. Los agentes A2A remotos comparten el conjunto de permisos de Servidores MCP, por lo que los permisos de Servidores MCP también rigen A2A.

Opción 1: proporcionar la URL de la tarjeta de agente

Introduce la URL de la tarjeta del agente, normalmente la URL base del agente, seguida de /.well-known/agent-card.json. UiPath lo obtiene en ese momento, utilizando las credenciales configuradas en la misma pantalla: la conexión adjunta, si hay una, o los encabezados configurados en caso contrario. Las referencias de activos en esos encabezados también se resuelven para esta solicitud, por lo que una tarjeta detrás de una clave API almacenada en Orchestrator puede leerse sin pegar la clave.

La URL se comprueba con la protección SSRF (falsificación de solicitud del lado del servidor) antes de realizar la solicitud, a menos que se llegue al agente a través del Relay. Si UiPath no puede comunicarse con la dirección o la respuesta no es correcta, no se crea el agente. Esta es la única opción que admite Actualizar tarjeta más tarde.

Opción 2: pegar el JSON de la tarjeta

Pegue el documento de la tarjeta directamente. UiPath no realiza ninguna solicitud saliente, por lo que no se necesitan credenciales en el momento del registro y la comprobación de SSRF no se aplica. Usa esta opción para un agente que no sea accesible desde UiPath en el momento del registro, o cuya tarjeta no se sirva en una dirección pública. Si se proporcionan tanto una URL como un JSON pegado, se utiliza el JSON pegado y no se obtiene nada.

Independientemente de cómo llegue la tarjeta, UiPath solo la acepta si se trata de un objeto JSON que anuncia un punto final HTTP o HTTPS JSON-RPC utilizable, a través del campo v0.3 url o la lista v1.0 supportedInterfaces. Una tarjeta sin tarjeta se rechaza en el momento del registro y no en el momento de la llamada.

La tarjeta almacenada no se vuelve a recuperar en cada llamada, por lo que una tarjeta que cambia en sentido ascendente no se actualiza por sí sola. La tarjeta de actualización la obtiene de nuevo, requiere el permiso Editar en servidores MCP y requiere una URL de tarjeta: un agente registrado pegando JSON no tiene ninguno, y se rechaza la actualización.

Nota:

Una actualización se autentica de la misma manera que una llamada, no como el registro: utiliza la conexión configurada para el usuario que la desencadena y recurre a la conexión predeterminada del agente. Por lo tanto, una actualización puede tener éxito para un usuario y fallar para otro.

Una conexión de Integration Service

Adjuntar una conexión al agente significa que UiPath recupera un nuevo token al portador en cada llamada. Esta es la mejor opción para cualquier agente cuyas credenciales caduquen, ya que no es necesario rotar nada a mano. La conexión se utiliza junto con la carpeta a la que pertenece; si falta esa carpeta, la llamada falla en lugar de recurrir a otra carpeta o a un encabezado configurado.

Encabezados

Como alternativa, configura los encabezados que el agente espera como pares de nombre y valor. El caso común es Authorization: Bearer <your-api-key>. Los encabezados se almacenan cifrados y enmascarados cuando se vuelven a leer, por lo que un secreto pegado una vez no es visible después.

Prioridad de conexión y encabezado

Si se adjunta una conexión, proporciona el encabezado Authorization, y cualquier encabezado Authorization configurado también se ignora en lugar de simplemente sobrescribirse: la línea configurada se elimina antes de que se resuelvan las referencias de activos, por lo que un encabezado que apunte a un activo Ni siquiera miré hacia arriba. Cada dos encabezados configurados se sigue enviando. La misma prioridad se aplica a la obtención de la tarjeta en el momento del registro.

Conexiones por usuario

Los usuarios individuales pueden adjuntar una conexión propia a través de Configuraciones de usuario en la fila del agente, lo que requiere el permiso Editar en Conexiones. Cuando se llama al agente, la conexión se selecciona en este orden:

1. La conexión configurada para el usuario que llama.
2. La conexión predeterminada del agente.
3. Sin conexión, en cuyo caso se utilizan los encabezados configurados, o no se envía ninguna autenticación si no se configura ninguna.

La conexión se elige para cualquier identidad que represente el token. En una ejecución programada o unattended, esa identidad no es la de la persona que creó o programó el agente, por lo que no se utiliza una conexión adjunta bajo el propio usuario de alguien. Si un agente debe ser accesible desde ejecuciones unattended, dale una conexión predeterminada en lugar de depender de las de cada usuario.

Las configuraciones de usuario también muestran el estado de cada conexión:

Estado	Significado
Activo	La conexión está autorizada y lista.
Requiere autenticación	No hay ninguna conexión disponible para este usuario, ya sea porque no hay ninguna configurada o porque es necesario volver a autorizar la suya.
No disponible	Falta la conexión predeterminada compartida, está deshabilitada, ha caducado o no se ha podido conectar.
Inactivo	El agente no está activo o la conexión está deshabilitada.

Hacer referencia a un activo de Orchestrator

En lugar de pegar un secreto en un encabezado, asigna al encabezado un valor en el formulario %ASSETS/AssetName%. UiPath lo resuelve al valor del activo antes de enviar la solicitud, leyendo el activo de la carpeta del agente bajo la identidad de la llamada. Si no se puede leer el activo, la llamada falla en lugar de reenviar el marcador de posición no resuelto.

Se admiten los activos de texto, secreto, booleano, entero, credencial y credencial de Windows; Los activos de credenciales y credenciales de Windows se resuelven en el valor de la contraseña. Los activos de lista de valores-clave se rechazan, ya que un valor de encabezado debe resolverse en una cadena. El valor resuelto se reenvía al agente remoto como el encabezado configurado, por lo que utiliza encabezados respaldados por activos solo para los puntos finales en los que confías esos secretos.

Llegar a un agente dentro de una red privada

Se llega a un agente que se ejecuta dentro de una red privada sin puertos de firewall entrantes a través de la retransmisión: UiPath envía la solicitud a un servidor de retransmisión, y un cliente de retransmisión dentro de la red la recopila y la reenvía al agente. El Relay cambia la forma en que UiPath llega al agente, no cómo se autentica en él: la conexión, los encabezados, su precedencia y las referencias de activos se comportan exactamente como se describe anteriormente. La comprobación de SSRF no se aplica a la llamada o a la obtención de la tarjeta, ya que la solicitud no se envía a una dirección pública.

Llamar a un agente registrado

Dos tipos de personas que llaman llegan a un agente remoto registrado. Un cliente de UiPath, como un agente de UiPath o un flujo de Maestro, utiliza el agente como herramienta y la plataforma resuelve la dirección, el token y la versión del protocolo en tiempo de ejecución. Un cliente HTTP directo llama a la propia URL del agente y tiene que proporcionar las tres. Ambos se autentican en UiPath de la misma manera; el resto de esta sección solo importa cuando se llama directamente.

Cada solicitud lleva un token al portador en el encabezado Authorization. No se transfiere nada entre turnos: cada mensaje de una conversación se autentica por sí solo.

Lo que estás alcanzando	Qué necesita la persona que llama
El propio agente	Un token válido para la organización y el tenant, acceso a la carpeta que contiene el agente y el permiso Ver en los servidores MCP de esa carpeta. Los roles Automation User, Automation Developer, Folder Administrator y Personal Workspace Administrator lo incluyen.
Su tarjeta de agente	Solo acceso a carpetas. La tarjeta son metadatos de descubrimiento, por lo que es deliberadamente más fácil de alcanzar que el propio agente.

Obteniendo un token

A2A utiliza los mismos tokens que el resto de la plataforma.

Método	Origen del token	Cuando usarlo
Token de acceso personal (PAT)	UiPath Cloud, en tus preferencias de usuario	La opción más sencilla para realizar pruebas. Su vencimiento es configurable y funciona con cualquier cliente HTTP.
Inicio de sesión interactivo	uipath auth	Desarrollo local. El token dura aproximadamente una hora y no se actualiza automáticamente.
Aplicación externa	Admin > External Apps, credenciales de cliente	Llamantes desatendidos, como procesos de CI/CD (integración continua/entrega continua) y cuentas de servicio, donde no hay nadie presente para iniciar sesión.

Para saber cómo crear cada uno, consulta Autenticación del servidor MCP. Los agentes A2A y los servidores MCP son validados por el mismo proceso, por lo que cualquier token que funcione para un servidor MCP también funciona para un agente A2A. La única excepción es el flujo OAuth de MCP, que solo admiten los puntos finales de MCP, ya que depende de los metadatos de descubrimiento que los agentes A2A no publican.

Obteniendo la URL del agente

Un agente remoto registrado reside en:

https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}

Su tarjeta de agente está en la misma dirección seguida de /.well-known/agent-card.json. Obtenga la URL de Agent Gateway > Agentes A2A seleccionando Copiar URL en la fila del agente, en lugar de ensamblarla a mano: la clave de la carpeta es un GUID (identificador único global) en lugar de un nombre de carpeta, y el slug no es la visualización nombre.

Seleccionar la versión del protocolo

Los agentes A2A remotos admiten A2A v0.3 y v1.0, seleccionados con el encabezado de solicitud A2A-Version:

• Para v1.0, establece el valor del encabezado en 1.0.
• Para v0.3, omite el encabezado. Un valor vacío o en blanco se trata de la misma manera.

El mismo encabezado se aplica al solicitar la tarjeta de agente y determina qué versión de la tarjeta devuelve UiPath. UiPath reenvía una solicitud solo a un punto final que coincida con la versión solicitada; no recurre a otra versión, ya que enviaría al agente remoto un mensaje en un formato de conexión que no entiende. Si la tarjeta de agente almacenada no publica ningún punto final JSON-RPC para esa versión, la solicitud se rechaza y la versión se nombra en la respuesta.

Lo que nunca cruza el límite

Tres cosas se detienen en el límite:

• El token de la persona que llama nunca llega al agente remoto. UiPath lo valida, lo elimina e inyecta las credenciales configuradas para el agente. El agente remoto no tiene forma de saber quién lo llamó a través de UiPath, o de reutilizar esa identidad. UiPath también elimina sus propios encabezados internos e inyecta un único encabezado de seguimiento de salida propio.
• El esquema de autenticación del agente remoto nunca se anuncia a las personas que llaman. La tarjeta de agente que sirve UiPath siempre declara la autenticación de portador propia de UiPath, sea cual sea la publicada en sentido ascendente, y se elimina cualquier firma de la tarjeta original, ya que reescribir la tarjeta la invalida. Para ver la tarjeta tal y como la publicó el agente remoto, abre el agente y selecciona Editar.
• Una llamada no puede volver a pasar por la plataforma. Una URL de tarjeta de agente que apunte a UiPath se rechaza al registrar el agente. Más allá de eso, cada solicitud de proxy lleva un marcador, y una solicitud que ya lo lleva se rechaza.

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 Saliente cubre los fallos en esta ruta.

Para la dirección opuesta, donde un cliente externo llama a un agente que implementaste, marca Entrante (externo a UiPath).