# 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 リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/build/reference/helm-values-ref.md) を参照してください。

## ベース 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 リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/auth-mp-ref.md)） | `oauth2ClientCredentials` の `tokenUrl`             |
| アプリケーション（外部ツールでのログイン）の利用者のトークン | Authorization Code フロー（[認証ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/auth-guide.md)）                                                                          | 外部ツールでのログインの入口が開いている環境だけ、`oauth2AuthorizationCode` |

- 外部ツールでのログインは、管理者がその入口を開けた環境でだけ使えます（[API 利用準備ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md)）
- 外部ツールでのログイン以外で得た利用者のトークン（メイン画面にログインしたときのトークンなど）では、`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 版）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/a2a-ref.md) の「版」「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`、無ければ `-32001`
- `contextId` はいつも `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 を中断します（[ワークフローの実行の中断](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/user-api-reference-projects.md#cancel-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 版）— エラー](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/a2a-ref.md#%E3%82%A8%E3%83%A9%E3%83%BC)）。スコープを確かめないので `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 版）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/a2a-ref.md) — メソッド・タスクの形・エラーの詳細
- [認証 API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/auth-mp-ref.md) — 標準のトークンエンドポイント
- [API 利用準備ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/setup-guide.md) — サービスアカウントと外部ツールでのログインの準備
- [A2A 仕様](https://a2a-protocol.org/latest/specification/) — プロトコル詳細
