Testen Sie A2A und beheben Sie Fehler

Lösungen für häufige Fehler beim Testen von eingehenden oder ausgehenden A2A-Aufrufen in Orchestrator, einschließlich Authentifizierungsfehlern, fehlenden Agents und Timeouts.

Hinweis:

Diese Funktion befindet sich in der Vorschau.

Testen Sie einen A2A-Agent mit direkten Aufrufen, bevor Sie ihn von einem UiPath-Agent oder einem externen Client verwenden. Wenn Sie den Agent selbst aufrufen, werden Ihnen die Roh-Anforderung und Antwort angezeigt, die Ihnen mitteilen, ob ein Problem beim Agent, in Ihrer Authentifizierung oder in der aufrufenden Anwendung liegt.

Eingehende und ausgehende Aufrufe schlagen aus unterschiedlichen Gründen fehl, daher wird auf dieser Seite zunächst beschrieben, was für beide Richtungen gilt, und dann wird nach Richtung unterteilt. Die URL, die Sie aufrufen, identifiziert, welche Hälfte Ihnen gehört:

• .../agenthub_/a2a/{folderKey}/{agentReleaseId} ist eingehend: Ein externer Client ruft einen auf der Plattform bereitgestellten Agent auf.
• .../agenthub_/a2a/remote/{folderKey}/{slug} ist ausgehend: UiPath ruft einen Agent auf, der an anderer Stelle im Namen des Anrufers gehostet wird.

Testen Sie einen Agent mit direkten Aufrufen

Die Beispiele verwenden cURL, aber dieselben Anforderungen funktionieren von Postman, dem A2A Python- oder.NET SDK (Software Development Kit) oder einem grafischen A2A-Client.

Richtung	URL	Wo es abgerufen werden kann
Eingehend	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}	Automatisierungen > Prozesse > A2A-Karten-URL kopieren. {folderKey} ist der Schlüssel des Ordners, in dem der Agent bereitgestellt wird, und {agentReleaseId} ist die Version-ID des bereitgestellten Agents.
Ausgehend	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}	Agent Gateway > A2A Agents und dann URL kopieren in der Zeile des Agents.

1. Legen Sie TOKEN auf ein Bearer-Token und AGENT_URL auf die URL für Ihre Richtung fest.
2. Fordern Sie zuerst die Agent-Karte an. Eine erfolgreiche Antwort bestätigt, dass der Agent vorhanden ist, der Ordner für Ihre Identität aufgelöst wird und Ihr Token akzeptiert wird:

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

3. Senden Sie eine Nachricht an den JSON-RPC-Endpunkt (JSON Remote Prozedur Call), der dieselbe Adresse ohne das Suffix /.well-known/agent-card.json ist:

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

Die Antwort hat contextId. Wenn Sie sie in die nächste Nachricht einfügen, wird dieselbe Konversation fortgesetzt; Die Konversations-ID, die Aufgaben-ID und der contextId sind der gleiche Wert. message/stream gibt die Antwort als SSE-Stream (Server-Sent Events) zurück: Fügen Sie -N hinzu, um die Pufferung von cURL zu verhindern, und -H "Accept: text/event-stream".

Wenn ein ausgehender Aufruf über UiPath fehlschlägt, wird Ihnen mit der gleichen Anforderung direkt an den Remote-Agent unter Verwendung der vom Agent erwarteten Anmeldeinformationen mitgeteilt, ob das Problem bei UiPath oder beim Agent selbst liegt.

Fehler, die für beide Richtungen gleich sind

401 Nicht autorisiert

Die Anforderung hat UiPath erreicht, aber das Token wurde nicht akzeptiert.

Ursache	Resolution
Das Token ist abgelaufen	Rufen Sie ein neues Token ab. Interaktive Anmeldetoken laufen nach einer Stunde ab; Ein persönliches Zugriffstoken hat ein konfigurierbares Ablaufdatum.
Das Token wurde für einen anderen Mandanten ausgestellt	Prüfen Sie, ob die Organisation und der Mandant in der Agent-URL mit denen übereinstimmen, für die das Token ausgestellt wurde.
Der Header ist falsch formatiert	Das Format ist Authorization: Bearer <your-access-token>.
Es wurde kein Token gesendet	Jede Anfrage, einschließlich der Agentkartenanfrage, muss ein Token enthalten.

Timeouts

Grenzwert	GiltFür	Was passiert?
15 Minuten	Jede einzelne Anforderung über UiPath.	Die Anforderung wird abgeschnitten. Innerhalb dieses Fensters wird eine gestreamte Antwort so lange fortgesetzt, wie beide Seiten die Verbindung offen halten.
5 Minuten	Eine Runde einer eingehenden Konversation.	Die Runde schlägt fehl. Die Aufgabe bleibt verwendbar, und die Runde kann wiederholt werden.
30 Sekunden	Die Agent-Sitzung hinter einer eingehenden Runde wird gestartet.	Wie oben.
5 Minuten	Ein ausgehender Agent, der als Tool von einem UiPath-Agent aufgerufen wird.	Der Toolaufruf schlägt fehl und der Fehlertext erreicht den UiPath Agent als Toolausgabe.

Für Arbeit, die länger dauert, als es eine einzelne Anforderung zulässt, streamen Sie die Antwort oder verwenden Sie A2A-Aufgaben: Nehmen Sie den Aufgabenbezeichner aus der ersten Antwort und rufen Sie das Ergebnis ab.

Protokoll- und Kartenversionen

Beide Richtungen wählen die A2A-Protokollversion mit dem Header A2A-Version, auch bei der Agent-Kartenanforderung. Legen Sie ihn für v1.0 auf 1.0 fest oder lassen Sie ihn für v0.3 weg (ein leerer oder leerer Wert wird genauso behandelt).

Eingehend stimmt der Wert genau überein, sodass 1.0 erkannt wird und 1.0.0 nicht. Der eingehende Endpunkt akzeptiert entweder das Transaktionsformat oder die abgerufene Karte, sodass sich der Header dort nur ändert, welche Karte Sie erhalten.

Ausgehend werden nur die Haupt- und Nebenversion gelesen, sodass 1.0 und 1.0.0 beide v1.0 auswählen. UiPath leitet eine Anforderung nur an einen Endpunkt weiter, der der angeforderten Version entspricht, sodass eine Anforderung für eine Version, die die gespeicherte Karte nicht erfüllen kann, mit 400 abgelehnt wird.

Eingehend (extern zu UiPath)

In dieser Richtung gibt es nichts zu registrieren, sodass jeder Fehler bei einem Aufruf auftritt. tasks/get gibt den aktuellen Status und Verlauf einer Konversation zurück. Was die Richtung erfordert, erfahren Sie unter Eingehend (extern zu UiPath).

Der Ordner oder Agent wurde nicht gefunden (404)

Meldung	Ursache	Resolution
Folder with key {folderKey} not found	Der Ordnerschlüssel ist falsch oder benennen einen Ordner, auf den der Aufrufer nicht zugreifen kann.	Überprüfen Sie die URL und den Ordnerzugriff des Aufrufers.
Conversational agent with release ID {agentReleaseId} not found in folder {folderId}	Unter dieser Release-ID in diesem Ordner wird kein Conversational Agent bereitgestellt.	Überprüfen Sie die Release-ID mit dem Eintrag des Agents unter Automatisierungen > Prozesse.

Ein aufgelöster Ordnerschlüssel wird für 30 Minuten zwischengespeichert. Ein Schlüssel, der nicht aufgelöst wird, wird nicht zwischengespeichert, sodass die Gewährung des Zugriffs auf einen Ordner durch einen Benutzer beim nächsten Aufruf wirksam wird. Ein Ordner, der gelöscht wurde oder dessen Zugriff zurückgezogen wurde, wird weiter aufgelöst, bis sein zwischengespeicherter Eintrag abläuft.

Nur der Endpunkt der Agent-Karte validiert die Release-ID, bevor er antwortet, also fordern Sie bei der Diagnose zuerst die Agent-Karte an. Unter message/send wird eine falsche Release-ID nicht so eindeutig gemeldet.

Der Anrufer wird vom Agent abgelehnt

Das Übergeben der Ordnersuche ist nicht mit einer Autorisierung identisch. Was der Anrufer benötigt, überprüfen Sie, was der Anrufer benötigt.

Die Konversation wird nicht fortgesetzt

Symptome	Ursache	Resolution
Eine Folgenachricht startet eine neue Konversation	contextId stimmt nicht mit einer Aufgabe von UiPath überein.	taskId neben contextId senden; eine nicht erkannte ID wird dann als Task not found gemeldet.
Task not found, für eine ID, die zuvor funktionierte	Die Aufgabe ist nach sieben Tagen Inaktivität abgelaufen, oder die Anforderung wurde an einen anderen Ordner oder eine andere Release-ID weitergeleitet.	Senden Sie die Anforderung an den Ordner und verarbeiten Sie die Aufgabe, unter der die Aufgabe erstellt wurde, oder starten Sie eine neue Aufgabe.
Cannot send a message to a task in a terminal state.	Die Aufgabe ist completed, canceled, failed oder rejected.	Neue Aufgabe starten.
Task is in a terminal state and cannot be canceled.	Die Aufgabe hat bereits einen Endstatus erreicht und tasks/cancel gilt nur für eine Aufgabe, die noch läuft.	Keine Aktion erforderlich. Die Aufgabe wurde bereits angehalten.

Anforderungen, die nicht unterstützt werden

Diese geben einen JSON-RPC-Fehler innerhalb einer erfolgreichen HTTP-Antwort zurück.

Request	Was Sie erhalten	Verwenden Sie stattdessen
tasks/resubscribe, task/subscribe	UnsupportedOperation	message/stream
tasks/list	UnsupportedOperation	Nachverfolgen von Aufgaben-IDs auf dem Client
tasks/pushNotificationConfig/*	PushNotificationNotSupported	message/stream. Die Karte gibt an pushNotifications: false
Die erweiterte Agent-Karte	ExtendedAgentCardNotConfigured	Die normale Karte

Ein negatives historyLength am tasks/get wird mit InvalidParams abgelehnt.

Ausgehend (UiPath nach extern)

Ein Aufruf in dieser Richtung wird zweimal authentifiziert: einmal vom Aufrufer an UiPath und einmal von UiPath an den Agent. Die meisten Fehler treten beim zweiten Hoppla auf. Zugehörige Aufrufe werden in Ablaufverfolgungen nach contextId gruppiert. Aktivieren Sie für das Setup die Option Ausgehend (UiPath zu extern).

Das Speichern eines Agents schlägt fehl

Symptome	Ursache	Resolution
409 Konflikt	Ein anderer Agent im Ordner verwendet diesen Namen oder diese Slug bereits.	Wählen Sie einen anderen Namen oder eine andere Slug; Beide müssen innerhalb des Ordners eindeutig sein. Die Slug kann nach der Erstellung nicht geändert werden.
Die Agent-Karte ist erforderlich	Es wurde weder eine Karten-URL noch eine Karten-JSON angegeben.	Stellen Sie eines davon bereit.
Die Agent-Karte ist nicht gültig	Die JSON ist kein Kartenobjekt oder veröffentlicht keinen JSON-RPC-Endpunkt.	Stellen Sie die Karte so bereit, wie sie vom Remote-Agent veröffentlicht wurde.
Die URL der Agent-Karte ist nicht gültig	Die URL hat kein Schema oder ist nicht über das öffentliche Internet erreichbar.	Geben Sie eine absolute URL http oder https ein oder legen Sie den Verbindungstyp auf Privat (Relay) fest.

Der Aufrufer darf den Agent (403)nicht verwenden.

Ursache	Resolution
Dem Aufrufer fehlt die Berechtigung zum Anzeigen für MCP-Server	Aktivieren Sie die Ansicht auf MCP-Servern für die zugewiesene Rolle.
Der Aufrufer ist dem Ordner nicht zugewiesen	Weisen Sie den Anrufer dem Ordner zu, der den Agent enthält.
Es ist keine Lizenz verfügbar	Aktivieren Sie Admin > Lizenzen.

Das Abrufen der Agent-Karte erfordert Zugriff auf den Ordner, jedoch nicht die Berechtigung zum Anzeigen für MCP-Server. Wenn die Karte geladen wird, aber das Senden einer Nachricht 403 zurückgibt, ist die fehlende Berechtigung auf MCP-Servern anzeigen.

Der Agent wurde nicht gefunden (404)

Ursache	Resolution
Die URL enthält den Anzeigenamen des Agents anstelle seiner Slug	Verwenden Sie die Slug, nicht den Anzeigenamen.
Der Ordnerschlüssel ist falsch	Der Agent wird in dem Ordner gesucht, der in der URL angegeben ist. Kopieren Sie die URL aus der Zeile des Agents.
Der Agent wurde gelöscht	Bestätigen Sie, dass es weiterhin in Agent Gateway > A2A Agents angezeigt wird.

Die Anforderung ist nicht zulässig (400)

Die Anforderung wurde bereits über den A2A-Proxy der Plattform übergeben, und eine auf diesem Weg eintreffende Anforderung wird abgelehnt, sodass Aufrufe keine Schleife durchführen können. Dies geschieht, wenn eine URL eines UiPath A2A-Agents als Remote-Agent registriert ist. Registrieren Sie stattdessen die eigene Adresse des Remote-Agents.

Die gespeicherte Karte fehlt oder ist veraltet

Die gespeicherte Karte wird bei späteren Aufrufen nicht mehr abgerufen, sodass eine Karte, die sich im Upstream ändert, weiterhin ihren früheren Inhalt bereitstellt. Um sie auf den neuesten Stand zu bringen, öffnen Sie den Agent, wählen Sie Bearbeiten aus und geben Sie die aktuelle Karte an. Der gleiche Bildschirm zeigt die Karte, wie der Remote-Agent sie veröffentlicht hat, bevor UiPath die angekündigten Endpunkte neu schreibt.

Zwei Fehler folgen aus einer Karte, die fehlt oder veraltet ist:

Symptome	Ursache	Resolution
404 auf der Agent-Karte, 400 auf message/send	Für den Agent ist keine Karte gespeichert, also gibt es nichts zu verwenden.	Öffnen Sie den Agent unter Agent Gateway > A2A Agents und geben Sie die Karte ein.
400, kein Endpunkt für die angeforderte A2A-Version	Es wurde kein A2A-Version -Header gesendet, aber der Agent unterstützt nur v1.0; oder 1.0 wurde gesendet und der Agent unterstützt nur v0.3; oder die Karte veröffentlicht keinen JSON-RPC-Endpunkt; oder der Remote-Agent geändert wurde und die gespeicherte Karte stimmt nicht mehr mit ihr überein.	Senden oder lassen Sie den Header weg, um dem zu entsprechen, was der Agent unterstützt, oder geben Sie die aktuelle Karte an. Remote-A2A-Agents müssen einen JSON-RPC-Endpunkt verfügbar machen; andere Schnittstellentypen werden nicht unterstützt.

502, UiPath kann den Remote-Agent nicht erreichen oder sich bei ihm authentifizieren

UiPath antwortet 502, wenn der Sprung zum Remote-Agent fehlschlägt, entweder während Sie den Agent speichern oder während er aufgerufen wird.

Beim Speichern ruft UiPath die Agent-Karte ab und der Agent wird nicht erstellt, wenn dies fehlschlägt:

Ursache	Resolution
Die URL ist von UiPath aus nicht erreichbar	Bestätigen Sie, dass die URL öffentlich aufgelöst wird, oder verwenden Sie „Private (Relay)“.
Der Agent erfordert eine Authentifizierung, die nicht konfiguriert ist	Fügen Sie den Header oder die Verbindung hinzu, die der Agent erwartet, und speichern Sie dann erneut.

Bei einem Aufruf schlägt eine Verbindung fehl, die angehängt ist, aber kein Token bereitstellen kann, da die Verbindung dann die einzige Quelle des Authorization -Headers ist. Öffnen Sie Benutzerkonfigurationen in der Zeile des Agents und überprüfen Sie den Verbindungsstatus (siehe Verbindungen pro Benutzer oder was jeder Status bedeutet). Der Status Inaktiv bedeutet, dass die Verbindung deaktiviert ist. Überprüfen Sie sie daher auf der Registerkarte „Verbindungen“ .

Wenn die Anmeldeinformationen aufgelöst werden, der Agent aber immer noch nicht erreichbar ist:

Ursache	Resolution
Der Agent befindet sich in einem privaten Netzwerk	Legen Sie den Verbindungstyp auf Privat (Relay) fest.
Die Adresse kann nicht aufgelöst werden, oder das Zertifikat wird nicht akzeptiert	Überprüfen Sie den Endpunkt, der auf der Agent-Karte veröffentlicht wurde, der oft ein anderer Host als die Karten-URL ist.
Der Agent wird nicht ausgeführt	Rufen Sie den Agent zur Bestätigung direkt an.
Der Agent ist verschoben	Die gespeicherte Karte verweist immer noch auf die alte Adresse. Geben Sie die aktuelle Karte an.

Ein Header, der auf ein Asset verweist, kann nicht aufgelöst werden

Ein Header-Wert im Format %ASSETS/AssetName% wird aufgelöst, bevor die Anforderung gesendet wird, und wenn das Asset nicht gelesen werden kann, schlägt der Aufruf fehl, ohne den ungelösten Wert zu senden.

Ursache	Resolution
Das Asset ist im Ordner des Agents nicht vorhanden	Erstellen Sie es im Orchestrator oder verweisen Sie auf ein Asset, das dies tut.
Der Aufrufer kann das Asset nicht lesen	Gewähren Sie die Berechtigung Anzeigen für Assets.
Der Asset-Typ wird nicht unterstützt	Ein Header muss in einen einzigen Wert aufgelöst werden, damit Schlüssel-Wert-Listen-Assets abgelehnt werden. Informationen zu den funktionierenden Typen finden Sie unter Referenzieren eines Orchestrator-Assets.

Der Aufruf hat eine Zeitüberschreitung von (504).

Bei einem Direktanruf hat der Remote-Agent nicht rechtzeitig geantwortet. Das Limit gilt dafür, wie lange der Agent benötigt, um zu reagieren; Sobald er gestartet wurde, kann ein Stream weit über diesen Punkt hinaus fortgesetzt werden. Verwenden Sie message/stream oder geben Sie eine Aufgabe zurück und rufen Sie das Ergebnis für einen Agent ab, der länger benötigt, um zu reagieren. Wenn eine Zeitüberschreitung auftritt, rufen Sie sie direkt auf, um zu bestätigen, dass sie erreichbar ist, und überprüfen Sie ihre eigenen Protokolle.

Die Antwort ist zu groß

Antworten eines Remote-Agents unterliegen einer Größenbeschränkung. Eine Antwort, die diese überschreitet, wird abgelehnt, und eine gestreamte Antwort, die darüber hinausgeht, wird teilweise angehalten, nachdem die aufrufende Anwendung bereits einige Ereignisse erhalten hat. Wenn ein Agent große Inhalte zurückgibt, soll er stattdessen eine Referenz wie eine URL zurückgeben.

Aufrufen eines Agents von einem UiPath-Agenten aus

Wenn ein registrierter Agent als Tool in Agent Builder oder einem Maestro-Flow angehängt wird, wird ein Fehler vom Remote-Agent als Toolausgabe mit dem Aufgabenstatus error an den UiPath-Agent zurückgegeben und die Ausführung wird fortgesetzt. Der UiPath-Agent verwendet diesen Text als Eingabe, sodass ein Fehler für das Modell wie ein gewöhnliches Toolergebnis aussieht. Um einen fehlgeschlagenen Anruf zu diagnostizieren, öffnen Sie die Ablaufverfolgung für die Ausführung und wählen Sie den Toolaufruf für den Agent aus; Die Ablaufverfolgung zeichnet die gesendete Nachricht und die zurückgegebene Antwort oder den Fehler auf.

UiPath-Agents rufen Remote-Agents mit message/send auf. Verwenden Sie dies also, wenn Sie die Funktion eines UiPath-Agents nachvollziehen. Streaming ist nur verfügbar, wenn Sie die UiPath-URL des Agents selbst aufrufen.

Auf diesem Pfad wartet die Plattform fünf Minuten auf die vollständige Antwort, und die nach und nach erzeugte Ausgabe verlängert diese Wartezeit nicht. Für einen Agent, der länger benötigt, soll er eine Aufgabe zurückgeben, die noch in Bearbeitung ist: Die Plattform behält die Aufgabe zwischen den Runden bei, sodass der UiPath-Agent sie in einer späteren Runde fortsetzen kann. Eine Aufgabe, die bereits completed, canceled, failed oder rejected erreicht hat, kann nicht fortgesetzt werden, und der nächste Aufruf startet eine neue Aufgabe innerhalb derselben Konversation.

Wenn die gespeicherte Karte weder eine v1.0-JSON-RPC-Schnittstelle noch einen verwendbaren v0.3-Endpunkt veröffentlicht, kann das Tool überhaupt nicht erstellt werden und die Ausführung meldet, dass kein kompatibler Endpunkt verfügbar ist. Öffnen Sie den Agent, wählen Sie Bearbeiten aus und bestätigen Sie, dass die Karte einen JSON-RPC-Endpunkt über http oder https verfügbar macht.

Aufrufe sind erfolgreich, verhalten sich aber unerwartet

Dies sind die Fehler, bei denen nichts fehlschlägt, also gibt es keinen Statuscode, der ausgeführt werden kann.

Symptome	Ursache	Resolution
Aufrufe verwenden die falsche Identität	Eine für den aufrufenden Benutzer konfigurierte Verbindung hat Vorrang vor der Standardverbindung des Agents.	Überprüfen Sie die Benutzerkonfigurationen für eine Verbindung, die Sie nicht erwartet haben.
Ein konfigurierter Authorization -Header scheint ignoriert zu werden	Eine Verbindung wird angehängt und die Verbindung stellt diesen Header bereit.	Erwartet. Jeder andere von Ihnen konfigurierte Header wird weiterhin gesendet.
Eine von Ihnen erwartete Verbindung fehlt in der Liste	Verbindungen werden nach der auf der Agent-Karte veröffentlichten Adresse gefiltert, die oft ein anderer Host ist als die von Ihnen registrierte Karten-URL.	Überprüfen Sie, ob die Verbindung aktiviert ist und sich in einem freigegebenen Ordner oder im persönlichen Arbeitsbereich des ausgewählten Benutzers befindet.
Ein UiPath-Agent beschreibt die Fähigkeiten des Remote-Agents falsch oder verwendet sie nicht, wenn sie erwartet wird	Die Toolbeschreibung und die Liste der Fähigkeiten stammen aus der gespeicherten Agent-Karte.	Aktualisieren Sie die gespeicherte Karte, öffnen Sie dann den UiPath-Agent und bestätigen Sie die aktualisierte Beschreibung.
Ein Anruf wird nicht mit dem Rest seiner Konversation in den Ablaufverfolgungengruppiert	Die erste Nachricht einer Konversation hat noch kein contextId.	Keine Aktion erforderlich. Spätere Nachrichten in der Konversation werden gruppiert.