Ausgehend (UiPath nach extern)

Registrieren Sie einen A2A-Agent, der außerhalb von UiPath gehostet wird, im Agent Gateway und konfigurieren Sie die Authentifizierung für Aufrufe an ihn.

Hinweis:

Diese Funktion befindet sich in der Vorschau.

Outbound A2A ist die Plattform, die einen Agent aufruft, der außerhalb von UiPath gehostet wird, entweder direkt oder als Tool innerhalb eines UiPath-Agents. Sie registrieren den Agent einmal in Agent Gateway > A2A Agents und UiPath fungiert als gesteuertes Gateway vor ihm.

Da es zwei Abschnitte gibt, gibt es zwei unabhängige Authentifizierungen: Der Aufrufer authentifiziert sich bei UiPath und UiPath authentifiziert sich separat beim Remote-Agent. Keine Seite sieht die Anmeldeinformationen der anderen.

Alles, was für diesen zweiten Sprung spezifisch ist, gilt nur für diese Richtung: Integration Service-Verbindungen, konfigurierte Header, Orchestrator-Asset-Referenzen und Verbindungen pro Benutzer.

Registrieren Sie einen Remote-A2A-Agent

Durch die Registrierung eines Agents wird ein A2A-Agent, der außerhalb von UiPath gehostet wird, von der Plattform aufrufbar. Agent Gateway speichert die Karte und die Anmeldeinformationen des Agents, gibt ihm eine stabile UiPath-URL und von da an erreicht jeder A2A-fähige Verbraucher auf der Plattform den Agent über diese URL.

Nach der Registrierung verhält sich der Agent wie jedes andere bereitgestellte Artefakt in UiPath: Er befindet sich in einem Ordner, Ordnerberechtigungen regeln, wer ihn aufrufen kann, Guardrails können seine Nachrichten überprüfen, Aufrufe werden in Traces angezeigt und Änderungen daran werden geprüft.

Ein registrierter A2A-Agent kann auch von externen Clients genutzt werden. Sie rufen die von UiPath exponierte A2A-URL mit einem UiPath-Token auf, genau wie bei einem von UiPath gehosteten Agenten. Die akzeptierten Token und die erforderlichen Berechtigungen finden Sie unter Authentifizierung.

Voraussetzungen

• Die Karte des Agents: entweder die URL, die normalerweise auf /.well-known/agent-card.json endet, oder die unformatierte Karten-JSON für Agents, deren Karte nicht direkt abgerufen werden kann.
• Was auch immer der Agent für die Authentifizierung erwartet: statische Header-Werte, wie z. B. ein API-Schlüssel oder ein festes Token oder eine bereits im Orchestrator erstellte Verbindung .
• Die Ordnerberechtigung Erstellen für MCP-Server im Zielordner. Remote-A2A-Agents teilen sich den Berechtigungssatz MCP-Server und zu den Rollen Automation Developer, Folder Administrator und Personal Workspace Administrator gehört Create. Automation User hat nur Ansicht , was ausreicht, um einen Agent aufzurufen, aber nicht, um einen zu registrieren.

Registrieren Sie den Agent

1. Wählen Sie unter Agent Gateway > A2A Agents die Option Externen Agent hinzufügen aus.

2. Geben Sie einen Namen, eine Slug und eine Beschreibung ein.

   Hinweis:

   Die Slug wird Teil der UiPath-URL des Agents und kann nach der Erstellung nicht geändert werden. Verwenden Sie nur Kleinbuchstaben, Ziffern und Bindestriche.

3. Geben Sie die Agent-Karte entweder als URL oder als eingefügte JSON an.

   Hinweis:

   Das eingefügte JSON füllt automatisch die Felder Name und Beschreibung aus, falls vorhanden.

4. Wählen Sie den Verbindungstyp aus: Standard für einen Agent, der über das öffentliche Internet erreichbar ist, oder Privat (Relay) für einen Agent in einem privaten Netzwerk. Weitere Informationen finden Sie unter Erreichen eines Agents innerhalb eines privaten Netzwerks.

5. Konfigurieren Sie die Authentifizierung beim Agent mithilfe einer oder beider der folgenden Optionen:

   • Verbindung: Erstellen Sie eine Verbindung für den Agent2Agent-Connector und wählen Sie ihn dann hier aus. Einmal ausgewählt, ruft das Agent Gateway bei jedem Aufruf ein neues Bearer-Token von der Verbindung ab, sodass ablaufende Anmeldeinformationen nicht von Hand rotiert werden müssen.
   • Header: Name- und Wertpaare, die jeder Anforderung hinzugefügt werden, im Format <key>:<value>, z. B. Authorization:Bearer <your-api-key>. Header werden verschlüsselt und beim Zurücklesen maskiert gespeichert. Anstatt ein Geheimnis einzufügen, kann ein Header-Wert auf ein Orchestrator-Asset in Form von Authorization:%ASSETS/AssetName% verweisen.

   Wenn beide festgelegt sind, stellt die Verbindung den Authorization -Header bereit und die anderen Header gelten weiterhin.

6. Erweitern Sie optional die Guardrails und konfigurieren Sie sie. Weitere Informationen finden Sie unter Guardrails.

7. Wählen Sie Speichern.

Ergebnis: Agent Gateway ruft die Karte des Agents ab und speichert sie zwischen. Der Agent wird in der Liste A2A-Agents angezeigt. Wenn der Abruf fehlschlägt, schlägt das Speichern mit dem Abruffehler fehl und es wird nichts gespeichert, bis die Karte lesbar ist.

Das sehen externe Clients

Der registrierte Agent verwaltet sich unter:

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

Sie können diese URL aus der Liste der A2A-Agents kopieren. Ein externer Client verwendet es genau wie jeden A2A-Agent: Das Agent-Gateway stellt die Karte des Agents unter <that URL>/.well-known/agent-card.json bereit, die so umgeschrieben wurde, dass jeder angekündigte Endpunkt auf das Gateway statt auf den Upstream-Host verweist und sich der Client bei UiPath und nicht beim Host authentifiziert Upstream-Agent. Das eigene Authentifizierungsschema des Upstreams wird nie offengelegt.

Bei jedem Aufruf überprüft das Agent Gateway das UiPath-Token und den Ordnerzugriff des Aufrufers, was die Berechtigung zum Anzeigen auf MCP-Servern erfordert, da A2A den Berechtigungssatz für MCP-Server freigibt. Es überprüft dann die Anforderung anhand der Leitplanken des Agents, entfernt den Authorization -Header des Aufrufers, fügt die konfigurierten Anmeldeinformationen ein und streamt die Antwort unverändert, einschließlich SSE (Server-Sent Events). Nachrichten werden nicht geparst oder umgeschrieben, sodass sowohl A2A 0.3- als auch 1.0-Clients funktionieren und ein Client eine Version mit dem A2A-Version -Header auswählt. Aufrufe werden in Ablaufverfolgungen angezeigt.

Nach der Registrierung

• Die Karte aktualisieren ruft die Karte erneut ab, wenn sich der Remote-Agent ändert, z. B. ein neuer Endpunkt, neue Fähigkeiten oder eine aktualisierte Beschreibung.
• Mit den Benutzerkonfigurationen können einzelne Benutzer ihre eigene Verbindung anhängen. Für ihre Anrufe hat sie Vorrang vor der Standardverbindung des Agents.

Authentication

Das Aufrufen eines A2A-Agents über UiPath umfasst zwei separate Authentifizierungen, die unabhängig voneinander sind. UiPath authentifiziert sich bei dem Agent, an den es die Anfrage weiterleitet, mithilfe von Anmeldeinformationen, die einmal bei der Registrierung des Agent konfiguriert werden. Der Aufrufer authentifiziert sich separat bei UiPath mit einem gewöhnlichen Plattformtoken. Keine Seite sieht die Anmeldeinformationen der anderen.

Beim Registrieren eines Agents werden zwei Dinge konfiguriert. Die Agent-Karte teilt UiPath mit, wohin Nachrichten gesendet werden sollen. Anmeldeinformationen ermöglichen es UiPath, sich bei jedem Anruf beim Agent zu authentifizieren, da das Token des Aufrufers nie weitergeleitet wird. Anmeldeinformationen können als Integration Service-Verbindung, als Header oder als beides bereitgestellt werden.

Die Agent-Karte

Eine Agent-Karte ist das JSON-Dokument, das ein A2A-Agent veröffentlicht, um sich selbst zu beschreiben: seinen Namen, seine Fähigkeiten und den Endpunkt, der JSON-RPC-Nachrichten (JSON Remote Prozedur Call) akzeptiert. UiPath kann einen Anruf ohne eine Karte nicht weiterleiten, deshalb behält jede Registrierung die Karte des Agents als Routing- und Authentifizierungsdatensatz bei.

Das Registrieren eines Agents erfordert die Berechtigung zum Erstellen für MCP-Server im Zielordner. Remote-A2A-Agents teilen sich den Berechtigungssatz für MCP-Server, sodass die Berechtigungen für MCP-Server auch für A2A gelten.

Option 1: Geben Sie die URL zur Agent-Karte an

Geben Sie die URL der Karte des Agents ein, normalerweise die Basis-URL des Agents, gefolgt von /.well-known/agent-card.json. UiPath ruft sie in diesem Moment mithilfe der auf demselben Bildschirm konfigurierten Anmeldeinformationen ab: die angehängte Verbindung, falls eine vorhanden ist, oder die konfigurierten Header, wenn dies nicht der Fall ist. Asset-Verweise in diesen Headern werden auch für diese Anforderung aufgelöst, sodass eine Karte hinter einem im Orchestrator gespeicherten API-Schlüssel gelesen werden kann, ohne den Schlüssel einzufügen.

Die URL wird gegen den SSRF-Schutz (Server-Side Request Forgery) überprüft, bevor die Anforderung gestellt wird, es sei denn, der Agent wird über das Relay erreicht. Wenn UiPath die Adresse nicht erreichen kann oder die Antwort kein Erfolg ist, wird der Agent nicht erstellt. Dies ist die einzige Option, die die spätere Aktualisierung der Karte unterstützt.

Option 2: Fügen Sie das Karten-JSON ein

Fügen Sie das Kartendokument direkt ein. UiPath stellt überhaupt keine ausgehende Anforderung, sodass zum Zeitpunkt der Registrierung keine Anmeldeinformationen erforderlich sind und die SSRF-Prüfung nicht durchgeführt wird. Verwenden Sie diese Option für einen Agent, der zum Zeitpunkt der Registrierung von UiPath aus nicht erreichbar ist oder dessen Karte nicht an einer öffentlichen Adresse bereitgestellt wird. Wenn sowohl eine URL als auch eine eingefügte JSON angegeben sind, wird die eingefügte JSON verwendet und es erfolgt kein Abruf.

Die Karte kommt jedoch an, UiPath akzeptiert sie nur, wenn es sich um ein JSON-Objekt handelt, das einen verwendbaren HTTP- oder HTTPS JSON-RPC-Endpunkt über das url Feld v0.3 oder die supportedInterfaces Liste v1.0 angibt. Eine Karte ohne Karte wird bei der Registrierung und nicht während des Anrufs abgelehnt.

Die gespeicherte Karte wird nicht bei jedem Aufruf erneut abgerufen, sodass eine Karte, die sich im Upstream ändert, nicht von selbst aktualisiert wird. Die Aktualisierungskarte ruft sie erneut ab, erfordert die Bearbeitungsberechtigung auf MCP-Servern und erfordert eine Karten-URL: Ein Agent, der durch Einfügen von JSON registriert ist, hat keine und die Aktualisierung wird abgelehnt.

Hinweis:

Eine Aktualisierung wird auf die gleiche Weise wie ein Anruf authentifiziert, nicht wie die Registrierung: Sie verwendet die Verbindung, die für den Benutzer konfiguriert ist, der sie auslöst, und greift auf die Standardverbindung des Agents zurück. Eine Aktualisierung kann daher für einen Benutzer erfolgreich sein und für einen anderen fehlschlagen.

Eine Integration Service-Verbindung

Das Anhängen einer Verbindung an den Agent bedeutet, dass UiPath bei jedem Aufruf ein neues Bearer-Token von ihm abruft. Dies ist die bessere Option für jeden Agent, dessen Anmeldeinformationen ablaufen, da nichts von Hand rotiert werden muss. Die Verbindung wird zusammen mit dem Ordner verwendet, zu dem sie gehört; Wenn dieser Ordner fehlt, schlägt der Aufruf fehl, anstatt auf einen anderen Ordner oder einen konfigurierten Header zuzugreifen.

Header

Alternativ können Sie die Header konfigurieren, die der Agent als Namens- und Wertpaare erwartet. Der gängigste Fall ist Authorization: Bearer <your-api-key>. Header werden verschlüsselt und beim Zurücklesen maskiert gespeichert, sodass ein einmal eingefügtes Geheimnis später nicht mehr sichtbar ist.

Verbindungs- und Header-Priorität

Wenn eine Verbindung angehängt ist, wird der Authorization -Header bereitgestellt und jeder konfigurierte Authorization -Header wird ignoriert und nicht nur überschrieben: Die konfigurierte Zeile wird entfernt, bevor Asset-Referenzen aufgelöst werden. Ein Header, der auf ein Asset verweist, wird also nicht nicht einmal gesucht. Jeder andere konfigurierte Header wird weiterhin gesendet. Der gleiche Status gilt für den Kartenabruf zum Zeitpunkt der Registrierung.

Verbindungen pro Benutzer

Einzelne Benutzer können eine eigene Verbindung über Benutzerkonfigurationen in der Zeile des Agents anhängen, was die Berechtigung zum Bearbeiten für Verbindungen erfordert. Wenn der Agent aufgerufen wird, wird die Verbindung in dieser Reihenfolge ausgewählt:

1. Die Verbindung, die für den aufrufenden Benutzer konfiguriert ist.
2. Die Standardverbindung des Agents.
3. Keine Verbindung, in diesem Fall werden die konfigurierten Header verwendet, oder es wird keine Authentifizierung gesendet, wenn keine konfiguriert ist.

Die Verbindung wird für jede Identität ausgewählt, die das Token darstellt. Bei einer geplanten oder unbeaufsichtigten Ausführung ist diese Identität nicht die Person, die den Agent erstellt oder geplant hat, sodass eine Verbindung, die unter einem eigenen Benutzer angehängt ist, dort nicht verwendet wird. Wenn ein Agent über Unattended-Ausführungen erreichbar sein muss, geben Sie ihm eine Standardverbindung, anstatt sich auf Verbindungen pro Benutzer zu verlassen.

Die Benutzerkonfigurationen zeigen auch den Status jeder Verbindung an:

Status	Bedeutung
Aktiv	Die Verbindung ist autorisiert und bereit.
Authentifizierung erforderlich	Für diesen Benutzer ist keine funktionierende Verbindung verfügbar – entweder, weil keine konfiguriert ist oder weil seine erneute Autorisierung benötigt.
Nicht verfügbar	Die freigegebene Standardverbindung fehlt, ist deaktiviert, abgelaufen oder konnte nicht erreicht werden.
Inaktiv	Der Agent ist nicht aktiv, oder die Verbindung ist deaktiviert.

Verweisen auf ein Orchestrator-Asset

Anstatt ein Geheimnis in einen Header einzufügen, geben Sie dem Header einen Wert im Formular %ASSETS/AssetName%. UiPath löst es auf den Wert des Assets auf, bevor die Anforderung gesendet wird, wobei das Asset aus dem Ordner des Agents unter der aufrufenden Identität gelesen wird. Wenn das Asset nicht gelesen werden kann, schlägt der Aufruf fehl, anstatt den ungelösten Platzhalter weiterzuleiten.

Text-, Geheimnis-, Bool-, Integer-, Anmeldeinformations- und Windows-Anmeldeinformations-Assets werden unterstützt; Anmeldedaten und Windows-Anmeldedaten werden in den Kennwortwert aufgelöst. Schlüsselwertlisten-Assets werden abgelehnt, da ein Headerwert in eine Zeichenfolge aufgelöst werden muss. Der aufgelöste Wert wird als konfigurierter Header an den Remote-Agent weitergeleitet. Verwenden Sie daher Asset-gestützte Header nur für Endpunkte, denen Sie diese Geheimnisse anvertrauen.

Erreichen eines Agents innerhalb eines privaten Netzwerks

Ein Agent, der in einem privaten Netzwerk ohne eingehende Firewall-Ports ausgeführt wird, wird über Relay erreicht: UiPath sendet die Anforderung an einen Relay-Server und ein Relay-Client innerhalb des Netzwerks sammelt sie und leitet sie an den Agent weiter. Das Relay ändert, wie UiPath den Agent erreicht, nicht wie es sich bei ihm authentifiziert: Die Verbindung, die Header, deren Rang und Asset-Referenzen verhalten sich alle genau wie oben beschrieben. Die SSRF-Prüfung gilt nicht für den Anruf oder den Kartenabruf, da die Anforderung nicht an eine öffentliche Adresse gesendet wird.

Ein registrierter Agent wird aufgerufen

Zwei Arten von Anrufern erreichen einen registrierten Remote-Agent. Ein UiPath-Client wie ein UiPath-Agent oder ein Maestro-Flow verwendet den Agent als Tool und die Plattform löst die Adresse, das Token und die Protokollversion zur Runtime auf. Ein direkter HTTP-Client ruft die URL des Agents selbst auf und muss alle drei bereitstellen. Beide authentifizieren sich bei UiPath auf die gleiche Weise; Der Rest dieses Abschnitts ist nur wichtig, wenn Sie direkt aufrufen.

Jede Anforderung hat ein Bearer-Token im Authorization -Header. Zwischen den Runden wird nichts übertragen: Jede Nachricht in einer Konversation wird für sich selbst authentifiziert.

Was Sie erreichen	Was der Anrufer benötigt
Der Agent selbst	Ein gültiges Token für die Organisation und den Mandanten, Zugriff auf den Ordner, der den Agent enthält, und die Berechtigung zum Anzeigen für MCP-Server in diesem Ordner. Die Rollen Automation User, Automation Developer, Folder Administrator und Personal Workspace Administrator enthalten es alle.
Die Agent-Karte	Nur Ordnerzugriff. Die Karte enthält Erkennungsmetadaten und ist daher absichtlich einfacher zu erreichen als der Agent selbst.

Ein Token wird abgerufen

A2A verwendet die gleichen Token wie der Rest der Plattform.

Method	Tokenquelle	Verwendungszweck
Persönliches Zugriffstoken (PAT)	UiPath Cloud, unter Ihren Benutzereinstellungen	Die einfachste Option zum Testen. Das Ablaufdatum ist konfigurierbar und es funktioniert mit jedem HTTP-Client.
Interaktive Anmeldung	uipath auth	Lokale Entwicklung. Das Token dauert etwa eine Stunde und wird nicht automatisch aktualisiert.
Externe Anwendung	Administrator > Externe Apps, Client-Anmeldeinformationen	Unattended-Aufrufe, wie z. B. CI/CD-Pipelines (Continuous Integration/Continuous Delivery) und Dienstkonten, bei denen jemand zum Anmelden vorhanden ist.

Informationen zum Erstellen jeder einzelnen davon finden Sie unter MCP-Serverauthentifizierung. A2A-Agents und MCP-Server werden von derselben Pipeline validiert, sodass jedes Token, das für einen MCP-Server funktioniert, auch für einen A2A-Agenten funktioniert. Die einzige Ausnahme ist der MCP OAuth-Flow, den nur MCP-Endpunkte unterstützen, da er von Erkennungsmetadaten abhängt, die A2A-Agents nicht veröffentlichen.

Abrufen der Agent-URL

Ein registrierter Remote-Agent befindet sich unter:

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

Die Agent-Karte befindet sich unter derselben Adresse, gefolgt von /.well-known/agent-card.json. Rufen Sie die URL von Agent Gateway > A2A Agents ab, indem Sie in der Zeile des Agents URL kopieren auswählen, anstatt sie manuell zusammenzustellen: Der Ordnerschlüssel ist eine GUID (Globally Unique Identifier) und kein Ordnername, und die Slug ist nicht die Anzeige Namen.

Auswählen der Protokollversion

Remote-A2A-Agents unterstützen A2A v0.3 und v1.0, ausgewählt mit dem Anforderungsheader A2A-Version:

• Legen Sie für v1.0 den Header-Wert auf 1.0 fest.
• Lassen Sie bei v0.3 den Header weg. Ein leerer oder leerer Wert wird genauso behandelt.

Der gleiche Header gilt, wenn die Agent-Karte angefordert wird, und bestimmt, welche Version der Karte UiPath zurückgibt. UiPath leitet eine Anforderung nur an einen Endpunkt weiter, der der angeforderten Version entspricht; er nicht auf eine andere Version zurückgreift, da diese dem Remote-Agent eine Nachricht in einem Name senden würde, den er nicht versteht. Wenn die gespeicherte Agent-Karte keinen JSON-RPC-Endpunkt für diese Version veröffentlicht, wird die Anforderung abgelehnt und die Version wird in der Antwort benannt.

Was nie die Grenze überschreitet

An der Grenze werden drei Dinge angehalten:

• Das Token des Aufrufers erreicht nie den Remote-Agent. UiPath validiert sie, entfernt sie und fügt die für den Agent konfigurierten Anmeldeinformationen ein. Der Remote-Agent hat keine Möglichkeit, zu erfahren, wer ihn über UiPath aufgerufen hat, oder diese Identität wiederzuverwenden. UiPath entfernt auch seine eigenen internen Header und fügt einen einzigen ausgehenden Trace-Header ein.
• Das Authentifizierungsschema des Remote-Agents wird Aufrufern nie angegeben. Die Agent-Karte, die UiPath dient, deklariert immer die eigene Bearer-Authentifizierung von UiPath, unabhängig davon, ob der Upstream veröffentlicht wurde, und jede Signatur auf der ursprünglichen Karte wird entfernt, da das Neuschreiben der Karte diese ungültig macht. Um die Karte so anzuzeigen, wie der Remote-Agent sie veröffentlicht hat, öffnen Sie den Agent und wählen Sie Bearbeiten aus.
• Ein Aufruf kann nicht über die Plattform zurückgeführt werden. Eine Agentkarten-URL, die auf UiPath zurückgreift, wird bei der Registrierung des Agents abgelehnt. Darüber hinaus enthält jede Proxy-Anforderung einen Marker, und eine Anforderung, die ihn bereits enthält, wird abgelehnt.

Fehlersuche und ‑behebung

Informationen zu den Fehlern, die am wahrscheinlichsten auftreten, und deren Behebung finden Sie unter Testen und Fehlerbehebung bei A2A. Der Abschnitt „Ausgehend“ behandelt die Fehler auf diesem Pfad.

Für die umgekehrte Richtung, in der ein externer Client einen von Ihnen bereitgestellten Agent aufruft, aktivieren Sie Eingehend (außerhalb von UiPath).