Eingehend (extern zu UiPath)

Wie ein externer Agent oder Client eine Konversation mit einem Conversational Agent führt, den Sie in Orchestrator bereitgestellt haben, und wie diese Aufrufe authentifiziert werden.

Hinweis:

Diese Funktion befindet sich in der Vorschau.

Eingehender A2A ist ein externer Agent oder Client, der eine Konversation mit einem Konversationsagenten führt, den Sie auf der UiPath-Plattform bereitgestellt haben. UiPath ist das Ziel des Aufrufs und kein Gateway vor etwas anderem.

Für diese Richtung ist nichts zu registrieren. Jeder Conversational Agent, der in einem Ordner bereitgestellt wird, spricht bereits A2A: Agent Gateway bedient seine Agent-Karte und übersetzt A2A-Datenverkehr in eine native Konversation mit dem Agent. Jeder A2A-Client kann den Agent nur mit der Karten-URL und einem UiPath-Token verwenden.

Da UiPath das Ziel ist, gibt es nur eine Authentifizierung zu konfigurieren: den Aufrufer, der sich bei UiPath authentifiziert. Die Verbindungen, Header und Orchestrator-Asset-Referenzen, die in ausgehender Richtung angezeigt werden, haben hier kein Gegenstück.

Bereitstellen von bereitgestellten Conversational Agents

Die Agent-Karte

Jeder bereitgestellte Agent hat eine Karte unter:

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

{folderKey} ist der Schlüssel des Ordners, in dem der Agent bereitgestellt wird, und {agentReleaseId} ist die Version-ID des bereitgestellten Agents.

Die Karte wird aus der aktuellen Bereitstellung generiert, sodass ihr Name, ihre Beschreibung und Version immer mit der bereitgestellten Version übereinstimmen. Es kündigt Streaming, Text- und Dateieingabe/-ausgabe sowie Bearer-Authentifizierung an. Es gibt keine anonyme Erkennung: Das Abrufen der Karte erfordert bereits ein UiPath-Token.

Sie können die A2A-URL über Automatisierungen > Prozesse > A2A-Karten-URL kopieren kopieren. Sie können auch sowohl die A2A-URL als auch die Agent-Karte auf der Registerkarte Bereitgestellte Agents überprüfen, nachdem Sie den Conversational Agent ausgewählt haben.

Anruf des Agenten

Der JSON-RPC-Endpunkt (JSON Remote Prozedur Call) ist die Karten-URL ohne das Suffix /.well-known/agent-card.json. Auf der Wire sieht ein Aufruf so aus:

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

Eine A2A-Aufgabe stellt eine Konversation mit dem Agent dar. Die erste Nachricht erstellt die Aufgabe und die Antwort enthält contextId; Einschließen dieser ID in der nächsten Nachricht setzt dieselbe Konversation fort. Nach jeder Antwort ist der Aufgabenstatus input-required, sodass die Konversation für Folgenachrichten offen bleibt.

message/stream gibt die Antwort als SSE-Stream (Server-Sent Events) zurück. tasks/get liest den Status und Verlauf einer Aufgabe und tasks/cancel bricht eine laufende Aufgabe ab. Push-Benachrichtigungen und tasks/resubscribe werden nicht unterstützt, daher ist für die Live-Ausgabe message/stream erforderlich.

Authentication

Eingehende A2A hat eine einzige Authentifizierung: Der Aufrufer authentifiziert sich bei UiPath. UiPath ist das Ziel des Aufrufs, daher gibt es keinen zweiten Hop und keine vorgelagerten Anmeldeinformationen zu konfigurieren.

Jede Anfrage hat ein Bearer-Token im Header Authorization, einschließlich der Anfrage für die Agent-Karte. Es gibt keine anonyme Erkennung und es wird nichts zwischen den Runden übertragen: Jede Nachricht in einer Konversation wird für sich selbst authentifiziert.

Was der Anrufer benötigt

Das Token muss für die Organisation und den Mandanten, die in der URL benannt sind, gültig sein, und der Ordner, der in der URL benannt ist, muss einer sein, den die aufrufende Identität sehen kann. Es ist nichts weiter erforderlich: keine Ordnerberechtigung, kein A2A-spezifischer Scope und kein Äquivalent der Anzeige- Berechtigung für MCP-Server , die ein ausgehender Aufruf benötigt. Identität und Ordner sind das Ganze, was UiPath hier überprüft, und nichts überprüft den Inhalt einer Nachricht.

Jedes Token, das an anderer Stelle auf der Plattform funktioniert, funktioniert hier: interaktive Anmeldung, externe Anwendungen oder ein persönliches Zugriffstoken, das für das Testen am einfachsten ist.

Hinweis:

Erstellen Sie ein persönliches Zugriffstoken mit der ausgewählten Ressource Orchestrator-API-Zugriff , da diese Ressource die Zielgruppe festlegt, die dieser Endpunkt überprüft. Ohne diese wird das Token abgelehnt, bevor der Anruf den Agent erreicht, und der Fehler benennt die Zielgruppe anstelle des Tokens, sodass es überhaupt nicht nach einem Scope-Problem aussieht.

Informationen zum Abrufen der einzelnen Tokentypen finden Sie unter MCP-Serverauthentifizierung.

UiPath validiert das Token, löst den Ordner auf und leitet die Anforderung an den Dienst weiter, der den Conversational Agent ausführt, wobei das Token des Aufrufers angehängt ist. Eingehend ist die einzige Richtung, in die das Token des Anrufers über das Agent-Gateway hinaus bewegt wird. Er bleibt innerhalb von UiPath, da der Dienst, der den Agent ausführt, ein UiPath-Dienst ist. Bei einem ausgehenden Aufruf wird das Token an der Grenze entfernt und durch die für den Remote-Agent konfigurierten Anmeldeinformationen ersetzt.

Auswählen der Kartenversion

Nur der Endpunkt der Agent-Karte liest den optionalen A2A-Version -Header; der Nachrichtenendpunkt ignoriert dies. Ein v1.0-Client sendet den Header selbst, sodass Sie ihn nur selten selbst festlegen müssen.

• Senden Sie 1.0 für die strikte v1.0-Karte.
• Senden Sie 0.3 für die strikte v0.3-Karte, die keine v1.0 enthält Felder und entspricht einem Client, dessen Deserialisierung unbekannte Eigenschaften abgelehnt.
• Senden Sie nichts oder einen anderen Wert, und Sie erhalten eine v0.3-Karte mit der v1.0-Eigenschaft supportedInterfaces hinzugefügt, sodass ein v1.0-Client, der den Header nicht gesendet hat, ihn trotzdem lesen kann.

Der Nachrichtenendpunkt akzeptiert beide Formate unabhängig vom Header, sodass ein v1.0- und ein v0.3-Client mit demselben Agent kommunizieren können. Der Wert stimmt exakt überein, sodass 1.0.0 nicht als 1.0 behandelt wird. Und wenn Sie den Header weglassen, erhalten Sie hier nicht die strikte v0.3-Karte, wie dies bei einem registrierten Remote-Agent der Fall ist. Wenn Sie die beiden Richtungen vergleichen, unterscheiden sich ihre Karten deshalb.

Fehlersuche und ‑behebung

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

Für die umgekehrte Richtung, in der UiPath einen anderswo gehosteten Agent aufruft, aktivieren Sie Outbound (UiPath to extern).