# A2A API リファレンス

AGENTIC STAR SaaS版が提供する **A2A（Agent-to-Agent Protocol）** エンドポイントの詳細仕様です。A2A は JSON-RPC 2.0 のインターフェースで、エージェント間の連携や独自フロントからのタスク実行に利用します。A2A の **0.3 と 1.0** の両方に対応しています。

> **Marketplace 版**
>
> このページは SaaS 版の A2A です。Marketplace 版の A2A は [A2A API リファレンス（Marketplace 版）](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/a2a-ref.md) を参照してください。
>
> 接続方式の概要（Agent Card 例を含む）は [接続方式ガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/connection-guide.md#a2aagent-to-agent-protocol) を参照してください。

## ベース URL

すべてのリクエストは以下のベース URL に対して送信します。

SaaS

`https://api.fd.agenticstar.tm.softbank.jp`

## エンドポイント

SaaS

| メソッド | エンドポイント                        | 説明                                           |
| ---- | ------------------------------ | -------------------------------------------- |
| GET  | `/.well-known/agent-card.json` | Agent Card 取得（スキル一覧・認証方式・ケイパビリティ）。トークンは要りません |
| POST | `/api/v1/a2a`                  | A2A JSON-RPC エンドポイント（0.3 と 1.0 のメソッド）        |

**プロトコル:** JSON-RPC 2.0（待つ送信は `application/json`、ストリーミングは SSE）。gRPC と HTTP+JSON の形はありません。

### Agent Card

Agent Card は版で 2 種類あります。リクエストヘッダー `A2A-Version: 1.0` を付けると 1.0 の形だけの Agent Card、付けないか別の値のときは 0.3 と 1.0 の両方の項目を持つ 1 枚の Agent Card が返ります。どちらも、同じ `/api/v1/a2a` を 1.0 と 0.3 の口として載せています（`supportedInterfaces`）。

Agent Card のスキルの説明は短い要約です。細かい使い方はこのページにあり、Agent Card の `documentationUrl` はこのページ（英語）を指します。

## 版

リクエストヘッダー `A2A-Version` で、A2A のどの版で話すかを決めます。

| `A2A-Version`          | 版                        |
| ---------------------- | ------------------------ |
| 付けない                   | 0.3                      |
| `0.3`                  | 0.3                      |
| `1.0`                  | 1.0                      |
| それ以外（`2.0`・`0.3.0` など） | `-32009`（版に対応していない）で断ります |

- タスク ID は版の間で使い回せません。0.3 のタスク ID を 1.0 で送ると `-32001`（Task Not Found）で、続けるには `contextId` を使うよう案内します

## 認証

すべてのリクエストには `Authorization: Bearer <access_token>` ヘッダーが必須です（Agent Card の取得を除く）。トークンには `a2a:all` か `a2a:connect` のスコープが必要です。

| スコープ          | できること                                |
| ------------- | ------------------------------------ |
| `a2a:all`     | A2A のすべての操作（ファイル添付と一覧を含む）            |
| `a2a:connect` | A2A のエンドポイントにつなぐ。操作ごとに、下の表のスコープも必要です |

`a2a:connect` のときに、操作ごとに必要なスコープは次のとおりです（REST の同じ操作と同じスコープです）。

| 操作                                                                                                                                                                               | 必要なスコープ                   |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| 送る（`message/send`・`message/stream`・`SendMessage`・`SendStreamingMessage`）・取る（`tasks/get`・`GetTask`）・止める（`tasks/cancel`・`CancelTask`）・つなぎ直す（`tasks/resubscribe`・`SubscribeToTask`） | `chat:exec`               |
| ファイルを添えて送る                                                                                                                                                                       | `chat:exec` と `chat:file` |
| 一覧（`ListTasks`）                                                                                                                                                                  | `chat:history`            |

足りないときは `-32600`（細かい印 `MISSING_SCOPE`）で、必要なスコープと次にすることを返します。新しく作るアプリには、`a2a:connect` と、使う機能のスコープを付けることをおすすめします。

A2A のスコープは、アプリケーション（Authorization Code フロー）で選べます。システム連携（Client Credentials フロー）では選べません。

トークン取得方法は [認証 API リファレンス（SaaS）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.md) を参照してください。

## JSON-RPC メソッド

| 0.3                 | 1.0                    | 形式           | 説明                                |
| ------------------- | ---------------------- | ------------ | --------------------------------- |
| `message/send`      | `SendMessage`          | 待つ（JSON）     | メッセージを送信し、終わるか質問待ちになるまで待って結果を返します |
| `message/stream`    | `SendStreamingMessage` | ストリーミング（SSE） | メッセージを送信し、SSE で逐次イベントを受信します       |
| `tasks/get`         | `GetTask`              | 待つ（JSON）     | タスクの状態を取得します                      |
| ―                   | `ListTasks`            | 待つ（JSON）     | 1 つの会話のタスクの一覧を取得します（1.0 だけ）       |
| `tasks/cancel`      | `CancelTask`           | 待つ（JSON）     | タスクを止めます                          |
| `tasks/resubscribe` | `SubscribeToTask`      | ストリーミング（SSE） | 切れた後に、同じタスクのストリーミングにつなぎ直します       |

プッシュ通知の設定のメソッドは使えません（`-32003`）。

- 待つ送信（`message/send`・`SendMessage`）は、終わるか質問待ちになるまで待ちます。0.3 の `message/send` は、`configuration.blocking` の値によらず待ちます
- 1.0 の `SendMessage` で `configuration.returnImmediately` を `true` にすると、受け付けた時点のタスク（`TASK_STATE_SUBMITTED`）をすぐ返します。続きは `GetTask` か `SubscribeToTask` で追います

## タスクの形

タスクの範囲は版で違います。

|             | 0.3                    | 1.0                                            |
| ----------- | ---------------------- | ---------------------------------------------- |
| 1 つのタスク     | 会話全体                   | 1 回の依頼（利用者のメッセージ 1 つと、それへの応答。質問待ちに答えた続きも同じタスク） |
| タスク ID      | 会話 ID（`contextId` と同じ） | 依頼ごとの ID                                       |
| `contextId` | 会話 ID                  | 会話 ID                                          |

タスク ID と `contextId` は、中を読まない値として扱ってください（形は予告なく変わることがあります）。

- 状態の名前は規格どおりです。このエンドポイントは `rejected`（`TASK_STATE_REJECTED`）を返しません
- 質問待ち（`input-required`・`TASK_STATE_INPUT_REQUIRED`）の `status.message` は質問の文で、`metadata.interactionType` に `choice`・`confirmation`・`question` のどれかが入ります。質問の ID は `metadata.interactionId` に入ります（無い場合があります）
- 0.3 の `tasks/get` と `message/send` の `artifacts` には、前のターンの分も入ります（タスクが会話全体のため）。1.0 の `GetTask` の `artifacts`・`history` は、その依頼の分だけです
- 取る（`tasks/get`・`GetTask`）と一覧（`ListTasks`）の `history` は、`historyLength` を付けないと直近 100 件です。送る応答のタスクの `history` は、送ったメッセージ 1 件です。どちらも、`historyLength` を `0` にすると `history` は入りません

## 送り先の決まり

**0.3** では、送り先の会話を `taskId`、`metadata.conversationId`、`contextId` の順に見て決めます。どれも無ければ新しい会話です。

**1.0** では、`taskId` と `contextId` の組み合わせで決まります。`metadata.conversationId` は読みません。

| `taskId`  | `contextId`   | 対象の依頼（`taskId` が無いときは、その会話のいちばん新しい依頼） | 動き                                                         |
| --------- | ------------- | ------------------------------------- | ---------------------------------------------------------- |
| あり        | なし・会話と同じ      | 質問待ち                                  | 続き（同じタスク）                                                  |
| あり        | なし・会話と同じ      | 実行中                                   | `-32600`（`CONVERSATION_BUSY`）                              |
| あり        | なし・会話と同じ      | 終わっている                                | `-32004`（終わったタスクには送れない。`contextId` で新しい依頼を送るよう案内）          |
| あり        | 会話と違う         | ―                                     | `-32602`（`CONTEXT_TASK_MISMATCH`）                          |
| 無い・形が合わない | ―             | ―                                     | `-32001`（Task Not Found）                                   |
| なし        | あり（自分の会話）     | 質問待ち                                  | `-32004`（答えるには `taskId` を付けるよう案内）                          |
| なし        | あり（自分の会話）     | 実行中                                   | `-32600`（`CONVERSATION_BUSY`）                              |
| なし        | あり（自分の会話）     | 終わっている・依頼が無い                          | 同じ会話の新しい依頼（アーカイブした会話には送れません。新しい会話にするときは `contextId` を外します） |
| なし        | 無い・自分のものでない会話 | ―                                     | `-32602`（`CONTEXT_NOT_FOUND`。`contextId` を外すと新しい会話になる、と案内） |
| なし        | なし            | ―                                     | 新しい会話                                                      |

### 質問への答え方

タスクが `input-required`（`TASK_STATE_INPUT_REQUIRED`）になったら、答えを次のように送ります。

- **0.3**: 同じ `contextId` を付けて `message/send` で送ります
- **1.0**: 同じタスクの `taskId` を付けて `SendMessage` で送ります。`contextId` だけを付けて送ると `-32004` で、`taskId` を付けるよう案内します

答えを待つタスクの続きとして送った返信は、待っている質問に質問の ID（`metadata.interactionId`）があるときだけ、自動でその質問への答えとして記録されます（月の利用の枠の上限に達していても答えられます）。選択肢から選んだ答えなら、`metadata.optionIndex` に選んだ選択肢の番号（0〜9。最初が 0）を付けます。質問の ID が無いときは、`metadata.optionIndex` を付けずに文で答えます（答えとしては記録されません）。番号が 0〜9 の整数ではない・選択肢の外、または質問の ID のある質問を待つタスクの続きではない送信に付けたときは `-32602`（`INVALID_OPTION_INDEX`）です。

## 一覧（1.0 の `ListTasks`）

1 つの会話のタスク（依頼）の一覧を返します。`params.contextId`（会話 ID）が必須です。無いときは `-32004` で、`contextId` を付けるか `GetTask` を使うよう案内します。

- `pageSize` は 1〜100 です（既定 50）
- `includeArtifacts` が `true` のときだけ、各タスクの `artifacts` を含めます
- 並びは状態の時刻の新しい順です
- 会話が無い・自分のものでないときは、空の一覧を返します

## 止める

|             | 0.3（`tasks/cancel`） | 1.0（`CancelTask`） |
| ----------- | ------------------- | ----------------- |
| `params.id` | 会話 ID               | タスク ID            |
| 実行中         | 止めます                | 止めます（そのタスクの実行のとき） |
| 質問待ち        | 止められません（`-32002`）   | 止めます              |
| 終わっている      | 止められません（`-32002`）   | 止められません（`-32002`） |

止めると、状態が `canceled`（`TASK_STATE_CANCELED`）のタスクを返します。1.0 で、同じ会話の別の依頼が実行中のときも `-32002` です。

- 送った直後（応答がまだ保存される前）でも止められます。そのときは、止めるのに 10 秒ほどまで待つことがあります
- それでも止められないときは `-32603` で、数秒後にもう一度止めるよう案内します

## つなぎ直す

|         | 0.3（`tasks/resubscribe`） | 1.0（`SubscribeToTask`）             |
| ------- | ------------------------ | ---------------------------------- |
| 最初に送るもの | なし（つないだ後の出来事だけ）          | その時点のタスク                           |
| 実行中     | その実行の出来事を流します            | その実行の出来事を流します                      |
| 質問待ち    | `-32001`（実行中でないため）       | つないだまま待ち、答えが届いて実行が始まったら、その出来事を流します |
| 終わっている  | `-32001`                 | `-32004`（`GetTask` で結果を読むよう案内）     |

1.0 の `SubscribeToTask` は、タスクが終わる（`TASK_STATE_COMPLETED`・`TASK_STATE_CANCELED`・`TASK_STATE_FAILED`）と最後の状態を送って閉じます。答えの後にまた質問になったときは、その状態を送ってつないだまま待ちます。待つのは最大 2 時間で、超えると状態を送らずに閉じます。その後も `GetTask` か `SubscribeToTask` で続きを追えます。

どちらの版も、切れている間の出来事を 1 つずつ送り直すことはしません。1.0 では、最初に送るタスクに、その時点までの artifact と状態が入ります。

### 0.3 のストリーミングの `final`

0.3 の `message/stream`・`tasks/resubscribe` では、質問待ち（`input-required`）の状態の出来事は `final: true` で、そこでストリームが閉じます。1.0 には `final` が無く、ストリームが閉じることで終わりが分かります。0.3 での `final: true` は、0.3 への対応をやめるときに外します。

## 提供スキル

Agent Card で公開しているスキルは以下のとおりです。

### `execute_task`

エージェントにタスクを送信し、隔離された環境で自律実行します。`agentMode: true` 相当（プランニング + ツール利用）。複雑なタスクは数分かかります。

| 項目      | 内容                                                                                                                    |
| ------- | --------------------------------------------------------------------------------------------------------------------- |
| 必要スコープ  | `a2a:all`、または `a2a:connect` と `chat:exec`（ファイルを添えるときは `chat:file` も）                                                  |
| 用途      | 複合タスクの自律実行・成果物生成                                                                                                      |
| 添えるファイル | 中身の部品（base64）だけ。URL の部品は使えません。1 ファイル 5 MB まで、5 ファイルまで、合計 20 MB まで。受け付けない種類のファイルは `-32005`（Content Type Not Supported） |

### `direct_llm`

LLM に直接問い合わせを行います。`agentMode: false` 相当（プランニング・ツール利用なし）。数秒で答え、ファイルは返しません。

| 項目     | 内容                                        |
| ------ | ----------------------------------------- |
| 必要スコープ | `a2a:all`、または `a2a:connect` と `chat:exec` |
| 用途     | 知識ベース Q\&A・翻訳・要約 等の単発処理                   |

### 答えと成果物の読み方

- **最終回答**は、`completed` の状態の `status.message` の文です。同じ文が `result-` で始まる artifact にも入ります
- **ファイル**は、ダウンロード用の URL を持つ artifact で届きます（下の「成果物の取得」）
- **質問**は、`input-required` の状態の `status.message` の文です。同じ質問が `interaction-` で始まる artifact にも入ります。その `metadata.interactionType` は `choice` / `confirmation` / `question` のいずれかで、質問の ID は `metadata.interactionId` に入ります（無い場合があります）。選択肢があるときは `metadata.options[]` に入ります（`choice` 以外では、選択肢が `parts[0]` の文の末尾にも `Options: …` として入ります）。回答を待っているターンには `result-` artifact は付きません
- **0.3** の `tasks/get`・`message/send` は、前のターンの artifact（前の質問の `interaction-` など）も返します。どのターンの artifact かは `artifact.metadata.messageId`（ファイルの artifact では、`artifactId` の末尾の `<messageId>`）で分けてください
- **止めた・失敗したタスク**は、状態（0.3 は `canceled`・`failed`、1.0 は `TASK_STATE_CANCELED`・`TASK_STATE_FAILED`）で分かります。そのときの artifact は当てにしないでください。止めた・失敗したときに新しい `result-`・`interaction-` が作られるとは限らず、前に送られたもの（質問待ちになったときの `interaction-` など）や、取り直したときに作り直されたもの（質問の `interaction-`、途中までの文の `result-`）が残ることがあります
- `ui-resource-` で始まる artifact は人に見せる補助の UI です（下の「UI リソース」）。UI を返せないときは、その artifact ごと出しません

## メッセージ構造

メッセージの形は A2A の規格どおりです。この製品では、次のように扱います。

- `messageId`（メッセージごとに新しい値）と `role`（0.3 は `"user"`、1.0 は `"ROLE_USER"`）は必須です。0.3 で欠けると `-32602` です
- 文の部品が要ります。文の部品が複数あるときは、改行でつないだ 1 つの指示として扱います
- データの部品（`data`）は指示に使いません。文が空のメッセージ（ファイルだけ・データだけなど）は、タスクが失敗します
- 実行の仕方は `metadata` で指定します（下の「メタデータ」）

### メタデータ

| キー            | 既定値         | 説明                                                                                                                                                             |
| ------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `agentMode`   | `true`      | `true`: エージェント実行 / `false`: LLM 直接問い合わせ                                                                                                                        |
| `agentLevel`  | `"default"` | `default` / `high_performance`                                                                                                                                 |
| `reportMode`  | `"with"`    | `with`: 実行の終わりに、整形した作業報告書（PDF）も作ります / `without`: その報告書だけを省きます（タスクの中身とほかに返すものは同じです）                                                                             |
| `personaKey`  | （未適用）       | ペルソナ（応答人格）の指定。未指定時はペルソナを適用しない。不明なキーは `-32602`（`INVALID_PERSONA_KEY`）                                                                                           |
| `optionIndex` | （無し）        | 選択肢から選んだ答えの番号（0〜9。最初が 0）。質問の ID（`metadata.interactionId`）のある質問を待つタスクの続きの返信だけに付けます（[質問への答え方](#%E8%B3%AA%E5%95%8F%E3%81%B8%E3%81%AE%E7%AD%94%E3%81%88%E6%96%B9)） |

いずれも省略可能で、0.3 と 1.0 で同じです。詳細は [接続方式ガイド - A2A 実行パラメータの指定](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/connection-guide.md#execution-parameters) を参照してください。

## 成果物の取得

エージェントが生成したファイルは、artifact の **ファイルの部品** として通知されます。artifact 自体にファイルの中身は含まれず、0.3 は `file.uri`、1.0 は `url` がダウンロード用の URL です。ファイルの名前は、0.3 は `file.name`、1.0 は `filename` に入ります。

ダウンロード用の URL は**A2A と同じ Bearer トークンで GET** します。`a2a:all`、または `a2a:connect` と `chat:exec` のトークンで、追加のスコープなしにダウンロードできます。

```bash
curl "<file.uri または url の値>" \
  -H "Authorization: Bearer <access_token>" \
  -o report.pdf
```

エンドポイントの詳細は [ユーザー API リファレンス — 成果物取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#get-artifact) を参照してください。

## UI リソース

エージェントが実行中に UI（グラフ・地図・カード一覧など）を生成した場合、`artifactId` が `ui-resource-` で始まる artifact として通知されます。

UI リソースは**補助的な出力**です。そのターンの実質的な出力は `result-` artifact（回答が質問で終わった場合は `interaction-` artifact）にあります。

実行中に生成された UI がすべて artifact になるとは限りません。**HTML を提供できない場合、その `ui-resource-` artifact は配信されません。**

### HTML の取得

`type: "html"` の場合、**HTML は artifact に含まれません**。以下のエンドポイントで取得します。

```text
GET /api/v1/conversations/{contextId}/ui-resources/{tool_call_id}
```

`contextId` はイベントに含まれる値（会話 ID と同一）、`tool_call_id` は `parts[0].data.tool_call_id` です。A2A と同じ Bearer トークンで取得でき、`a2a:all`、または `a2a:connect` と `chat:exec` のトークンで、追加のスコープなしに取得できます。詳細は [ユーザー API リファレンス — UI リソース取得](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#get-ui-resource) を参照してください。

`type: "data"` の場合はペイロードが `parts[0].data.data` にインラインで含まれるため、取得は不要です。

チャットで作った下書きのカードの `ui-resource-` artifact には、2 つ目の部品（データの部品）が付き、その `data.draft`（`parts[1].data.draft`）に下書きが入ります。形と作り方は [ストリーミングガイド — delta.draft](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#delta-draft) と同じです。

入力を求める UI（選択肢カードや質問フォーム）は `ui-resource-` ではなく **`interaction-` で始まる artifact の 2 番目の部品**（データの部品）に入ります。UI が提供できない場合はこの部品が付かず、`parts[0]` のテキストだけになります。回答の送り方は上の「質問への答え方」のとおりです。

> **HTML をモデルに渡さないでください**
>
> **取得した HTML をモデルのコンテキストに入れないでください**（外部コンテンツではプロンプトインジェクションのリスクがあり、自社由来でも推論上の価値はありません）。取得した HTML は、アプリケーション側で人間に向けて描画するものです。
>
> 描画時の注意は [ストリーミングガイド — 描画時の注意](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#rendering-notes) を参照してください。

## リクエスト例

### `SendMessage`（1.0）

```bash
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/a2a \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "A2A-Version: 1.0" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "SendMessage",
    "params": {
      "message": {
        "messageId": "9b2f0c1e-4d8a-4f7e-a1b2-3c4d5e6f7a8b",
        "role": "ROLE_USER",
        "parts": [{ "text": "売上データを分析してください" }],
        "metadata": { "agentMode": true }
      }
    }
  }'
```

応答の `result.task.id` がタスク ID、`result.task.contextId` が会話 ID です。

## エラー

エラーの番号は A2A の規格どおりです（[A2A 仕様](https://a2a-protocol.org/latest/specification/)）。エラーの文は、相手（人やエージェント）が次にすることが分かるように書いています。細かい印は、0.3 は `error.data.code`、1.0 は `error.data[].metadata.code` に入ります。

| 細かい印                                                         | code     | いつ                                                                               |
| ------------------------------------------------------------ | -------- | -------------------------------------------------------------------------------- |
| `MISSING_SCOPE`                                              | `-32600` | 操作に必要なスコープが無い                                                                    |
| `CONVERSATION_BUSY`                                          | `-32600` | 同じ会話が実行中                                                                         |
| `ACCOUNT_SUSPENDED`                                          | `-32600` | 管理者に利用を止められた利用者                                                                  |
| `FEATURE_NOT_PERMITTED`                                      | `-32600` | 管理者が、エージェントモード（`metadata.agentMode` が `true`。省略したときも `true`）か、ファイルの添付を許可していない    |
| `TEXT_SEGMENT_TOO_LARGE`                                     | `-32600` | 文の部品が長すぎる                                                                        |
| `PROJECT_CONVERSATION`                                       | `-32600` | プロジェクトの実行の会話に送った                                                                 |
| `CONVERSATION_ARCHIVED`                                      | `-32600` | アーカイブ中の会話に送った（会話を元に戻してから送り直す）                                                    |
| `CONVERSATION_NOT_FOUND`                                     | `-32600` | 0.3 で、無い・自分のものでない会話に送った                                                          |
| `CONTEXT_NOT_FOUND`                                          | `-32602` | 1.0 で、無い・自分のものでない会話の `contextId` を送った                                            |
| `CONTEXT_TASK_MISMATCH`                                      | `-32602` | 1.0 で、`taskId` と `contextId` が合わない                                               |
| `FILE_URI_NOT_SUPPORTED`                                     | `-32602` | URL のファイルの部品を送った                                                                 |
| `FILE_PROCESSING_FAILED`                                     | `-32602` | 添えたファイルを受け付けられない（大きさ・数など）                                                        |
| `INVALID_PERSONA_KEY`                                        | `-32602` | 不明な `personaKey`                                                                 |
| `INVALID_OPTION_INDEX`                                       | `-32602` | `metadata.optionIndex` が 0〜9 の整数ではない・質問の選択肢の外、または質問の ID のある質問を待つタスクの続きではない送信に付けた |
| `INVALID_PAGE_SIZE`・`INVALID_TIMESTAMP`・`INVALID_PAGE_TOKEN` | `-32602` | `ListTasks` のパラメータが不正                                                            |
| `INVALID_PARAMS`                                             | `-32602` | 1.0 の送信に `message` が無い                                                           |
| `EXECUTION_TIMEOUT`                                          | `-32603` | 待つ送信が、実行の最大時間を超えた                                                                |
| `FEATURE_PERMISSIONS_UNAVAILABLE`                            | `-32603` | 機能の許可を確かめられない（時間をおいて送り直す）                                                        |

HTTP 層のエラー:

| HTTP Status               | 説明                                                                                                         |
| ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`        | アクセストークンが無効・期限切れ                                                                                           |
| `403 Forbidden`           | `a2a:all` も `a2a:connect` も無い、または `/api/v1/a2a` へのリクエストが前段のセキュリティの検査に止められた場合（`error.code` が `waf_blocked`） |
| `413 Payload Too Large`   | リクエストサイズが上限超過                                                                                              |
| `503 Service Unavailable` | 認証の仕組みが一時的に使えない。少し待ってから送り直してください。続くときは、サービスの管理者に問い合わせてください                                                 |

## 関連ドキュメント

- [接続方式ガイド - A2A](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/connection-guide.md#a2aagent-to-agent-protocol) — Agent Card 例とユースケース
- [認証 API リファレンス（SaaS）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/auth-saas-ref.md) — トークン取得
- [A2A 仕様](https://a2a-protocol.org/latest/specification/) — プロトコル詳細
