Tester et résoudre les problèmes A2A

Solutions pour les erreurs courantes lors du test des appels A2A entrants ou sortants dans Orchestrator, notamment les échecs d'authentification, les agents manquants et les délais d'expiration.

Remarque :

Cette fonctionnalité est en aperçu.

Testez un agent A2A avec des appels directs avant de l'utiliser à partir d'un agent UiPath ou d'un client externe. Le fait d'appeler l'agent vous affiche la demande et la réponse brutes, ce qui vous indique s'il y a un problème au niveau de l'agent, de votre authentification ou de l'application d'appel.

Les appels entrants et sortants échouent pour des raisons différentes. Cette page couvre donc d’abord ce qui s’applique aux deux directions, puis les divise par direction. L'URL que vous appelez identifie la moitié qui vous appartient:

• .../agenthub_/a2a/{folderKey}/{agentReleaseId} est entrant: un client externe appelle un agent conversationnel déployé sur la plate-forme.
• .../agenthub_/a2a/remote/{folderKey}/{slug} est sortant: UiPath appelle un agent hébergé ailleurs au nom de l'appelant.

Tester un agent avec des appels directs

Les exemples utilisent cURL, mais les mêmes requêtes fonctionnent à partir de Postman, du SDK A2A Python ou.NET ou d'un client graphique A2A.

Direction	URL	Où l’obtenir
Entrant	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}	Automatisations > Processus > Copier l’URL de la carte A2A. {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é.
Sortant	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}	Agent Gateway > Agents A2A, puis Copier l'URL sur la ligne de l'agent.

1. Définissez TOKEN sur un jeton de porteur et AGENT_URL sur l'URL pour votre direction.
2. Demandez d’abord la carte d’agent. Une réponse réussie confirme que l’agent existe, que le dossier est résolu pour votre identité et que votre jeton est accepté:

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

3. Envoyez un message au point de terminaison JSON-RPC, qui est la même adresse sans le suffixe /.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 réponse comporte un contextId. L’inclure dans le message suivant poursuit la même conversation; l'ID de conversation, l'ID de tâche et le contextId sont la même valeur. message/stream renvoie la réponse sous forme de flux SSE: ajoutez -N pour arrêter cURL de la mise en mémoire tampon, et -H "Accept: text/event-stream".

Si un appel sortant via UiPath échoue, l'envoi de la même requête directement à l'agent distant, à l'aide des informations d'identification attendues par l'agent, vous indique si le problème est lié à UiPath ou à l'agent lui-même.

Erreurs communes aux deux directions

401 Non autorisé

La requête a atteint UiPath, mais le jeton n’a pas été accepté.

Origine	Résolution
Le jeton a expiré	Obtenez un nouveau jeton. Les jetons de connexion interactifs expirent après une heure; un jeton d'accès personnel a une expiration configurable;
Le jeton a été émis pour un locataire différent	Vérifiez que l’organisation et le locataire dans l’URL de l’agent correspondent à ceux pour lesquels le jeton a été émis.
L'en-tête est incorrect	Le format est Authorization: Bearer <your-access-token>.
Aucun jeton n’a été envoyé	Chaque requête, y compris la demande de carte d’agent, doit inclure un jeton.

Délais d'attente

Limite	ApplicableÀ	Que se passe-t-il
15 minutes	Toute demande unique effectuée via UiPath.	La requête est coupée. Dans cette fenêtre, une réponse diffusé se poursuit tant que la connexion est ouverte.
5 minutes	Un tour d'une conversation entrante.	Le tour échoue. La tâche reste utilisable et le tour peut être réessayé.
30 secondes	Démarrage de la session de l’agent derrière un tour entrant.	Comme ci-dessus.
5 minutes	Un agent sortant appelé en tant qu'outil par un agent UiPath.	L'appel d'outil échoue et le texte d'erreur atteint l'agent UiPath en tant que sortie d'outil.

Pour les travaux qui s’exécutent plus longtemps qu’une seule requête ne le permet pas, diffuser la réponse ou utiliser des tâches A2A: prenez l’identifiant de la tâche à partir de la première réponse et interrogez son résultat.

Versions de protocole et de carte

Les deux directions sélectionnent la version du protocole A2A avec l’en-tête A2A-Version, y compris sur la demande de carte de l’agent. Définissez-le sur 1.0 pour la version v1.0 ou omettez-le pour la version v0.3 (une valeur vide ou vierge est traitée de la même manière).

En entrée, la valeur correspond exactement, de sorte que 1.0 est reconnu et 1.0.0 ne l’est pas. Le point de terminaison entrant accepte l'un ou l'autre format de fil de discussion, quelle que soit la carte que vous avez récupérée, de sorte que l'en-tête ne change que la carte que vous obtenez.

En sortant, seules les versions majeure et mineure sont lues, donc 1.0 et 1.0.0 sélectionnent tous deux v1.0. UiPath transmet une demande uniquement à un point de terminaison qui correspond à la version demandée, de sorte qu'une demande pour une version que la carte stockée ne peut pas satisfaire est rejetée avec 400.

Entrant (externe à UiPath)

Il n'y a rien à enregistrer dans cette direction, de sorte que chaque échec se produit lors d'un appel. tasks/get renvoie l'état actuel et l'historique d'une conversation. Pour ce que la direction requiert, vérifiez Entrant (externe à UiPath).

Le dossier ou l’agent est introuvable (404)

Message	Origine	Résolution
Folder with key {folderKey} not found	La clé de dossier est erronée ou nomme un dossier auquel l'appelant ne peut pas accéder.	Vérifiez l'URL et l'accès au dossier de l'appelant.
Conversational agent with release ID {agentReleaseId} not found in folder {folderId}	Aucun agent conversationnel n’est déployé sous cet ID de version dans ce dossier.	Vérifiez l’ID de version par rapport à l’entrée de l’agent sous Automatisations > Processus.

Une clé de dossier qui se résout est mise en cache pendant 30 minutes. Une clé qui ne se résout pas n’est pas mise en cache, de sorte que l’octroi à un utilisateur de l’accès à un dossier prend effet lors de son prochain appel. Un dossier qui a été supprimé, ou dont l’accès a été retiré, poursuit la résolution jusqu’à ce que son entrée mise en cache expire.

Seul le point de terminaison de la carte d'agent valide l'ID de version avant de répondre. Demandez donc d'abord la carte d'agent lors du diagnostic. Sur message/send, un ID de version incorrect n'est pas signalé comme clairement.

L'appelant est refusé par l'agent

La réussite de la recherche du dossier n’est pas la même que l’autorisation. Pour ce dont l'appelant a besoin, vérifiez ce dont l'appelant a besoin.

La conversation ne se poursuit pas

Symptôme	Origine	Résolution
Un message de suivi démarre une nouvelle conversation	La valeur contextId ne correspond pas à une tâche détenue par UiPath.	Envoyer taskId avec contextId; un ID non reconnu est alors signalé comme Task not found.
Task not found, pour un ID qui fonctionnait auparavant	La tâche a expiré après sept jours d’inactivité, ou la demande est envoyée à un dossier ou à un ID de version différent.	Envoyez la demande au dossier et traitez sous lequel la tâche a été créée, ou démarrez une nouvelle tâche.
Cannot send a message to a task in a terminal state.	La tâche est completed, canceled, failed ou rejected.	Démarrer une nouvelle tâche.
Task is in a terminal state and cannot be canceled.	La tâche a déjà atteint un état terminal et tasks/cancel s’applique uniquement à une tâche qui est toujours en cours.	Aucune action requise. La tâche est déjà arrêtée.

Requêtes qui ne sont pas prises en charge

Ceux-ci renvoient une erreur JSON-RPC dans une réponse HTTP réussie.

Requête (Request)	Ce que vous obtenez	Utiliser plutôt
tasks/resubscribe, task/subscribe	UnsupportedOperation	message/stream
tasks/list	UnsupportedOperation	Suivre les ID de tâche sur le client
tasks/pushNotificationConfig/*	PushNotificationNotSupported	message/stream. La carte annonce pushNotifications: false
La carte d’agent étendue	ExtendedAgentCardNotConfigured	La carte standard

Un historyLength négatif sur tasks/get est rejeté avec InvalidParams.

Sortant (UiPath vers externe)

Un appel dans cette direction est authentifié deux fois: une fois par l'appelant auprès d'UiPath et une fois par UiPath auprès de l'agent. La plupart des échecs proviennent du deuxième saut. Les appels associés sont regroupés dans des Traces par contextId. Pour la configuration, vérifiez Sortant (UiPath vers externe).

L'enregistrement d'un agent échoue

Symptôme	Origine	Résolution
Conflit 409	Un autre agent du dossier utilise déjà ce nom ou ce champ de données dynamique.	Choisissez un nom ou un champ de données dynamique différent; les deux doivent être uniques dans le dossier. Le champ de données dynamique ne peut pas être modifié après sa création.
La carte d’agent est requise	Aucune URL de carte ni JSON de carte n’ont été fournis.	Indiquez-en l'une.
La carte d’agent n’est pas valide	Le JSON n’est pas un objet de carte ou ne publie aucun point de terminaison JSON-RPC.	Indiquez la carte telle qu’elle a été publiée par l’agent distant.
L’URL de la carte d’agent n’est pas valide	L’URL n’a pas de schéma ou n’est pas accessible via Internet public.	Saisissez une URL absolue http ou https , ou définissez le Type de connexion sur Privé (Relai) (Privé).

L'appelant n'est pas autorisé à utiliser l'agent (403)

Origine	Résolution
L'appelant ne dispose pas de l'autorisation Afficher sur les serveurs MCP	Activez Afficher sur les serveurs MCP pour le rôle attribué.
L'appelant n'est pas affecté au dossier	Affectez l'appelant au dossier qui contient l'agent.
Aucune licence n’est disponible	Vérifiez Admin > Licences.

La récupération de la carte de l’agent nécessite l’accès au dossier, mais pas l’autorisation Afficher sur les serveurs MCP. Si la carte se charge, mais que l'envoi d'un message renvoie 403, l'autorisation manquante est Afficher sur les serveurs MCP.

L’agent est introuvable (404)

Origine	Résolution
L’URL contient le nom complet de l’agent au lieu de son champ de données dynamique	Utilisez le champ de données dynamique, et non le nom complet.
La clé de dossier est incorrecte	L'agent est recherché dans le dossier nommé dans l'URL. Copiez l’URL à partir de la ligne de l’agent.
L’agent a été supprimé	Confirmez qu’il s’affiche toujours dans Agent Gateway > Agents A2A.

La requête n'est pas autorisée (400)

La requête est déjà passée par le proxy A2A de la plate-forme, et une requête qui arrive par ce biais est refusée afin que les appels ne puissent pas passer en boucle. Cela se produit lorsqu’une URL d’agent UiPath A2A est enregistrée en tant qu’agent distant. Enregistrez plutôt la propre adresse de l’agent distant.

La carte stockée est manquante ou obsolète

La carte stockée n'est pas récupérée à nouveau lors des appels suivants, de sorte qu'une carte modifiée en amont continue de servir son contenu antérieur. Pour la mettre à jour, ouvrez l’agent, sélectionnez Modifier et fournissez la carte actuelle. Le même écran affiche la carte telle que l’agent distante l’a publiée, avant qu’UiPath ne réécrive les points de terminaison annoncés.

Deux échecs résultent d'une carte manquante ou obsolète:

Symptôme	Origine	Résolution
404 sur la carte de l’agent, 400 sur message/send	Aucune carte n’est stockée pour l’agent, il n’y a donc rien à servir.	Ouvrez l'agent dans Agent Gateway > Agents A2A et fournissez la carte.
400, aucun point de terminaison pour la version A2A demandée	Aucun en-tête A2A-Version n’a été envoyé, mais l’agent ne prend en charge que la version v1.0; ou 1.0 a été envoyé et l’agent prend uniquement en charge la version v0.3; ou la carte ne publie aucun point de terminaison JSON-RPC; ou l'agent distant a changé et la carte stockée ne correspond plus.	Envoyez ou omettez l’en-tête pour qu’il corresponde à ce que l’agent prend en charge, ou fournissez la carte actuelle. Les Agents A2A distants doivent exposer un point de terminaison JSON-RPC; les autres types d'interface ne sont pas pris en charge.

502: UiPath ne peut pas atteindre l'agent distant ou s'authentifier auprès de l'agent distant

UiPath répond 502 lorsque le saut vers l’agent distant échoue, soit pendant que vous enregistrez l’agent, soit pendant qu’il est appelé.

Lors de l’enregistrement, UiPath récupère la carte de l’agent, et l’agent n’est pas créé en cas d’échec:

Origine	Résolution
L’URL n’est pas accessible depuis UiPath	Confirmez que l’URL se résout publiquement ou utilisez Privé (Relai) (Privé).
L’agent nécessite une authentification qui n’est pas configurée	Ajoutez l'en-tête ou la connexion attendue par l'agent, puis enregistrez à nouveau.

Lors d'un appel, une connexion qui est connectée mais ne peut pas fournir de jeton échoue l'appel, car la connexion est alors la seule source de l'en-tête Authorization. Ouvrez les Configurations utilisateur sur la ligne de l'agent et vérifiez le statut de la connexion (voir Connexions par utilisateur pour connaître la signification de chaque statut). Un statut Inactif signifie que la connexion est désactivée, vérifiez-le donc dans l’onglet Connexions .

Si les informations d’identification sont résolues mais que l’agent est toujours inaccessible:

Origine	Résolution
L'agent utilise un réseau privé	Définissez le type de connexion sur Privé (Retour) (Privé).
L’adresse ne peut pas être résolue ou le certificat n’est pas accepté	Vérifiez le point de terminaison publié sur la carte de l’agent, qui est souvent un hôte différent de l’URL de la carte.
L’agent n’est pas en cours d’exécution	Appelez directement l’agent pour confirmer.
L’agent a été déplacé	La carte stockée pointe toujours sur l’ancienne adresse. Indiquez la carte actuelle.

Un en-tête qui fait référence à une ressource ne peut pas être résolu

Une valeur d'en-tête au format %ASSETS/AssetName% est résolue avant l'envoi de la requête, et si la ressource ne peut pas être lue, l'appel échouera sans que la valeur non résolue soit jamais envoyée.

Origine	Résolution
La ressource n’existe pas dans le dossier de l’agent	Créez-le dans Orchestrator ou référencez une ressource qui le fait.
L’appelant ne peut pas lire la ressource	Accordez l'autorisation Afficher pour les ressources.
Le type de ressource n’est pas pris en charge	Un en-tête doit se résoudre à une valeur unique, de sorte que les ressources clé-valeur-liste sont rejetées. Pour connaître les types qui fonctionnent, consultez Référencement d'une ressource Orchestrator.

L'appel expire (504)

Lors d'un appel direct, l'agent distant ne commençait pas à répondre à temps. La limite s’applique au temps écoulé avant que l’agent commence à répondre; une fois démarré, un flux peut se poursuivre bien au-delà de ce point. Utilisez message/stream ou renvoyez une tâche et une interrogation pour le résultat, pour un agent qui a besoin de plus de temps pour commencer à répondre. S’il ne cesse de expirer, appelez-le directement pour confirmer qu’il est accessible et vérifiez ses propres journaux.

La réponse est trop volumineuse

Les réponses d’un agent distant sont soumises à une limite de taille. Une réponse qui le dépasse est rejetée, et une réponse diffusé qui le dépasse est arrêtée à mi-parcours, une fois que l'application appelant a déjà reçu certains événements. Si un agent renvoie du contenu volumineux, demandez-lui plutôt de renvoyer une référence telle qu’une URL.

Appeler un agent depuis un agent UiPath

Lorsqu'un agent enregistré est joint en tant qu'outil dans Agent Builder ou dans un flux Maestro, une erreur de l'agent distant est renvoyée à l'agent UiPath en tant que sortie d'outil, avec un état de tâche de error, et l'exécution se poursuit. L'agent UiPath continue avec ce texte comme entrée, de sorte qu'une erreur ressemble à un résultat d'outil normale pour le modèle. Pour diagnostiquer un appel défaillant, ouvrez les Traçages de l'exécution et sélectionnez l'appel d'outil pour l'agent; le traçage enregistre le message envoyé et la réponse ou l'erreur renvoyée.

Les agents UiPath appellent les agents distants avec message/send; vous pouvez donc l'utiliser lorsque vous reproduisez ce que fait un agent UiPath. Le flux est disponible uniquement lorsque vous appelez vous-même l'URL UiPath de l'agent.

Sur ce chemin, la plateforme attend cinq minutes pour la réponse complète, et la sortie produite progressivement ne prolonge pas cette attente. Pour un agent qui a besoin de plus de temps, faites en sorte qu’il renvoie une tâche qui est toujours en cours: la plateforme maintient la tâche entre les tours, afin que l’agent UiPath puisse la poursuivre à un tour ultérieur. Une tâche qui a déjà atteint completed, canceled, failed, ou rejected ne peut pas être poursuivie et l'appel suivant démarre une nouvelle tâche dans la même conversation.

Si la carte stockée ne publie ni une interface JSON-RPC v1.0 ni un point de terminaison v0.3 utilisable, l’outil ne peut pas du tout être créé et l’exécution signale qu’aucun point de terminaison compatible n’est disponible. Ouvrez l'agent, sélectionnez Modifier et confirmez que la carte expose un point de terminaison JSON-RPC sur http ou https.

Les appels réussissent mais se comportent de manière inattendue

Ce sont des échecs où aucune erreur n’apparaît, il n’y a donc pas de code de statut à utiliser.

Symptôme	Origine	Résolution
Les appels utilisent la mauvaise identité	Une connexion configurée pour l'utilisateur appelant est prioritaire sur la connexion par défaut de l'agent.	Vérifiez les configurations utilisateur d’une connexion à laquelle vous ne vous attendiez pas.
Un en-tête Authorization configuré semble être ignoré	Une connexion est jointe et la connexion fournit cet en-tête.	Attendu. Tous les autres en-têtes que vous avez configurés sont toujours envoyés.
Une connexion attendue est absente de la liste	Les connexions sont filtrées par l'adresse publiée sur la carte de l'agent, qui est souvent un hôte différent de l'URL de la carte que vous avez enregistrée.	Vérifiez que la connexion est activée et qu'elle se trouve dans un dossier partagé ou dans l'espace de travail personnel de l'utilisateur sélectionné.
Un agent UiPath décrit les capacités de l’agent distant de manière incorrecte ou ne les utilise pas comme prévu	La description de l'outil et la liste des compétences proviennent de la carte d'agent stockée.	Mettez à jour la carte enregistrée, puis ouvrez l’agent UiPath et confirmez la description mise à jour.
Un appel n'est pas regroupé avec le reste de sa conversation dans Traces	Le premier message d’une conversation n’a pas encore de contextId.	Aucune action requise. Les messages ultérieurs de la conversation sont regroupés.