Entrant (externe à UiPath)

Comment un agent ou un client externe tient une conversation avec un agent conversationnel que vous avez déployé dans Orchestrator et comment ces appels sont authentifiés.

Remarque :

Cette fonctionnalité est en aperçu.

L'agent A2A entrant est un agent ou un client externe qui tient une conversation avec un agent conversationnel que vous avez déployé sur la plateforme UiPath. UiPath est la destination de l'appel, et non une passerelle devant quelque chose d'autre.

Il n'y a rien à inscrire pour cette direction. Chaque agent conversationnel déployé dans un dossier parlera déjà A2A: Agent Gateway sert sa carte d’agent et traduit le trafic A2A en conversation native avec l’agent. Tout client A2A peut utiliser l’agent avec uniquement l’URL de la carte et un jeton UiPath.

Étant donné qu'UiPath est la destination, il n'y a qu'une seule authentification à configurer: l'authentification de l'appelant auprès d'UiPath. Les connexions, les en-têtes et les références de ressources Orchestrator qui apparaissent dans le sens sortant n’ont pas d’équivalent ici.

Exposer les agents conversationnels déployés

La carte d’agent

Chaque agent déployé dispose d'une carte à:

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

{folderKey} est la clé du dossier dans lequel l’agent est déployé et {agentReleaseId} est l’ID de version de l’agent conversationnel déployé.

La carte est générée à partir du déploiement actuel, de sorte que son nom, sa description et sa version correspondent toujours au déploiement. Il annonce le flux, l'entrée/la sortie de texte et de fichier et l'authentification du porteur. Il n’y a pas de découverte anonyme: la récupération de la carte nécessite déjà un jeton UiPath.

Vous pouvez copier l'URL A2A depuis Automatisations > Processus > Copier l'URL de la carte A2A. Vous pouvez également inspecter à la fois l’URL A2A et la carte de l’agent depuis l’onglet Agents déployés après avoir sélectionné l’agent conversationnel.

Appel de l'agent

Le point de terminaison JSON-RPC est l'URL de la carte sans le suffixe /.well-known/agent-card.json. Sur le fil, un appel ressemble à ceci:

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"
        }
      ]
    }
  }
}

Une tâche A2A représente une conversation avec l’agent. Le premier message crée la tâche et la réponse porte un contextId; l’inclusion de cet ID dans le message suivant poursuit la même conversation. Après chaque réponse, l’état de la tâche est input-required, ce qui maintient la conversation ouverte pour les messages de suivi.

message/stream renvoie la réponse sous forme de flux SSE (Événements envoyés par le serveur). tasks/get lit l'état et l'historique d'une tâche, et tasks/cancel annule une tâche en cours d'exécution. Les notifications Push et tasks/resubscribe ne sont pas pris en charge, la sortie en direct nécessite donc message/stream.

Authentification

L'entrée A2A a une seule authentification: l'appelant s'authentifiant auprès d'UiPath. UiPath est la destination de l'appel, il n'y a donc pas de deuxième saut et aucune information d'identification en amont à configurer.

Chaque demande comporte un jeton de porteur dans l'en-tête Authorization, la demande de carte d'agent incluse. Il n’y a pas de découverte anonyme et rien n’est reporté entre les tours: chaque message d’une conversation est authentifié de manière autonome.

Ce dont l'appelant a besoin

Le jeton doit être valide pour l’organisation et le locataire nommés dans l’URL, et le dossier nommé dans l’URL doit être un dossier que l’identité d’appel peut voir. Rien d’autre n’est requis: aucune autorisation de dossier, aucune étendue spécifique à A2A et aucun équivalent à l’autorisation d’affichage sur les serveurs MCP dont un appel sortant a besoin. L’identité et le dossier sont l’ensemble de ce qu’UiPath vérifie ici, et rien n’inspecte le contenu d’un message.

Tout jeton qui fonctionne ailleurs sur la plate-forme fonctionne ici: connexion interactive, applications externes ou jeton d'accès personnel, ce qui est le plus simple à utiliser pour les tests.

Remarque :

Créez un jeton d'accès personnel avec la ressource Accès à l'API Orchestrator sélectionnée, car cette ressource définit l'audience que ce point de terminaison vérifie. Sans cela, le jeton est rejeté avant que l'appel n'atteigne l'agent, et l'erreur nomme l'audience plutôt que le jeton, de sorte qu'il ne ressemble pas du tout à un problème d'étendue.

Pour savoir comment obtenir chaque type de jeton, consultez la section Authentification du serveur MCP.

UiPath valide le jeton, résout le dossier et transmet la requête au service qui exécute l’agent conversationnel, avec le jeton de l’appelant en pièce jointe. Le sens entrant est la direction dans laquelle les jetons de l'appelant se déplacent au-delà de Agent Gateway. Il reste à l’intérieur de UiPath, car le service qui exécute l’agent est un service UiPath. Lors d'un appel sortant, le jeton est supprimé à la limite et remplacé par les informations d'identification configurées pour l'agent distant.

Sélectionner la version de la carte

Seul le point de terminaison de la carte d’agent lit l’en-tête facultatif A2A-Version; le point de terminaison du message l'ignore. Un client v1.0 envoie l'en-tête par défaut, vous avez donc rarement besoin de le définir vous-même.

• Envoyez 1.0 pour la carte v1.0 stricte.
• Envoyez 0.3 pour la carte stricte v0.3, qui ne comporte pas de données v1.0 et convient à un client dont le désérialisateur rejette les propriétés inconnues.
• N'envoyez rien ou toute autre valeur et vous obtenez une carte v0.3 avec la propriété v1.0 supportedInterfaces ajoutée, afin qu'un client v1.0 qui n'a pas envoyé l'en-tête puisse toujours la lire.

Le point de terminaison du message accepte les deux formats de fils de discussion, quel que soit l'en-tête, de sorte qu'un client v1.0 et un client v0.3 peuvent parler au même agent. La valeur correspond exactement, de sorte que 1.0.0 n'est pas traité comme 1.0. Et l'absence de l'en-tête ne vous donne pas la carte v0.3 stricte ici, comme cela est le cas pour un agent distant enregistré. Si vous comparez les deux directions, c'est pourquoi leurs cartes diffèrent.

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 Entrant couvre les échecs de ce chemin.

Dans le sens inverse, où UiPath appelle un agent hébergé ailleurs, cochez la case Sortant (UiPath vers externe).