メインコンテンツまでスキップ

A2A API リファレンス

AGENTIC STAR マーケットプレイス版が提供する A2A(Agent-to-Agent Protocol) エンドポイントの詳細仕様です。A2A に対応した外のエージェントやアプリケーションから、登録 Agent と 公開したワークフロー(プロジェクト) を呼びます。A2A の 0.3 と 1.0 の両方に対応しています。

A2A を使える環境

A2A は、管理者が外部の受け口(MCP・A2A)を開け、標準のトークンエンドポイントを設定した環境でだけ使えます。開けていない環境では、エンドポイントは 404 Not Found を返します(トークンが無い・無効なときは、先に 401 Unauthorized が返ります)。受け口の開け方は、構築の節の Helm Values リファレンス を参照してください。

ベース URL​

すべてのリクエストは以下のベース URL に対して送信します。<your-domain> は導入した環境のドメインに読み替えてください。

Marketplace
https://<your-domain>

エンドポイント​

登録 Agent と公開したワークフローごとに、エンドポイントと Agent Card があります。一覧のエンドポイントはありません(登録 Agent の ID の一覧は GET /v1/marketplace-agents で読めます。公開したワークフローの一覧の口はありません)。

メソッドエンドポイント説明
POST/api/v1/a2a/agents/{agentId}/登録 Agent の A2A JSON-RPC エンドポイント
GET/api/v1/a2a/agents/{agentId}/.well-known/agent-card.jsonその Agent Card
POST/api/v1/a2a/projects/{projectId}/公開したワークフローの A2A JSON-RPC エンドポイント
GET/api/v1/a2a/projects/{projectId}/.well-known/agent-card.jsonその Agent Card
  • エンドポイントの URL は、Agent Card の url・supportedInterfaces のとおり、末尾に / が付きます(付けなくても同じです)
  • Agent Card の取得にもトークンが必要です。トークンの決まりは下の「認証」と同じです
  • agentId は、管理者が管理コンソールで登録した Agent の ID です。GET /v1/marketplace-agents の marketplaceAgentId で一覧を読めます(A2A の受け口が有効な配備で、名刺と口の {agentId} にそのまま使えます)
  • projectId は、プロジェクトのオーナーが A2A で公開したワークフローの ID です。オーナーに確かめてください。公開の設定で A2A のカードの名前と説明を書いたワークフローだけが呼べます

プロトコル: JSON-RPC 2.0(待つ送信は application/json、ストリーミングは SSE)

Agent Card​

Agent Card は版で 2 種類あります。リクエストヘッダー A2A-Version: 1.0 を付けると 1.0 の形だけの Agent Card、付けないか別の値のときは 0.3 と 1.0 の両方の項目を持つ 1 枚の Agent Card が返ります。

項目登録 Agent公開したワークフロー
名前・説明管理コンソールで書いた A2A のカードの名前・説明。書いていなければ、Agent の表示名と説明プロジェクトの公開の設定で書いた A2A のカードの名前・説明
スキルA2A のカードのスキル。書いていなければ、名前と説明で 1 つA2A のカードのスキル。書いていなければ、名前と説明で 1 つ
ストリーミング対応(streaming: true)対応しない(streaming: false)
入力・出力の形A2A のカードの設定。書いていなければ text/plain入力 text/plain・application/json、出力 text/plain

認証​

すべてのリクエスト(Agent Card の取得を含む)には Authorization: Bearer <access_token> ヘッダーが必須です。使えるトークンは次の 2 つです。マーケットプレイス版ではスコープによる制限はありません。

トークン取り方Agent Card での載り方
システム連携(サービスアカウント)のトークン標準のトークンエンドポイント(https://<auth-domain>/api/v1/oauth/token)の Client Credentials フロー(認証 API リファレンス)oauth2ClientCredentials の tokenUrl
アプリケーション(外部ツールでのログイン)の利用者のトークンAuthorization Code フロー(認証ガイド)外部ツールでのログインの入口が開いている環境だけ、oauth2AuthorizationCode
  • 外部ツールでのログインは、管理者がその入口を開けた環境でだけ使えます(API 利用準備ガイド)
  • 外部ツールでのログイン以外で得た利用者のトークン(メイン画面にログインしたときのトークンなど)では、404 Not Found が返ります
  • トークンが無い・無効なときは 401 Unauthorized が返ります

版とメソッド​

リクエストヘッダー A2A-Version で版を決めます(付けない・0.3 は 0.3、1.0 は 1.0、それ以外は -32009)。メソッドの名前とストリーミングのイベントの形は、A2A の規格どおりで、SaaS 版と同じです。タスクの形は、登録 Agent のエンドポイントは SaaS 版と同じで、公開したワークフローのエンドポイントは 1 回の実行(run)です(下の各節)。A2A API リファレンス(SaaS 版) の「版」「JSON-RPC メソッド」「タスクの形」を参照してください。

登録 Agent のエンドポイント​

POST /api/v1/a2a/agents/{agentId}/ は、その登録 Agent にタスクを送ります。版・メソッド・タスクの形・送り先の決まり・一覧・止める・つなぎ直すは SaaS 版の A2A と同じで、次の点が違います。

項目マーケットプレイス版
使えるメソッド送る・ストリーミング・取る・止める・つなぎ直す(0.3 と 1.0)、一覧(1.0 の ListTasks)
タスクの形0.3 は会話全体、1.0 は 1 回の依頼(SaaS 版と同じ)
1.0 のタスク ID登録 Agent ごとの ID です。別の Agent のエンドポイントに送ると -32001(Task Not Found)
メッセージの metadataagentMode・agentLevel・reportMode・personaKey は使いません(送っても効きません)
添えるファイル中身の部品(base64)だけ。URL の部品は使えません
質問への答え方0.3 は同じ contextId、1.0 は同じ taskId で送ります(SaaS 版と同じ)

送り先の決まり(taskId と contextId の組み合わせ)、一覧、止める、つなぎ直すの動きは SaaS 版と同じです。

公開したワークフローのエンドポイント​

POST /api/v1/a2a/projects/{projectId}/ は、公開したワークフローを 1 回動かします(run)。1 つのメッセージで 1 つの run を始め、タスクは run です。

呼べる人​

  • システム連携(サービスアカウント)のトークン
  • 外部ツールでのログインの利用者のうち、そのプロジェクトの参加者(オーナー・運用担当・メンバー)と、組織の運用の役割の人。どちらでもない人は project_not_found で断ります。ほかの人が始めた run を止められるのは、オーナー・運用担当と組織の運用の役割の人です

入力​

メッセージの部品run への入力
文の部品(1 つ以上)改行でつないだ文字列
データの部品 1 つだけ(中身が JSON の object)その object
文とデータの混在・データの部品 2 つ以上・object でないデータ-32602(INVALID_INPUT)
ファイルの部品-32005(ファイルは使えません)

入力は JSON にして 8,000 文字以内、UTF-8 で 16 KB 以内(日本語でおよそ 5,000 文字)です。超えると -32602(PAYLOAD_TOO_LARGE)です。

送る​

指定応答
1.0 の configuration.returnImmediately: true、または 0.3 で configuration.blocking が無い・false始めた run のタスク(0.3 は submitted、1.0 は TASK_STATE_SUBMITTED)をすぐ返します
それ以外(待つ)run が終わるまで待って、終わった状態のタスクを返します。待つのは既定で最大 2 時間で、超えると -32603(EXECUTION_TIMEOUT)。run は動き続けているので、取る(GetTask・tasks/get)で追ってください。新しいメッセージとして送り直すと、別の run が始まります
  • 同じ呼び手が同じ messageId・同じ入力で送り直したときは、新しい run を始めず、前の run を返します。同じ messageId で入力が違うときは断ります
  • taskId を付けた送信は断ります(run ごとに新しく始めるため)。その run があれば -32004、無ければ -32001
  • contextId はいつも projectId です。別の値を送ると -32602(CONTEXT_NOT_FOUND)

タスクの状態​

run の状態0.31.0
実行中workingTASK_STATE_WORKING
確認待ち(AGENTIC STAR の画面で人が決める確認依頼)workingTASK_STATE_WORKING
完了completedTASK_STATE_COMPLETED
失敗failedTASK_STATE_FAILED
却下rejectedTASK_STATE_REJECTED
止めたcanceledTASK_STATE_CANCELED

status.message には run の要約が入ります(無ければ、最後に終わった工程の出力の要約。どちらも無いときは入りません)。成果物(artifacts)と履歴(history)は返しません。プロジェクトに参加していない、組織の運用の役割の人には、status.message は入りません(最後に終わった工程が中断で閉じたときだけ、その印の cancelled が入ります)。

取る・一覧​

  • 取る(tasks/get・GetTask)の params.id は、送ったときに返ったタスク ID(run の ID)です
  • 一覧(1.0 の ListTasks)は、その呼び手がそのプロジェクトで始めた run を返します。状態(status)・時刻(statusTimestampAfter)で絞れ、件数(pageSize)は 1〜100(既定 50)で、pageToken で続きを読めます。状態は、取るより最大 1 分ほど遅れることがあります

止める​

止める(tasks/cancel・CancelTask)は、run を中断します(ワークフローの実行の中断と同じです)。params.id は、送ったときに返ったタスク ID(run の ID)です。

run の状態応答
実行中・確認待ち中断し、状態が canceled(TASK_STATE_CANCELED)のタスクを返します
終わっている(中断した後を含みます)-32002(Task Not Cancelable)
無い・形が合わない ID-32001(Task Not Found)
  • 中断は元に戻せません。まだ判断されていない確認依頼は取り下げられ、動いている工程の Agent には停止を伝えます
  • 同じタスクをもう一度止めると -32002 です

できないこと​

操作応答
ストリーミング(message/stream・SendStreamingMessage)・つなぎ直す(tasks/resubscribe・SubscribeToTask)-32004(run は始めません)
プッシュ通知の設定-32003

エラー​

エラーの番号は SaaS 版と同じです(A2A API リファレンス(SaaS 版)— エラー)。スコープを確かめないので MISSING_SCOPE は返らず、personaKey を使わないので INVALID_PERSONA_KEY も返りません。マーケットプレイス版だけのものは次のとおりです。細かい印は、0.3 は error.data.code、1.0 は error.data[].metadata.code に入ります。

場面エンドポイント(POST)Agent Card(GET)
登録 Agent が無い・無効-32602(agent_not_found)404(agent_not_found)
公開していない・無いワークフロー、またはメンバーでも組織の運用の役割の人でもない-32602(project_not_found)404(project_not_found)
ほかの人が始めた run を、オーナーでも運用担当でもなく、組織の運用の役割も持たないメンバーが止めた-32600(operator_only)―
公開したワークフローを実行する人の利用を、管理者が止めている-32600(PRINCIPAL_SUSPENDED)―
公開したワークフローのプロジェクト、または置いた登録 Agent を、管理者が止めている-32600(ADMIN_STOPPED)―
公開したワークフローのプロジェクトの最初の定義が承認待ち-32600(DEFINITION_PENDING)―
公開したワークフローのプロジェクトに、取り込みで見つからなかった参照が残っている(つなぎ直すまで始められない)-32600(RELINK_REQUIRED)―
公開したワークフローへの入力の形が合わない-32602(INVALID_INPUT)―
公開したワークフローへの入力が長すぎる-32602(PAYLOAD_TOO_LARGE)―
登録 Agent の一覧を一度も読めていない、または公開したワークフローの一覧を読めない-32603(少し待って送り直すよう案内)503

公開していない・無い・サイクル型のプロジェクトは、どれも同じ project_not_found で、どの理由かは返しません。Agent Card のエラーは、REST の API と同じエラーの形です。

関連ドキュメント​