受信 (UiPath 外部)

外部エージェントまたはクライアントが、Orchestrator にデプロイした会話型エージェントとの会話をどのように保持するか、およびそれらの呼び出しがどのように認証されるか。

注:

この機能はプレビュー版です。

受信 A2A とは、外部エージェントまたはクライアントが、UiPath Platform にデプロイした会話型エージェントと会話を保持することです。UiPath は呼び出しの宛先であり、他の何かの前のゲートウェイではありません。

この方向に登録するものは何もありません。フォルダーにデプロイされたすべての会話型エージェントはすでに A2A を読み上げています。Agent Gateway は、エージェント カードを提供し、A2A トラフィックをエージェントとのネイティブの会話に変換します。すべての A2A クライアントは、カードの URL と UiPath トークンのみでエージェントを使用できます。

UiPath が接続先であるため、設定する認証は 1 つのみ、UiPath に対して認証する呼び出し元のみです。アウトバウンド方向に表示されるコネクション、ヘッダー、および Orchestrator アセット参照は、ここでは対応するものがありません。

デプロイ済みの会話型エージェントを公開する

エージェント カード

デプロイ済みのすべてのエージェントには、次の場所にカードがあります。

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

{folderKey} はエージェントがデプロイされているフォルダーのキーで、 {agentReleaseId} はデプロイ済みの会話型エージェントのリリース ID です。

カードは現在のデプロイから生成されるため、その名前、説明、バージョンは常にデプロイされたものと一致します。ストリーミング、テキストとファイルの入出力、ベアラー認証をアドバタイズします。匿名検出はありません。カードを取得するにはすでに UiPath トークンが必要です。

[ オートメーション] > [プロセス] から A2A の URL をコピー> [A2A カードの URL をコピー] から A2A の URL をコピーできます。また、会話型エージェントを選択した後に、[ デプロイ済みのエージェント ] タブから A2A URL とエージェント カードの両方を調べることもできます。

エージェントを呼び出す

JSON-RPC (JSON リモート プロシージャ呼び出し) エンドポイントは、 /.well-known/agent-card.json サフィックスを含まないカードの URL です。有線では、呼び出しは次のようになります。

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

1 つの A2A タスクは、エージェントとの 1 つの会話を表します。最初のメッセージでタスクが作成され、応答には contextIdが返されます。その ID を次のメッセージに含めると、同じ会話が続行されます。各返信の後、タスクのステートは input-requiredになり、フォローアップ メッセージに対して会話を開いたままにします。

message/stream は、応答を SSE (サーバー送信イベント) ストリームとして返します。tasks/get タスクの状態と履歴を読み取り、実行中のタスクをキャンセル tasks/cancel 。プッシュ通知と tasks/resubscribe はサポートされていないため、ライブ出力には message/streamが必要です。

認証

受信 A2A の認証は 1 つ、つまり発信者が UiPath に対して認証するものです。UiPath が呼び出しの宛先であるため、セカンド ホップや上流の資格情報を設定する必要はありません。

すべての要求の Authorization ヘッダーにはベアラー トークンが含まれ、エージェント カードの要求も含まれます。匿名の検出はなく、ターン間で何も繰り越されません。会話内の各メッセージは単独で認証されます。

呼び出し元に必要なもの

トークンは、URL で指定された組織とテナントに対して有効である必要があり、URL で名前が付けられたフォルダーは、呼び出し元の ID が認識できるフォルダーである必要があります。フォルダー権限も A2A に固有のスコープもなく、アウトバウンド呼び出しに必要な MCP サーバーの表示権限と同等の権限も必要ありません。ID とフォルダーは UiPath がここでチェックする機能のすべてであり、メッセージの内容を検査するものはありません。

プラットフォーム上の他の場所で機能するトークンはすべて、対話型ログイン、外部アプリケーション、またはテスト用に最も簡単な個人用アクセス トークンです。

注:

[ Orchestrator API アクセス ] リソースを選択した状態で個人用アクセス トークンを作成します。このリソースにより、このエンドポイントがチェックする対象ユーザーが設定されるためです。タイムアウトが設定されていない場合、呼び出しがエージェントに到達する前にトークンが拒否され、エラーではトークンではなくオーディエンスに名前が付けられるため、スコープの問題とはまったく思えません。

各種類のトークンの取得方法については、「 MCP サーバーの認証」をご覧ください。

UiPath がトークンを検証してフォルダーを解決し、呼び出し元のトークンを付加した状態で会話型エージェントを実行するサービスに要求を転送します。[受信] は、呼び出し元のトークンが Agent Gateway の外を移動する 1 方向です。エージェントを実行するサービスは UiPath のサービスであるため、UiPath 内に留まります。アウトバウンド通話では、トークンは境界で取り除かれ、リモート エージェントに設定されている資格情報に置き換えられます。

カードのバージョンを選択する

エージェント カード エンドポイントのみが、任意の A2A-Version ヘッダーを読み取ります。メッセージ エンドポイントはこれを無視します。v1.0 クライアントはヘッダーを単独で送信するため、自分で設定する必要はほとんどありません。

• ストリクト v1.0 カードの送信 1.0 。
• ストリクト v0.3 カード (v1.0 を保存しない) の送信0.3フィールドと、デシリアライザーが不明なプロパティを拒否するクライアントに適しています。
• 何も送信しないか、その他の値を送信すると、v1.0 supportedInterfaces プロパティが追加された v0.3 カードが得られるため、ヘッダーを送信しなかった v1.0 クライアントでも読み取ることができます。

メッセージ エンドポイントは、ヘッダーに関係なく両方のワイヤ形式を受け入れるため、v1.0 クライアントと v0.3 クライアントは同じエージェントと通信できます。値は完全に一致するため、 1.0.0 として扱われ 1.0。また、 ヘッダーを省略しても、登録済みリモート エージェントの場合のように、ここでは厳密な v0.3 カードは提供されません。2 つの方向を比較すると、カードが異なります。

トラブルシューティング

発生する可能性が最も高いエラーとその解決方法については、「 A2A をテストおよびトラブルシューティングする」をご覧ください。その [Inbound ] セクションでは、このパスでの失敗について説明します。

反対方向の場合、UiPath が別の場所でホストされているエージェントを呼び出す場合は、「 アウトバウンド (UiPath から外部へ)」をご覧ください。