A2A API リファレンス
AGENTIC STAR マーケットプレイス版が提供する A2A(Agent-to-Agent Protocol) エンドポイントの詳細仕様です。A2A に対応した外のエージェントやアプリケーションから、登録 Agent と 公開したワークフロー(プロジェクト) を呼びます。A2A の 0.3 と 1.0 の両方に対応しています。
A2A は、管理者が外部の受け口(MCP・A2A)を開け、標準のトークンエンドポイントを設定した環境でだけ使えます。開けていない環境では、エンドポイントは 404 Not Found を返します(トークンが無い・無効なときは、先に 401 Unauthorized が返ります)。受け口の開け方は、構築の節の Helm Values リファレンス を参照してください。
ベース URL
すべてのリクエストは以下のベース URL に対して送信します。<your-domain> は導入した環境のドメインに読み替えてください。
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) |
メッセージの metadata | agentMode・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、無ければ-32001contextIdはいつもprojectIdです。別の値を送ると-32602(CONTEXT_NOT_FOUND)
タスクの状態
| run の状態 | 0.3 | 1.0 |
|---|---|---|
| 実行中 | working | TASK_STATE_WORKING |
| 確認待ち(AGENTIC STAR の画面で人が決める確認依頼) | working | TASK_STATE_WORKING |
| 完了 | completed | TASK_STATE_COMPLETED |
| 失敗 | failed | TASK_STATE_FAILED |
| 却下 | rejected | TASK_STATE_REJECTED |
| 止めた | canceled | TASK_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 と同じエラーの形です。
関連ドキュメント
- A2A API リファレンス(SaaS 版) — メソッド・タスクの形・エラーの詳細
- 認証 API リファレンス — 標準のトークンエンドポイント
- API 利用準備ガイド — サービスアカウントと外部ツールでのログインの準備
- A2A 仕様 — プロトコル詳細