発信 (UiPath から外部へ)

UiPath の外部でホストされている A2A エージェントを Agent Gateway に登録し、そのエージェントへの呼び出しの認証を設定します。

注:

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

アウトバウンド A2A とは、UiPath の外部でホストされているエージェントを直接、または UiPath エージェント内のツールとして呼び出すプラットフォームです。Agent Gateway > A2A Agents でエージェントを一度登録すると、UiPath がその前で管理されたゲートウェイとして機能します。

ホップが 2 つあるため、2 つの独立した認証があります。呼び出し元が UiPath に対して認証し、UiPath がリモート エージェントに対して個別に認証します。どちらの側にも相手の資格情報は見られません。

その 2 番目のホップに固有のすべては、この方向にのみ適用されます。Integration Service のコネクション、設定済みヘッダー、Orchestrator アセット参照、ユーザーごとのコネクションです。

リモート A2A エージェントの登録

エージェントを登録すると、UiPath の外部でホストされている A2A エージェントをプラットフォームから呼び出せるようになります。Agent Gateway は、エージェントのカードと資格情報を保存し、安定した UiPath URL を提供します。その後、プラットフォーム上の A2A 対応コンシューマーはその URL を介してエージェントにアクセスします。

登録が完了すると、エージェントは UiPath にデプロイされた他の成果物と同様に動作します。つまり、エージェントはフォルダー内に存在し、フォルダーの権限によって誰を呼び出すことができるかが制御され、ガードレールによってメッセージをスクリーニングし、呼び出しがトレースに表示され、変更が監査されます。

登録済みの A2A エージェントは、外部クライアントも使用できます。UiPath がホストするエージェントの場合とまったく同じように、UiPath に公開されている A2A URL を UiPath トークンで呼び出します。受け入れられるトークンと必要な権限については、「 認証」をご覧ください。

前提条件

• エージェントのカード: URL (通常は /.well-known/agent-card.jsonで終わる)、またはカードを直接取得できないエージェントの場合は生のカード JSON。
• エージェントが認証に期待するもの (API キーや固定トークンなどの静的なヘッダー値、または Orchestrator で既に作成されている 接続 )
• ターゲット フォルダー内の MCP サーバーに対するフォルダーレベルの作成権限。リモート A2A エージェントは MCP サーバー権限セットを共有します。 Automation Developer、 Folder Administrator、および Personal Workspace Administrator のロールには 作成が含まれます。Automation User には 表示 機能のみがあるため、エージェントを呼び出すには十分ですが、エージェントを登録することはできません。

エージェントを登録する

1. In Agent Gateway > A2A Agents, select Add external agent.

2. [名前]、[スラッグ]、[説明] を入力します。

   注:

   スラッグはエージェントの UiPath URL の一部になり、作成後に変更することはできません。小文字、数字、ハイフンのみを使用してください。

3. エージェント カードを URL または貼り付けた JSON で指定します。

   注:

   貼り付けた JSON フィールドは、[名前] フィールドと [説明] フィールド (存在する場合) 自動的に入力されます。

4. 接続の種類を選択します。パブリック インターネット経由でアクセス可能なエージェントの場合は [標準]、プライベート ネットワーク上のエージェントの場合は [プライベート (リレー)] から選択します。詳しくは、「 プライベート ネットワーク内のエージェントにリーチする」をご覧ください。

5. 次のいずれかまたは両方を使用して、エージェントへの認証を設定します。

   • コネクション: Agent2Agent コネクタの コネクションを作成し 、ここで選択します。このオプションを選択すると、Agent Gateway は呼び出しのたびに接続から新しいベアラー トークンを取得するため、有効期限が切れた資格情報を手動でローテーションする必要はありません。
   • ヘッダー: 名前と値のペアで、すべての要求に追加されます。形式は <key>:<value>です (例: Authorization:Bearer <your-api-key>)。ヘッダーは暗号化されて保存され、読み戻されるとマスクされます。ヘッダー値でシークレットを貼り付ける代わりに、Orchestrator アセットを 形式で参照できます Authorization:%ASSETS/AssetName%。

   両方を設定した場合、コネクションは Authorization ヘッダーを提供し、他のヘッダーは引き続き適用されます。

6. 必要に応じて、[ ガードレール] を展開して設定します。詳しくは、「 ガードレール」をご覧ください。

7. [保存] を選択します。

結果: Agent Gateway は、エージェントのカードを取得してキャッシュします。エージェントが [A2A エージェント ] リストに表示されます。フェッチに失敗すると、保存はフェッチ エラーで失敗し、カードが読み取れるようになるまで何も保存されません。

外部クライアントに表示される情報

登録代理人は次の場所に住んでいます。

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

この URL は A2A エージェント のリストからコピーできます。外部クライアントは、他の A2A エージェントとまったく同じようにこのシステムを使用します。Agent Gateway は <that URL>/.well-known/agent-card.jsonでエージェントのカードを処理します。書き直されたこのため、アドバタイズされるすべてのエンドポイントがアップストリームのホストではなくゲートウェイを指し、クライアントはアップストリームのエージェントではなく UiPath に対して認証を行います。上流独自の認証スキームが漏洩することはありません。

Agent Gateway は呼び出しのたびに、呼び出し元の UiPath トークンとフォルダーへのアクセス権を検証します。これには、MCP サーバーに対する [表示] 権限が必要です。A2A は MCP サーバー権限セットを共有しているためです。次に、エージェントのガードレールに対して要求をスクリーニングし、呼び出し元の Authorization ヘッダーを削除して、設定された資格情報を挿入して、SSE (サーバー送信イベント) を含む応答をそのままストリーミングして戻します。メッセージは解析または書き換えられないため、A2A 0.3 クライアントと 1.0 クライアントの両方が機能し、クライアントは A2A-Version ヘッダーを持つバージョンを選択します。呼び出しが トレースに表示されます。

登録後

• [カードを更新] は、リモート エージェントが変更したときに (新しいエンドポイント、新しいスキル、説明の更新など) カードを再取得します。
• ユーザー設定では 、個々のユーザーが独自のコネクションをアタッチできます。相手の呼び出しでは、エージェントの既定の接続よりも優先されます。

認証

UiPath 経由で A2A エージェントを呼び出すには、2 つの別個の認証が必要であり、これらは互いに独立しています。UiPath は、要求の転送先のエージェントに対して、エージェントの登録時に一度設定された資格情報を使用して認証を行います。呼び出し元は、通常のプラットフォーム トークンを使用して UiPath に対して個別に認証します。どちらの側にも相手の資格情報は見られません。

エージェントを登録すると、次の 2 つの設定が行われます。エージェント カードは、メッセージの送信先を UiPath に指示します。資格情報を使用すると、呼び出し元のトークンが転送されないため、UiPath はすべての呼び出しでエージェントに対して認証できます。資格情報は、Integration Service のコネクション、ヘッダー、またはその両方として指定できます。

エージェント カード

エージェント カードは、A2A エージェントが自分自身を説明するために公開する JSON ドキュメントです。エージェントの名前、スキル、および JSON-RPC (JSON リモート プロシージャ コール) メッセージを受け入れるエンドポイントです。UiPath はポートなしでは通話をルーティングできないため、登録のたびにエージェントのカードがルーティングおよび認証レコードとして保持されます。

エージェントを登録するには、ターゲット フォルダー内の MCP サーバーに対する作成権限が必要です。リモート A2A エージェントは [MCP サーバー] 権限セットを共有するため、[MCP サーバー] 権限によって A2A も管理されます。

オプション 1: エージェント カードの URL を入力します

エージェントのカードの URL を入力します。通常はエージェントのベース URL の後に /.well-known/agent-card.jsonが続きます。UiPath は、同じ画面で設定された資格情報 (接続されたコネクションがある場合はその資格情報、または設定されているヘッダー (ある場合) を使用して、その瞬間にデータを取得します。これらのヘッダー内のアセット参照もこの要求で解決されるため、Orchestrator に格納された API キーの背後にあるカードを貼り付けなくても読み取ることができます。

リレーを介してエージェントに到達しない限り、要求が行われる前に、URL が SSRF (サーバー側要求フォージェリ) 保護と照合されます。UiPath がそのアドレスに到達できない場合、または応答が成功しない場合、エージェントは作成されません。これは、後で カードを更新 できる唯一のオプションです。

オプション 2: カードの JSON を貼り付ける

カードドキュメントを直接貼り付けます。UiPath は送信要求を一切行わないため、登録時に資格情報は必要ありません。また、SSRF チェックは適用されません。このオプションは、登録時に UiPath から連絡が取れないエージェント、または公衆の住所でカードが提供されないエージェントに使用します。URL と貼り付けた JSON の両方が指定されている場合は、貼り付けた JSON が使用され、フェッチは行われません。

カードが到着しても、v0.3 の url フィールドまたは v1.0 の supportedInterfaces リストを使用して、使用可能な HTTP または HTTPS の JSON-RPC エンドポイントをアドバタイズする JSON オブジェクト限り、UiPath はカードを受け入れます。カードのないカードは、呼び出し時ではなく登録時に拒否されます。

保存されたカードはすべての呼び出しで再取得されるわけではないため、アップストリームで変更されたカードは自動的に更新されません。[更新] カードは、カードを再度取得します。MCP サーバーに対する編集権限が必要で、カード URL が必要です。JSON を貼り付けて登録されたエージェントには URL がないため、更新は拒否されます。

注:

更新は、登録の方法ではなく、呼び出しの方法で認証されます。つまり、更新をトリガーするユーザーに設定された接続を使用し、エージェントの既定の接続にフォールバックします。したがって、更新は、あるユーザーでは成功し、別のユーザーでは失敗する可能性があります。

Integration Service のコネクション

エージェントにコネクションをアタッチすると、UiPath は呼び出しのたびに新しいベアラー トークンをエージェントから取得します。これは、資格情報の有効期限が切れるエージェントにとってより良いオプションです。手動でローテーションする必要はないからです。コネクションは、コネクションが属するフォルダーとともに使用されます。そのフォルダーがない場合、呼び出しは別のフォルダーまたは構成されているヘッダーにフォールバックするのではなく、失敗します。

ヘッダー

または、エージェントが予期するヘッダーを名前と値のペアとして設定します。一般的なケースは Authorization: Bearer <your-api-key>です。ヘッダーは暗号化されて保存され、読み戻すときにマスクされるため、一度貼り付けたシークレットは後で表示されません。

接続とヘッダーの優先順位

接続がアタッチされている場合は、 Authorization ヘッダーが提供され、同様に設定されている Authorization ヘッダーは単に上書きされるのではなく無視されます。設定された行はアセット参照が解決される前に削除されるため、アセットを指すヘッダーは検索されることさえありません。設定されている他のすべてのヘッダーは引き続き送信されます。登録時のカード取得にも同じ優先順位が適用されます。

ユーザーごとのコネクション

個々のユーザーは、エージェントの行のユーザー設定を使用して独自のコネクションをアタッチできます。この設定には、[コネクション] に対する編集権限が必要です。エージェントが呼び出されると、接続は次の順序で選択されます。

1. 呼び出し元のユーザーに対して構成されたコネクション。
2. エージェントの既定の接続です。
3. 接続がない。その場合、設定されているヘッダーが使用されます。または、設定されていない場合は認証は送信されません。

コネクションは、トークンが表す ID に対して選択されます。スケジュールされた実行または無人実行では、その ID はエージェントを構築したりスケジュールしたりしたユーザーではないため、他のユーザー自身のユーザーにアタッチされたコネクションは使用されません。エージェントを無人実行からアクセス可能にする必要がある場合は、ユーザー単位の接続に依存するのではなく、既定の接続を指定します。

[ユーザー設定] には、各接続の状態も表示されます。

ステータス	意味
アクティブ	接続が認可され、準備が整います。
認証が必要	このユーザーには、接続が設定されていないか、再度承認が必要なため、使用可能な接続がありません。
利用不可	共有されている既定のコネクションが見つからないか、無効化されているか、期限切れであるか、到達できませんでした。
非アクティブ	エージェントがアクティブでないか、コネクションが無効化されています。

Orchestrator アセットを参照する

ヘッダーにシークレットを貼り付ける代わりに、ヘッダーに %ASSETS/AssetName%の形式で値を設定します。UiPath は要求を送信する前にこのアセットの値に解決し、呼び出し元の ID の下にあるエージェントのフォルダーからアセットを読み取ります。アセットを読み取れない場合、未解決のプレースホルダーを転送するのではなく、呼び出しが失敗します。

Text、Secret、Bool、Integer、Credential、および Windows Credential アセットがサポートされています。Credential アセットと Windows Credential アセットはパスワードの値に解決されます。Key-Value-List アセットは拒否されます。1 つのヘッダー値は 1 つの文字列に解決する必要があるためです。解決された値は設定済みのヘッダーとしてリモート エージェントに転送されるため、アセット経由ヘッダーは、これらのシークレットを持つ信頼できるエンドポイントにのみ使用してください。

プライベート ネットワーク内のエージェントに到達する

ファイアウォールの受信ポートのないプライベート ネットワーク内で実行されるエージェントには、リレー経由でアクセスします。UiPath が要求をリレー サーバーに送信すると、ネットワーク内のリレー クライアントが要求を収集してエージェントに転送します。リレーは、UiPath がエージェントに到達する方法を変更するものであり、UiPath の認証方法を変更します。つまり、コネクション、ヘッダー、その優先順位、アセット参照はすべて、上記のとおりに動作します。SSRF チェックは、要求がパブリック アドレスに送信されないため、呼び出しまたはカード フェッチには適用されません。

登録代理人への呼び出し

2種類の発信者が登録済みリモートエージェントに到達します。UiPath エージェントや Maestro フローなどの UiPath クライアントはエージェントをツールとして使用し、プラットフォームは実行時にアドレス、トークン、プロトコル バージョンを解決します。直接 HTTP クライアントは、エージェントの URL 自体を呼び出し、3 つすべてを指定する必要があります。どちらも UiPath に対する認証方法は同じです。このセクションの残りの部分は、直接呼び出す場合にのみ重要です。

すべての要求は、 Authorization ヘッダーにベアラー トークンを持ちます。ターン間で何も繰り越されません。会話内の各メッセージは単独で認証されます。

到達しているもの	呼び出し元に必要なもの
エージェント自体	組織とテナントの有効なトークン、エージェントを含むフォルダーへのアクセス権、およびそのフォルダー内の MCP サーバーに対する表示権限。Automation User、Automation Developer、Folder Administrator、および Personal Workspace Administrator のロールにすべて含まれています。
そのエージェント カード	フォルダーにのみアクセスできます。カードは検出メタデータであるため、エージェント自体よりもアクセスしやすいように意図されています。

トークンを取得する

A2A は、プラットフォームの他の部分と同じトークンを使用します。

メソッド	トークンのソース	使用すべきタイミング
個人用アクセス トークン (PAT)	[ユーザー基本設定] の [UiPath Cloud]	最も簡単なテスト オプションです。有効期限は設定可能で、任意の HTTP クライアントで動作します。
対話型ログイン	uipath auth	ローカル開発。トークンは約 1 時間続き、自動的には更新されません。
外部アプリケーション	管理 > 外部Apps、クライアント資格情報	CI/CD (継続的インテグレーション/継続的デリバリー) パイプラインやサービス アカウントなど、サインインするために誰も存在しない無人の発信者。

それぞれの作成方法については、「 MCP サーバーの認証」をご覧ください。A2A エージェントと MCP サーバーは同じパイプラインで検証されるため、MCP サーバーで機能するトークンは A2A エージェントでも機能します。1 つの例外は MCP OAuth フローです。OAuth フローは MCP エンドポイントのみでサポートされます。これは、A2A エージェントがパブリッシュしない検出メタデータに依存しているためです。

エージェントの URL を取得する

登録済みリモートエージェントは、以下に存在します。

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

エージェント カードは同じ住所にあり、その後に /.well-known/agent-card.jsonが付いています。エージェントを手作業で組み立てるのではなく、エージェントの行の [URL をコピー] を選択して、Agent Gateway> A2A エージェントから URL を取得します。フォルダー キーはフォルダー名ではなく GUID (グローバル一意な識別子) であり、スラッグは表示名ではありません。

プロトコル バージョンの選択

リモート A2A エージェントは、要求ヘッダーを A2A-Version で選択した A2A v0.3 および v1.0 をサポートします。

• v1.0 の場合は、ヘッダー値を 1.0に設定します。
• v0.3 の場合は、ヘッダーを省略します。空の値または空白の値は、同じように扱われます。

エージェント カードを要求する際にも同じヘッダーが適用され、UiPath が返すカードのバージョンを決定します。UiPath は、要求されたバージョンに一致するエンドポイントにのみ要求を転送します。別のバージョンにフォールバックすることはありません。別のバージョンにフォールバックすると、リモート エージェントが理解できないワイヤ形式のメッセージが送信されるためです。保存されているエージェント カードでそのバージョンの JSON-RPC エンドポイントがパブリッシュされていない場合、要求は拒否され、応答でそのバージョンに名前が付けられます。

決して境界を越えないもの

境界で3つのものが止まっています。

• 呼び出し元のトークンがリモート エージェントに到達することはありません。UiPath が認証を検証して削除し、エージェントに設定された資格情報を挿入します。リモート エージェントには、UiPath 経由で誰が呼び出されたかを学習したり、その ID を再利用したりする方法はありません。また、UiPath は独自の内部ヘッダーを削除し、独自の単一の送信トレース ヘッダーを挿入します。
• リモート エージェントの認証スキームは、呼び出し元にアドバタイズされません。UiPath が提供するエージェント カードは、アップストリームでパブリッシュされたものに関係なく、常に UiPath 独自のベアラー認証を宣言します。また、カードを書き換えると元のカードに付けられた署名はすべて削除されます。このカードをリモート エージェントがパブリッシュしたとおりに表示するには、エージェントを開いて [ 編集] を選択します。
• 呼び出しはプラットフォームを介してループ バックできません。エージェントの登録時に、UiPath を指しているエージェント カードの URL は拒否されます。それを超えると、プロキシされたすべての要求にはマーカーが保持され、すでにマーカーが保持されている要求は拒否されます。

トラブルシューティング

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

デプロイしたエージェントを外部クライアントが呼び出す逆方向については、[ 受信 (UiPath の外部)] をご覧ください。