Sortant (UiPath vers externe)

Enregistrez un agent A2A hébergé en dehors d’UiPath dans Agent Gateway et configurez l’authentification pour les appels à cet agent.

Remarque :

Cette fonctionnalité est en aperçu.

L'A2A sortant est la plateforme qui appelle un agent hébergé en dehors d'UiPath, directement ou en tant qu'outil à l'intérieur d'un agent UiPath. Vous enregistrez l'agent une fois dans Agent Gateway (Passerelle de l'agent) > Agents A2A, et UiPath agit comme une passerelle régie devant celui-ci.

Comme il y a deux sauts, il existe deux authentifications indépendantes: l'appelant s'authentifie auprès d'UiPath et UiPath s'authentifie séparément auprès de l'agent distant. Aucun côté ne voit les informations d’identification de l’autre.

Tout ce qui est spécifique à ce deuxième saut s’applique uniquement à cette direction: connexions Integration Service, en-têtes configurés, références de ressources Orchestrator et connexions par utilisateur.

Enregistrer un agent A2A à distance

L'enregistrement d'un agent rend un agent A2A hébergé en dehors d'UiPath appelable depuis la plateforme. Agent Gateway stocke la carte et les informations d'identification de l'agent, lui donne une URL UiPath stable, puis tout consommateur compatible A2A sur la plateforme atteint l’agent via cette URL.

Une fois enregistré, l'agent se comporte comme n'importe quel autre artefact déployé dans UiPath: il réside dans un dossier, les autorisations de dossier régissent qui peut l'appeler, les garde-fous peuvent filtrer ses messages, les appels apparaissent dans Traces et les modifications qui y sont auditées.

Un agent A2A enregistré peut également être utilisé par des clients externes. Ils appellent l'URL A2A exposée par UiPath avec un jeton UiPath, exactement comme ils le feraient pour un agent hébergé par UiPath. Pour connaître les jetons acceptés et les autorisations requises, consultez l'Authentification.

Prérequis

• Carte de l'agent: soit son URL, qui se termine généralement par /.well-known/agent-card.json, soit le fichier JSON brut de la carte, pour les Agents dont la carte ne peut pas être récupérée directement.
• Ce que l'agent attend de l'authentification: valeurs d'en-tête statiques, telles qu'une clé API ou un jeton fixe, ou une connexion déjà créée dans Orchestrator.
• L'autorisation de Création au niveau du dossier pour les serveurs MCP dans le dossier cible. Les Agents A2A distants partagent l'ensemble d'autorisations des serveurs MCP, et les rôles Automation Developer, Folder Administrator et Personal Workspace Administrator incluent Créer. Automation User dispose uniquement de la Consultation , ce qui suffit pour appeler un agent, mais pas pour en enregistrer un.

Enregistrer l'agent

1. In Agent Gateway > Agents A2A, select Ajouter un agent externe.

2. Saisissez un Nom, un Champ de données dynamique et une Description.

   Remarque :

   Le champ de données dynamique fait partie de l’URL UiPath de l’agent et ne peut pas être modifié après sa création. Utilisez uniquement des lettres minuscules, des chiffres et des traits d’union.

3. Indiquez la carte d'agent, soit par URL, soit au format JSON collé.

   Remarque :

   Le fichier JSON collé remplit automatiquement les champs Nom et Description , le cas échéant.

4. Sélectionnez le type de connexion: Standard pour un agent accessible via Internet public, ou Privé (Relay) pour un agent sur un réseau privé. Pour de plus amples informations, consultez la section Consulter un agent à l'intérieur d'un réseau privé.

5. Configurez l’authentification de l’agent à l’aide de l’un des éléments suivants ou des deux:

   • Connexion: créez une connexion pour le connecteur Agent2Agent, puis sélectionnez-la ici. Une fois sélectionné, Agent Gateway récupère un nouveau jeton de porteur à partir de la connexion à chaque appel, de sorte que les informations d’identification qui expirent n’ont pas à être pivotées manuellement.
   • En-têtes: paires de nom et de valeur ajoutées à chaque requête, sous la forme <key>:<value>, par exemple Authorization:Bearer <your-api-key>. Les en-têtes sont stockés chiffrés et masqués lors de leur lecture. Au lieu de coller une clé secrète, une valeur d'en-tête peut référencer une ressource Orchestrator, sous la forme Authorization:%ASSETS/AssetName%.

   Si les deux sont définis, la connexion fournit l'en-tête Authorization, et les autres en-têtes s'appliquent toujours.

6. Vous pouvez également développer les garde-fous et les configurer. Pour plus de détails, consultez la section Garde-fous.

7. Sélectionnez Enregistrer.

Résultat: Agent Gateway récupère la carte de l'agent et la met en cache. L'agent s'affiche dans la liste Agents A2A . Si la récupération échoue, l'enregistrement échoue avec l'erreur de récupération, et rien n'est stocké jusqu'à ce que la carte soit lisible.

Ce que voient les clients externes

L’agent enregistré réside à:

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

Vous pouvez copier cette URL à partir de la liste Agents A2A . Un client externe l'utilise exactement comme le ferait un agent A2A: Agent Gateway sert la carte de l'agent à <that URL>/.well-known/agent-card.json, réécrit de sorte que chaque point de terminaison annoncé pointe sur la passerelle au lieu de l'hôte en amont, et que le client s'authentifie auprès d'UiPath plutôt que auprès du agent en amont. Le schéma d’authentification de l’amont ne fuite jamais.

À chaque appel, Agent Gateway valide le jeton UiPath et l'accès au dossier de l'appelant, ce qui nécessite l'autorisation Afficher sur les serveurs MCP, car A2A partage l'ensemble d'autorisations des serveurs MCP. Il filtre ensuite la requête au regard des garde-fous de l'agent, supprime l'en-tête Authorization de l'appelant, injecte les informations d'identification configurées et renvoie la réponse inchangée, y compris les SSE. Les messages ne sont pas analysés ou réécrits. Les clients A2A 0.3 et 1.0 fonctionnent donc tous deux, et un client sélectionne une version avec l'en-tête A2A-Version. Les appels apparaissent dans Traçages.

Après l'inscription

• Actualiser la carte récupère la carte lorsque l’agent distant change, par exemple un nouveau point de terminaison, de nouvelles compétences ou une description mise à jour.
• Les configurations utilisateur permettent aux utilisateurs individuels d'associer leur propre connexion. Pour leurs appels, il prend le pas sur la connexion par défaut de l’agent.

Authentification

L’appel d’un agent A2A via UiPath implique deux authentifications distinctes, qui sont indépendantes l’une de l’autre. UiPath s'authentifie auprès de l'agent auquel il transmet la demande, à l'aide d'informations d'identification configurées une fois lorsque l'agent est enregistré. L'appelant s'authentifie auprès d'UiPath séparément, avec un jeton de plateforme normal. Aucun côté ne voit les informations d’identification de l’autre.

L'enregistrement d'un agent configure deux choses. La carte de l’agent indique à UiPath où envoyer les messages. Les informations d’identification permettent à UiPath de s’authentifier auprès de l’agent à chaque appel, car le jeton de l’appelant n’est jamais transféré. Les informations d'identification peuvent être fournies sous la forme d'une connexion Integration Service, d'en-têtes ou des deux.

La carte d’agent

Une carte d'agent est le document JSON qu'un agent A2A publie pour se décrire: son nom, ses compétences et le point de terminaison qui accepte les messages JSON-RPC. UiPath ne peut pas acheminer un appel sans un, de sorte que chaque enregistrement conserve la carte de l’agent comme enregistrement de routage et d’authentification.

L'enregistrement d'un agent nécessite l'autorisation Create (Créer) sur les serveurs MCP du dossier cible. Les Agents A2A distants partagent l’ensemble d’autorisations des serveurs MCP, de sorte que les autorisations des serveurs MCP régissent également A2A.

Option 1: fournir l'URL à la carte d'agent

Saisissez l'URL de la carte de l'agent, généralement l'URL de base de l'agent suivie de /.well-known/agent-card.json. UiPath le récupère à ce moment, à l'aide des informations d'identification configurées sur le même écran: la connexion attachée, s'il y en a une, ou les en-têtes configurés dans le cas contraire. Les références de ressources dans ces en-têtes sont également résolues pour cette requête, de sorte qu'une carte derrière une clé API stockée dans Orchestrator peut être lue sans coller la clé.

L'URL est vérifiée par rapport à la protection SSLF avant que la demande ne soit effectuée, sauf si l'agent est atteint via le Relay. Si UiPath ne peut pas atteindre l’adresse ou si la réponse n’est pas une réussite, l’agent n’est pas créé. Il s’agit de la seule option qui prend en charge l’actualisation ultérieure de la carte .

Option 2: coller la carte JSON

Collez le document de carte directement. UiPath n'effectue aucune demande sortante, donc aucune information d'identification n'est nécessaire au moment de l'inscription, et la vérification SSLF ne s'applique pas. Utilisez cette option dans le cas d'un agent qui n'est pas accessible depuis UiPath au moment de l'inscription ou dont la carte n'est pas servie à une adresse publique. Si une URL et un fichier JSON collé sont fournis, le fichier JSON collé est utilisé et aucune extraction ne se produit.

Cependant, la carte arrive, UiPath l'accepte uniquement s'il s'agit d'un objet JSON qui annonce un point de terminaison HTTP ou HTTPS JSON-RPC utilisable, via le champ url v0.3 ou la liste supportedInterfaces v1.0. Une carte sans carte est rejetée lors de l'inscription plutôt qu'au moment de l'appel.

La carte stockée n'est pas récupérée à chaque appel, de sorte qu'une carte modifiée en amont ne se met pas à jour d'elle-même. L’actualisation de la carte la récupère à nouveau, requiert l’autorisation de Modification sur les serveurs MCP et requiert une URL de carte: un agent enregistré en collant JSON n’en a aucune et l’actualisation est refusée.

Remarque :

Une actualisation est authentifiée de la même manière qu'un appel, et non de l'enregistrement: elle utilise la connexion configurée pour l'utilisateur qui l'a déclenché et revient à la connexion par défaut de l'agent. Une actualisation peut donc réussir pour un utilisateur et échouer pour un autre.

Une connexion Integration Service

Le fait d'associer une connexion à l'agent signifie qu'UiPath récupère un nouveau jeton de porteur à chaque appel. Il s'agit de la meilleure option pour tout agent dont les informations d'identification expirent, car rien ne doit être pivoté manuellement. La connexion est utilisée avec le dossier auquel elle appartient; si ce dossier est manquant, l'appel échoue plutôt que de revenir à un autre dossier ou à un en-tête configuré.

En-têtes

Vous pouvez également configurer les en-têtes attendus par l'agent sous forme de paires nom et valeur. Le cas courant est Authorization: Bearer <your-api-key>. Les en-têtes sont stockés chiffrés et masqués lors de leur lecture, de sorte qu’une clé secrète collée une fois ne sera plus visible par la suite.

Priorité des connexions et des en-têtes

Si une connexion est attachée, elle fournit l'en-tête Authorization, et tout en-tête Authorization configuré est également ignoré plutôt que simplement écrasé: la ligne configurée est supprimée avant que les références de ressources ne soient résolues, de sorte qu'un en-tête pointant vers une ressource ne sera pas t même recherché. Tous les autres en-têtes configurés sont toujours envoyés. La même priorité s'applique à la récupération de la carte au moment de l'enregistrement.

Connexions par utilisateur

Les utilisateurs individuels peuvent attacher une connexion qui leur est propre via les configurations utilisateur sur la ligne de l'agent, ce qui nécessite l'autorisation Modifier sur les connexions. Lorsque l’agent est appelé, la connexion est sélectionnée dans cet ordre:

1. La connexion configurée pour l'utilisateur appelant.
2. La connexion par défaut de l’agent.
3. Aucune connexion, auquel cas les en-têtes configurés sont utilisés, ou aucune authentification n’est envoyée si aucun n’est configuré.

La connexion est choisie pour l'identité que représente le jeton. Dans le cas d'une exécution planifiée ou non assistée, cette identité ne correspond pas à la personne qui a créé ou planifié l'agent, de sorte qu'une connexion attachée sous le propre utilisateur d'une personne n'y est pas utilisée. Si un agent doit être accessible depuis des exécutions Unattended, donnez-lui une connexion par défaut au lieu de vous fier à des connexions par utilisateur.

Les configurations utilisateur affichent également l’état de chaque connexion:

État (Status)	Signification
Actif (Active)	La connexion est autorisée et prête.
Requiert l'authentification	Aucune connexion de travail n’est disponible pour cet utilisateur, soit parce qu’aucune n’est configurée, soit parce que celle-ci nécessite une nouvelle autorisation.
Indisponible	La connexion par défaut partagée est manquante, désactivée, expirée ou inaccessible.
Inactif	L’agent n’est pas actif ou la connexion est désactivée.

Référencement d'une ressource Orchestrator

Au lieu de coller un secret dans un en-tête, donnez à l'en-tête une valeur sous la forme %ASSETS/AssetName%. UiPath la résout à la valeur de la ressource avant d’envoyer la requête, en lisant la ressource du dossier de l’agent sous l’identité appelant. Si la ressource ne peut pas être lue, l'appel échoue plutôt que de transférer l'espace réservé non résolu.

Les ressources Text, Secret, Bool, Integer, Credential et Windows Credential sont prises en charge; Les ressources Credential (Informations d'identification) et Windows Credential (Informations d'identification Windows) se résolvent sur la valeur du mot de passe. Les ressources clé-valeur-liste sont rejetées, car une valeur d'en-tête doit se résoudre en une seule chaîne. La valeur résolue est transmise à l'agent distant sous forme d'en-tête configuré de sorte à utiliser des en-têtes basés sur la ressource uniquement pour les points de terminaison dans lesquels vous avez confiance avec ces secrets.

Rejoindre un agent dans un réseau privé

Un agent qui s'exécute au sein d'un réseau privé sans ports de pare-feu entrants est atteint via le relais: UiPath envoie la requête à un serveur de relais, et un client de relais à l'intérieur du réseau la collecte et la transmet à l'agent. Le relais modifie la façon dont UiPath atteint l'agent, et non la façon dont il s'authentifie: la connexion, les en-têtes, leur priorité et les références de ressources se comportent exactement comme décrit ci-dessus. La vérification SSLF ne s’applique pas à l’appel ou à la récupération de la carte, car la demande n’est pas envoyée à une adresse publique.

Appeler un agent enregistré

Deux types d’appelant atteignent un agent distant enregistré. Un client UiPath, tel qu'un agent UiPath ou un flux Maestro, utilise l'agent comme outil et la plateforme résout l'adresse, le jeton et la version du protocole au moment de l'exécution. Un client HTTP direct appelle l'URL de l'agent et doit fournir les trois. Les deux s’authentifient auprès d’UiPath de la même manière; le reste de cette section n'est important que lors de l'appel direct.

Chaque requête comporte un jeton de porteur dans l'en-tête Authorization. Rien n’est reporté entre les tours: chaque message d’une conversation est authentifié de manière autonome.

Ce que vous atteignez	Ce dont l'appelant a besoin
L'agent lui-même	Un jeton valide pour l'organisation et le locataire, l'accès au dossier qui contient l'agent et l'autorisation Afficher sur les serveurs MCP dans ce dossier. Les rôles Automation User, Automation Developer, Folder Administrator et Personal Workspace Administrator l'incluent tous.
Sa carte d'agent	Accès aux dossiers uniquement. La carte est des métadonnées de découverte, elle est donc délibérément plus facile à atteindre que l’agent lui-même.

Récupérer un jeton

A2A utilise les mêmes jetons que le reste de la plate-forme.

Method	Source du jeton	Quand l’utiliser
Jeton d’accès personnel (PAT)	UiPath Cloud, sous vos préférences utilisateur	L'option la plus simple pour les tests. Son expiration est configurable et fonctionne avec n'importe quel client HTTP.
Connexion interactive	uipath auth	Développement local. Le jeton dure environ une heure et n’est pas actualisé automatiquement.
Application externe	Admin > External Apps, informations d’identification du client	Appels Unattended, tels que les pipelines CI/CD et les comptes de service, où personne n'est présent pour se connecter.

Pour savoir comment créer chacun d’eux, consultez la section Authentification du serveur MCP. Les Agents A2A et les serveurs MCP sont validés par le même pipeline, de sorte que tout jeton qui fonctionne pour un serveur MCP fonctionne également pour un agent A2A. La seule exception est le flux OAuth MCP, qui est uniquement pris en charge par les points de terminaison MCP, car il dépend de métadonnées de découverte que les agents A2A ne publient pas.

Récupération de l’URL de l’agent

Un agent distant enregistré réside à:

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

Sa carte d’agent se trouve à la même adresse suivie de /.well-known/agent-card.json. Obtenez l'URL de Agent Gateway > Agents A2A en sélectionnant Copier l'URL sur la ligne de l'agent, plutôt que de l'assembler manuellement: la clé de dossier est un GUID plutôt qu'un nom de dossier, et le champ de données dynamique n'est pas l'affichage nom.

Sélectionner la version du protocole

Les agents A2A distants prennent en charge A2A v0.3 et v1.0, sélectionné avec l'en-tête de requête A2A-Version:

• Pour la version v1.0, définissez la valeur de l'en-tête sur 1.0.
• Pour la version v0.3, omettez l'en-tête. Une valeur vide ou vide est traitée de la même manière.

Le même en-tête s'applique lors de la demande de carte d'agent et détermine la version de la carte renvoyée par UiPath. UiPath transmet une demande uniquement à un point de terminaison qui correspond à la version demandée; elle ne bascule pas sur une autre version, car cela enverrait à l'agent distant un message dans un format de fil de discussion qu'il ne comprend pas. Si la carte d’agent stockée ne publie aucun point de terminaison JSON-RPC pour cette version, la demande est rejetée et la version est nommée dans la réponse.

Ce qui ne dépasse jamais la limite

Trois éléments sont arrêtés à la limite:

• Le jeton de l'appelant n'atteint jamais l'agent distant. UiPath le valide, le supprime et injecte les informations d'identification configurées pour l'agent. L'agent distant n'a aucun moyen d'apprendre qui l'a appelé via UiPath ou de réutiliser cette identité. UiPath supprime également ses propres en-têtes internes et injecte un seul en-tête de traçage sortant.
• Le schéma d’authentification de l’agent distant n’est jamais annoncé aux appelants. La carte d'agent qu'UiPath sert toujours déclare la propre authentification du porteur d'UiPath, quel que soit l'amont publié, et toute signature sur la carte d'origine est supprimée, car la réécriture de la carte l'invalide. Pour voir la carte telle que l'agent distant l'a publiée, ouvrez l'agent et sélectionnez Edit (Modifier).
• Un appel ne peut pas revenir en arrière sur la plate-forme. Une URL de carte d’agent qui redirige vers UiPath est rejetée lors de l’enregistrement de l’agent. Au-delà, chaque requête proxy comporte un marqueur, et une requête qui le comporte déjà est refusée.

Résolution des problèmes

Pour connaître les erreurs que vous êtes le plus susceptible de rencontrer et savoir comment les résoudre, consultez la section Tester et résoudre les problèmes A2A. Sa section sortante couvre les échecs sur ce chemin.

Dans le sens inverse, lorsqu'un client externe appelle un agent que vous avez déployé, cochez la case Entrant (externe à UiPath).