A2A のテストとトラブルシューティング

Orchestrator で A2A の受信または発信をテストする際に発生する一般的なエラー (認証の失敗、エージェントの欠落、タイムアウトなど) の解決策です。

注:

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

A2A エージェントを UiPath エージェントまたは外部クライアントから使用する前に、直接呼び出しでテストします。エージェントを自分で呼び出すと、未加工の要求と応答が表示され、問題がエージェントにあるのか、認証にあるのか、呼び出し元のアプリケーションにあるのかがわかります。

受信呼び出しと送信呼び出しはそれぞれ異なる理由で失敗するため、このページでは、まず両方向に適用される内容を説明し、次に方向ごとに分割します。呼び出している URL により、どの半分が自分のものかが識別されます。

• .../agenthub_/a2a/{folderKey}/{agentReleaseId} が 受信の場合: 外部クライアントが、プラットフォームにデプロイされている会話型エージェントを呼び出しています。
• .../agenthub_/a2a/remote/{folderKey}/{slug} が アウトバウンドです: UiPath は、発信者に代わって他の場所でホストされているエージェントに電話をかけています。

直接通話を使用してエージェントをテストする

ここで挙げる例では cURL を使用していますが、Postman、A2A Python または .NET SDK (ソフトウェア開発キット)、またはグラフィカル A2A クライアントからも同じ要求が機能します。

方向	URL	入手場所
受信	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/{folderKey}/{agentReleaseId}	オートメーション > プロセス > A2A カードの URL をコピーする{folderKey} はエージェントがデプロイされているフォルダーのキーで、 {agentReleaseId} はデプロイ済みの会話型エージェントのリリース ID です。
発信	https://cloud.uipath.com/{org}/{tenant}/agenthub_/a2a/remote/{folderKey}/{slug}	Agent Gateway > A2A Agents を選択し、エージェントの行の [URL をコピー] を選択します。

1. TOKEN をベアラー トークンに設定し、AGENT_URL方向の URL を設定します。
2. 最初にエージェント カードをリクエストします。応答が成功すると、エージェントが存在することが確認され、フォルダーがユーザーの ID で解決され、トークンが受け入れられます。

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

3. JSON-RPC (JSON リモート プロシージャ コール) エンドポイントにメッセージを送信します。このエンドポイントは、 /.well-known/agent-card.json サフィックスなしの同じアドレスです。

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

応答には contextIdが付きます。次のメッセージに含めると、同じ会話が続行されます。会話 ID、タスク ID、および contextId は同じ値です。message/stream は、応答を SSE (サーバー送信イベント) ストリームとして返します。cURL のバッファリングを停止する -N を追加し、 -H "Accept: text/event-stream"。

UiPath を介したアウトバウンド呼び出しが失敗した場合、エージェントが期待する資格情報を使用して同じ要求をリモート エージェントに直接送信すると、問題が UiPath にあるのか、それともエージェント自体にあるのかがわかります。

両方向に共通するエラー

401 未承認

要求は UiPath に到達しましたが、トークンが受け入れられませんでした。

原因	解決方法
トークンの有効期限が切れています	新しいトークンを取得します。対話型ログイン トークンは 1 時間後に期限切れになります。個人用アクセス トークンの有効期限を設定できます。
トークンが別のテナントに対して発行されている場合	エージェント URL の組織とテナントが、トークンが発行された対象と一致していることを確認します。
ヘッダーの形式が正しくありません	形式は Authorization: Bearer <your-access-token>です。
トークンが送信されませんでした	エージェント カードの要求を含むすべての要求にトークンを含める必要があります。

タイムアウト

上限量	適用対象	フェーズの説明
15 分	UiPath を介した 1 つの要求	要求がカットオフされます。その期間内では、両側が接続を開いたままである限り、ストリーミング応答が継続します。
5 分	インバウンド会話の 1 ターン。	ターンは失敗します。タスクは引き続き使用可能であり、ターンをリトライできます。
30 秒	インバウンド ターンの背後にエージェント セッションを開始する。	上記のように。
5 分	UiPath エージェントからツールとして呼び出されるアウトバウンド エージェント	ツールの呼び出しは失敗し、エラー テキストがツールの出力として UiPath エージェントに届きます。

1 つの要求で許可される時間を超える時間実行される作業の場合は、応答をストリーミングするか、A2A タスクを使用します。最初の応答からタスク識別子を取得し、その結果をポーリングします。

プロトコルとカードのバージョン

双方向で、エージェント カードの要求を含め、 A2A-Version ヘッダーを持つ A2A プロトコル バージョンを選択します。v1.0 の場合は [ 1.0 ] に設定し、v0.3 の場合は省略します (空または空白の値は同じように扱われます)。

受信の場合、値は完全に一致するため、 1.0 は認識され、 1.0.0 は認識されません。受信エンドポイントは、フェッチしたカードのいずれかのワイヤ形式を受け入れるため、そこにあるヘッダーによって取得するカードのみが変更されます。

アウトバウンドでは、メジャー バージョンとマイナー バージョンのみが読み取られるため、 1.0 と 1.0.0 の両方で v1.0 を選択します。UiPath は、要求されたバージョンに一致するエンドポイントにのみ要求を転送するため、保存されているカードが満たさないバージョンの要求は 400 で拒否されます。

受信 (UiPath 外部)

この方向に登録するものは何もないため、すべての失敗は呼び出しで発生します。tasks/get は、会話の現在のステートと履歴を返します。方向に必要な内容については、「 受信 (UiPath 外部)」をご覧ください。

フォルダーまたはエージェントが見つから (404)

メッセージ	原因	解決方法
Folder with key {folderKey} not found	フォルダー キーが間違っているか、呼び出し元がアクセスできないフォルダーに名前を付けています。	URL と呼び出し元のフォルダーのアクセス権を確認します。
Conversational agent with release ID {agentReleaseId} not found in folder {folderId}	そのフォルダーには、そのリリース ID で会話型エージェントがデプロイされていません。	[ オートメーション] > [プロセス] でエージェントのエントリとリリース ID を確認します。

解決されたフォルダー キーは、30 分間キャッシュされます。解決されないキーはキャッシュされないため、フォルダーへのアクセス権をユーザーに付与すると、次回の呼び出しで有効になります。削除されたフォルダー、またはアクセス権が取り消されたフォルダーは、キャッシュされたエントリの有効期限が切れるまで解決され続けます。

応答する前にリリース ID を検証するのはエージェント カード エンドポイントのみであるため、診断の際はまずエージェント カードを要求してください。message/sendでは、誤ったリリース ID は明確に報告されません。

発信者がエージェントによって拒否された

フォルダーの検索を渡すことは、承認されることと同じではありません。発信者に必要なものについては、「 発信者が必要とするもの」をご覧ください。

会話は続かない

症状	原因	解決方法
フォローアップ メッセージで新しい会話を開始します	contextIdが、UiPath が保持しているタスクと一致しません。	contextIdと一緒にtaskIdを送信します。認識できない ID は Task not foundとして報告されます。
Task not found以前は機能していた ID の場合、	タスクが 7 日間非アクティブな状態であるか、要求が別のフォルダーまたはリリース ID に移動された後に期限切れになった。	タスクが作成されたフォルダーとプロセスに要求を送信するか、新しいタスクを開始します。
Cannot send a message to a task in a terminal state.	タスクは completed、 canceled、 failed、または rejectedです。	新しいタスクを開始します。
Task is in a terminal state and cannot be canceled.	タスクはすでに最終ステートに達しており、 tasks/cancel はまだ進行中のタスクにのみ適用されます。	アクションは不要です。タスクはすでに停止しています。

サポートされていない要求

これらは、正常な HTTP 応答内に JSON-RPC エラーを返します。

要求	得られるもの	代わりに使用してください
tasks/resubscribe, task/subscribe	UnsupportedOperation	message/stream
tasks/list	UnsupportedOperation	クライアントでタスク ID を追跡する
tasks/pushNotificationConfig/*	PushNotificationNotSupported	message/stream.このカードは、 pushNotifications: false
拡張エージェント カード	ExtendedAgentCardNotConfigured	普通のカード

tasks/getで否定的なhistoryLengthは、 InvalidParamsで拒否されます。

発信 (UiPath から外部へ)

この方向の呼び出しは 2 回認証されます。1 回は発信者が UiPath に、もう 1 回は UiPath がエージェントに認証します。ほとんどの障害は 2 番目のホップから発生します。関連する呼び出しは、contextId別にトレースにグループ化されます。設定については、「 アウトバウンド (UiPath から外部へ)」をご覧ください。

エージェントの保存に失敗する

症状	原因	解決方法
409 コンフリクト	フォルダー内の別のエージェントがすでにその名前またはスラッグを使用しています。	別の名前またはスラッグを選択します。どちらもフォルダー内で一意である必要があります。スラッグは作成後に変更できません。
エージェント カードが必要です	カード URL もカード JSON も指定されていません。	そのうちの 1 つを供給します。
エージェント カードが無効です。	JSON がカード オブジェクトではないか、JSON-RPC エンドポイントをパブリッシュしません。	リモート エージェントによってパブリッシュされたカードを指定します。
エージェント カードの URL が無効です	URL にスキームがないか、パブリック インターネット経由でアクセスできません。	絶対 http または https URL を入力するか、[ 接続の種類] を [ プライベート (リレー)] に設定します。

発信者はエージェント (403) の使用を許可されていません。

原因	解決方法
呼び出し元に MCP サーバーに対する表示権限がない	割り当てられたロールの [MCP サーバーの表示] を有効化します。
呼び出し元がフォルダーに割り当てられていない	エージェントが含まれるフォルダーに呼び出し元を割り当てます。
利用可能なライセンスがありません。	詳しくは、「 管理者>のライセンス」をご覧ください。

エージェント カードを取得するには、フォルダーへのアクセス権が必要ですが、MCP サーバーの表示権限は必要ありません。カードが読み込まれても、メッセージの送信が 403 を返す場合、不足している権限は MCP サーバーの表示です。

エージェントが見つからない (404)

原因	解決方法
この URL には、スラッグではなくエージェントの表示名が含まれています	表示名ではなく、スラッグを使用します。
フォルダー キーが間違っています	エージェントは、URL で指定されたフォルダーで検索されます。エージェントの行から URL をコピーします。
エージェントが削除されました	Confirm it still appears in Agent Gateway > A2A Agents.

要求は許可されません (400)

要求はすでにプラットフォームの A2A プロキシを通過しており、その方法で到着した要求は拒否されるため、呼び出しはループできません。これは、UiPath A2A エージェントの URL がリモート エージェントとして登録されている場合に発生します。代わりに、リモートエージェントの自身のアドレスを登録してください。

保存されているカードが見つからないか、古くなっています

格納されたカードは、後の呼び出しで再度取得されないため、アップストリームで変更されたカードは、以前のコンテンツを提供し続けます。最新の状態にするには、エージェントを開き、[ 編集] を選択して、現在のカードを指定します。アドバタイズされているエンドポイントを UiPath が書き換える前に、リモート エージェントがカードをパブリッシュしたときと同じ画面に表示されます。

カードが見つからないか古い場合は、次の 2 つの失敗が発生します。

症状	原因	解決方法
エージェント カードの 404、エージェント カードの 400 message/send	エージェントのカードは保存されないため、サービスを提供するものは何もありません。	Agent Gateway > A2A エージェントでエージェントを開き、カードを指定します。
400、要求された A2A バージョンのエンドポイントがありません	A2A-Version ヘッダーは送信されていませんが、エージェントは v1.0 のみをサポートしています。または、1.0が送信され、エージェントは v0.3 のみをサポートします。または、カードに JSON-RPC エンドポイントがパブリッシュされていない。または、リモート エージェントが変更され、保存されているカードがリモート エージェントと一致しなくなった場合。	ヘッダーを送信したり省略して、エージェントがサポートするものと一致させるか、現在のカードを指定します。リモート A2A エージェントは JSON-RPC エンドポイントを公開する必要があります。他の種類のインターフェイスはサポートされていません。

502、UiPath はリモート エージェントに到達できないか、リモート エージェントに対して認証できません

エージェントの保存中または呼び出されている間、リモート エージェントへのホップが失敗すると、UiPath は 502 と応答します。

保存中に UiPath はエージェント カードを取得します。保存に失敗すると、エージェントは作成されません。

原因	解決方法
UiPath からこの URL にアクセスできない	URL がパブリックに解決されることを確認するか、 プライベート (リレー) を使用します。
エージェントに必要な認証が設定されていない	エージェントが期待するヘッダーまたはコネクションを追加し、もう一度保存します。

呼び出し時に、接続されているがトークンを提供できない接続は、接続が Authorization ヘッダーの唯一のソースであるため、呼び出しに失敗します。エージェントの行で [ ユーザー設定 ] を開き、接続ステータスを確認します (各ステータスの意味については、「 ユーザーごとの接続 」をご覧ください)。非アクティブ ステータスは、コネクションが無効化されていることを意味します。そのため、[コネクション] タブで確認します。

資格情報が解決されたにもかかわらずエージェントに到達できない場合は、以下の手順を実行します。

原因	解決方法
エージェントがプライベート ネットワーク上にある	[ 接続の種類] を [ プライベート (リレー)] に設定します。
アドレスを解決できないか、証明書が受け入れられません	エージェント カードで公開されているエンドポイントを確認します。多くの場合、カードの URL とは異なるホストです。
エージェントが実行されていない	エージェントに直接電話して確認します。
エージェントの移動	保存されているカードはまだ古いアドレスを示しています。現在のカードを指定します。

アセットを参照するヘッダーを解決できない

%ASSETS/AssetName% 形式のヘッダー値は要求が送信される前に解決され、アセットを読み取れない場合、未解決の値を送信せずに呼び出しは失敗します。

原因	解決方法
アセットがエージェントのフォルダーに存在しません。	Orchestrator で作成するか、作成するアセットを参照します。
呼び出し元はアセットを読み取れません	アセットの表示権限を付与します。
アセットの種類はサポートされていません	ヘッダーは 1 つの値に解決する必要があるため、key-value-list アセットは拒否されます。機能する種類については、「 Orchestrator アセットを参照する」をご覧ください。

呼び出しがタイムアウトします (504)

直接通話で、リモート エージェントが時間内に応答を開始しませんでした。この制限は、エージェントが応答 を開始する までに要する時間に適用されます。ストリームが開始されると、そのポイントをはるかに超えて続行できます。message/streamを使用するか、応答を開始するまでに時間がかかるエージェントに対してタスクを返し、結果をポーリングします。タイムアウトし続けている場合は、直接呼び出してアクセス可能であることを確認し、独自のログを確認します。

応答が大きすぎます

リモート エージェントからの応答にはサイズ制限があります。それを超える応答は拒否され、それを超えるストリーミング応答は、呼び出し元アプリケーションがすでにいくつかのイベントを受信した後、途中で停止されます。エージェントが大きなコンテンツを返した場合は、代わりに URL などの参照を返します。

UiPath エージェントからエージェントを呼び出す

登録済みエージェントが Agent Builder または Maestro フローにツールとしてアタッチされている場合、リモート エージェントからのエラーがタスクのステート errorでツールの出力として UiPath エージェントに返され、実行は続行されます。UiPath エージェントはそのテキストを入力として続行するため、モデルにとってエラーは通常のツールの結果のように見えます。失敗した呼び出しを診断するには、実行の トレース を開き、エージェントのツール呼び出しを選択します。トレースには、送信されたメッセージと返された応答またはエラーが記録されます。

UiPath エージェントは message/sendを使用してリモート エージェントを呼び出すため、UiPath エージェントの動作を再現する場合は を使用します。ストリーミングは、エージェントの UiPath URL を自分で呼び出す場合にのみ利用できます。

このパスでは、プラットフォームは完全な応答が得られるまで 5 分間待機し、徐々に生成される出力によってその待機時間が延長されることはありません。これ以上の時間を必要とするエージェントに対しては、まだ進行中のタスクを返します。つまり、プラットフォームによってタスクがターン間で保持されるため、UiPath エージェントは次のターンでタスクを続行できます。すでに completed、 canceled、 failed、または rejected に達しているタスクは続行できず、次の呼び出しで同じ会話内で新しいタスクを開始します。

格納されたカードに v1.0 の JSON-RPC インターフェイスも使用可能な v0.3 エンドポイントも発行されていない場合、ツールはまったく作成できず、実行では利用可能なエンドポイントがないことが報告されます。エージェントを開き、[ 編集] を選択して、カードで http または https経由で JSON-RPC エンドポイントが公開されることを確認します。

呼び出しは成功するが予期しない動作を行う

これらは、エラーが何も起こらない失敗であるため、続行するステータス コードはありません。

症状	原因	解決方法
呼び出しで間違った ID が使用されている	呼び出し元のユーザーに対して設定されたコネクションは、エージェントの既定のコネクションよりも優先されます。	予期しない接続について「 ユーザー設定 」を確認します。
設定されている Authorization ヘッダーは無視されているように見えます	コネクションがアタッチされ、コネクションはそのヘッダーを提供します。	期待どおりです。設定した他のすべてのヘッダーは引き続き送信されます。
予期されるコネクションがリストにありません	コネクションは、エージェント カードに公開されているアドレスでフィルター処理されます。多くの場合、登録したカードの URL とは異なるホストです。	コネクションが有効化されていること、および共有フォルダー内にあるか、選択したユーザーの個人用ワークスペース内にあることを確認します。
UiPath エージェントがリモート エージェントの能力を誤って説明しているか、期待どおりに使用しない	ツールの説明とスキルのリストは、保存されているエージェント カードから取得されます。	保存されているカードを最新の状態にしてから、UiPath エージェントを開いて、更新された説明を確認します。
通話は、他の会話とともにトレースにグループ化されません	会話の最初のメッセージにはまだ contextId がありません。	アクションは不要です。会話内の後のメッセージはグループ化されます。