# 接続方式ガイド

AGENTIC STAR のエージェントと対話するための 3 つの接続方式と、すべての方式で共通するコンセプトを解説します。

## 3つの接続方式

AGENTIC STAR のエージェントとは、用途に応じて 3 つの方式で対話できます。どの方式でも、エージェントに送信されるリクエストと返されるレスポンスの基本構造は共通です。

|          | Chat API / SSE         | MCP                          | A2A                     |
| -------- | ---------------------- | ---------------------------- | ----------------------- |
| プロトコル    | `REST + SSE`           | `Streamable HTTP / JSON-RPC` | `JSON-RPC`              |
| エンドポイント  | `/v1/chat/completions` | `/v1/mcp`                    | `/v1/a2a`               |
| スコープ     | `chat:exec`            | `mcp:connect / mcp:all`      | `a2a:connect / a2a:all` |
| ディスカバリー  | `なし（API仕様を参照）`         | `tools/list で自動取得`           | `Agent Card で自動取得`      |
| 想定クライアント | `自社アプリ / HTTP クライアント`  | `Claude / MCP 対応 AI エージェント`  | `A2A 対応 AI エージェント`      |
| ドキュメント詳細 | `ユーザー API リファレンス参照`    | `下記参照`                       | `下記参照`                  |

### 方式の選び方

> **どの方式を選ぶべきか**
>
> - **Chat API / SSE** — 自社アプリケーションにエージェント機能を組み込む場合。リクエスト・レスポンスを自分で制御できます。
> - **MCP** — Claude 等の MCP 対応 AI エージェントから AGENTIC STAR に接続する場合。エージェントがツール定義を自動取得します。
> - **A2A** — A2A（0.3 と 1.0）対応のエージェントから AGENTIC STAR に接続する場合。Agent Card でスキルを自動取得します。

## 共通リクエストパラメータ

3つの接続方式すべてで、エージェントに送信されるリクエストは内部で同じ形式に変換されます。以下のパラメータが共通して利用できます。

<!-- -->

> **方式ごとの送信キー**
>
> パラメータ名は概念上の共通名です。実際のキーや構造は方式ごとに異なります:
>
> - **Chat API / SSE**: `messages[].content`（OpenAI 互換形式）
> - **MCP**: ツール引数の `prompt`
> - **A2A**: `message.parts[]` の文の部品の `text`（0.3 は `kind: "text"` が付き、1.0 は `kind` が付きません）
> - **質問への答えの印**: Chat API はボディの `interactionReply`、MCP はツール引数の `interactionReply`。A2A は印を付けず、答えを待つタスクの続きとして送ります（質問に ID があるときだけ、答えとして記録され、選択肢の番号を `metadata.optionIndex` で送れます。ID が無いときは番号を付けずに文で答えます）
>
> 詳細は各方式のセクション（[Chat API](#chat-api--sse) / [MCP](#mcpmodel-context-protocol) / [A2A](#a2aagent-to-agent-protocol)）を参照してください。

| パラメータ            | 型         | 必須 | 説明                                                                                     |
| ---------------- | --------- | -- | -------------------------------------------------------------------------------------- |
| `prompt / text`  | `string`  | 必須 | エージェントへの指示テキスト                                                                         |
| `conversationId` | `string`  | —  | 既存の会話を継続する場合に指定。省略すると新しい会話が作成されます。                                                     |
| `agentMode`      | `boolean` | —  | true（デフォルト）= 自律エージェント実行。false = LLM 直接応答。                                              |
| `agentLevel`     | `string`  | —  | "default"（デフォルト）または "high\_performance"。エージェントの推論に使用する LLM モデルを切り替えます。                 |
| `reportMode`     | `string`  | —  | "with"（デフォルト）または "without"。完了時に作業報告書を生成するかを制御します。                                      |
| `personaKey`     | `string`  | —  | エージェントの応答人格（ペルソナ）。`GET /v1/personas`（MCP は list\_personas）が返す personaKey を指定。省略時は適用なし。 |
| `files`          | `array`   | —  | 添付ファイル。Chat API では事前アップロード + fileId、MCP では base64 エンコードで送信します。                         |

## レスポンスモデル

どの接続方式でも、エージェントの応答には以下の情報が含まれます。フォーマットはプロトコルごとに異なり、要素によっては方式ごとに提供形式（単一フィールド / イベント分割）が変わります。詳細は各方式のセクションを参照してください。

| 要素               | 説明                                                                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `text`           | エージェントの応答テキスト                                                                                                                        |
| `conversationId` | 会話 ID。次回のリクエストで指定すると会話を継続できます。                                                                                                       |
| `deliverables`   | エージェントが生成した成果物ファイルの一覧（ファイル名、パス、MIME タイプ等）                                                                                            |
| `executionSteps` | エージェントの実行トレース（ツール呼び出し、コード実行等のステップ詳細）                                                                                                 |
| `interaction`    | ユーザーへの対話リクエスト（発生した場合のみ）                                                                                                              |
| `uiResource`     | エージェントが生成した UI のメタ情報（発生した場合のみ）。方式により `delta.uiResource`（Chat API）/ `uiResources[]`（MCP）/ `ui-resource-` artifact（A2A）として届きます         |
| `draft`          | チャットで作った下書きの、作る・変えるのに要る値を持つデータ（発生した場合のみ）。方式により `delta.draft`（Chat API）/ `drafts[]`（MCP）/ `ui-resource-` artifact のデータの部品（A2A）として届きます |

## インタラクション

エージェントがタスク実行中にユーザーの入力を必要とする場合、インタラクションが発生します。クライアントはインタラクションの種類に応じてユーザーに選択肢や確認を提示し、回答を同じ conversationId で送信して会話を継続します。

| 型              | 説明                    | クライアントの対応                          |
| -------------- | --------------------- | ---------------------------------- |
| `choice`       | 選択肢を提示し、ユーザーに1つを選択させる | 選択結果をテキストとして送信                     |
| `confirmation` | ユーザーに確認（承認/拒否）を求める    | 承認/拒否をテキストとして送信                    |
| `question`     | 1つ以上の設問への回答を求める       | 回答をテキストとして送信。選択肢のある設問でも選択肢は本文に含まれる |

質問に ID（`interactionId`）があるときは、回答に、どの質問への答えかの印を付けられます（ID の無い質問は、印を付けずに文で答えます）。付けると、その質問への答えとして記録され、月の利用の枠の上限に達していても答えられます。選択肢から選んだ答えなら、選んだ選択肢の番号（0〜9。最初が 0）も送ります。

| 方式               | 答えの印                                                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `Chat API / SSE` | ボディの `interactionReply`（`{ interactionId, optionIndex? }`）。`interactionId` は `delta.interaction.interactionId`                |
| `MCP`            | `execute_chat` の引数の `interactionReply`（同じ形）。`interactionId` は結果の `interaction.interactionId`                                  |
| `A2A`            | 印は付けません。答えを待つタスクの続きとして送ると、質問に ID（`metadata.interactionId`）があるときは自動で答えとして記録されます。選択肢の番号は `metadata.optionIndex`（質問に ID があるときだけ） |

SSE での具体的なフォーマットは[ストリーミングガイド — インタラクション](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md#deltainteraction)を参照してください。

## 会話の継続

エージェントとの対話は conversationId で管理されます。レスポンスに含まれる conversationId を次のリクエストに指定することで、文脈を維持した連続対話が可能です。conversationId を省略すると新しい会話が開始されます。

> **注記**
>
> 同一の conversationId に対して同時に複数のリクエストを送信することはできません（HTTP 409 Conflict）。前のリクエストの完了を待つか、キャンセルしてから新しいリクエストを送信してください。

## キャンセル

進行中のエージェント実行をキャンセルできます。キャンセル方法は接続方式によって異なります。

| プロトコル          | キャンセル方法                                             | 対象の指定                                |
| -------------- | --------------------------------------------------- | ------------------------------------ |
| Chat API / SSE | `POST /v1/chat/completions/{conversationId}/cancel` | パスパラメータ `conversationId`             |
| MCP            | `cancel_chat` ツール                                   | 引数 `conversationId`                  |
| A2A            | `tasks/cancel`（0.3）・`CancelTask`（1.0）               | `params.id` に、0.3 は会話 ID、1.0 はタスク ID |

いずれの方式も内部では同一のキャンセル処理に集約されます。A2A では、すでに終了しているタスクを止めようとすると `TaskNotCancelableError`（JSON-RPC エラーコード `-32002`）が返ります。0.3 では、回答待ちのタスクも止められません（1.0 では止められます）。MCP の `cancel_chat` は、すでに終了しているときもエラーにはならず、`conversationState` に `completed` または `not_found` を返します。

## Chat API / SSE

OpenAI 互換の Chat Completions API です。HTTP クライアントから直接呼び出し、SSE（Server-Sent Events）ストリーミングでリアルタイムにレスポンスを受信します。リクエスト・レスポンスの詳細仕様はユーザー API リファレンスを参照してください。

[ユーザー API リファレンス（Chat）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#chat)

[エンドポイント仕様・リクエストボディ・レスポンスヘッダー](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#chat)

[→](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/api-reference.md#chat)

[SSE ストリーミングガイド](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md)

[接続フロー・Delta 拡張・実行パターン・エラーハンドリング](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md)

[→](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/streaming-guide.md)

## MCP（Model Context Protocol）

MCP 対応の AI エージェント（Claude 等）から AGENTIC STAR に接続するためのインターフェースです。エージェントは接続時にツール定義を自動取得し、AGENTIC STAR のタスク実行・ファイル取得・キャンセル・プロジェクトの操作を自律的に行います。

### 接続仕様

| 項目      | 値                                             |
| ------- | --------------------------------------------- |
| エンドポイント | `POST /v1/mcp`                                |
| プロトコル   | `Streamable HTTP / JSON-RPC 2.0`              |
| 認証      | `Bearer JWT (scope: mcp:connect または mcp:all)` |
| モード     | `Stateless`                                   |

ツールとスコープは [MCP API リファレンス — 提供ツール](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/mcp-ref.md#%E6%8F%90%E4%BE%9B%E3%83%84%E3%83%BC%E3%83%AB)、AI クライアントの設定とつなぎ方は [AI クライアント接続ガイド（MCP）](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/ai-client-guide.md) を参照してください。

## A2A（Agent-to-Agent Protocol）

A2A プロトコル（0.3 と 1.0）対応のエージェントから AGENTIC STAR に接続するためのインターフェースです。クライアントエージェントは Agent Card からスキル情報を自動取得し、タスクの送信・ストリーミング・キャンセルを行います。

### 接続仕様

| 項目         | 値                                                       |
| ---------- | ------------------------------------------------------- |
| Agent Card | `GET /.well-known/agent-card.json`                      |
| エンドポイント    | `POST /v1/a2a`                                          |
| プロトコル      | `JSON-RPC 2.0`                                          |
| 認証         | `Bearer JWT（scope: a2a:connect と操作ごとのスコープ、または a2a:all）` |

### スキル一覧

| スキル名           | スコープ                                                           | 説明                                   |
| -------------- | -------------------------------------------------------------- | ------------------------------------ |
| `execute_task` | `a2a:all（または a2a:connect と chat:exec。ファイルを添えるときは chat:file も）` | エージェントにタスクを送信し、自律実行（agentMode: true） |
| `direct_llm`   | `a2a:all（または a2a:connect と chat:exec）`                         | LLM に直接問い合わせ（agentMode: false）       |

### サポートメソッド

| 0.3                 | 1.0                    | 説明                       |
| ------------------- | ---------------------- | ------------------------ |
| `message/send`      | `SendMessage`          | メッセージを送信し、完了まで待機         |
| `message/stream`    | `SendStreamingMessage` | メッセージを送信し、SSE でストリーミング受信 |
| `tasks/get`         | `GetTask`              | タスクの状態を取得                |
| `—`                 | `ListTasks`            | 1 つの会話のタスクの一覧を取得         |
| `tasks/cancel`      | `CancelTask`           | タスクをキャンセル                |
| `tasks/resubscribe` | `SubscribeToTask`      | SSE 切断後にタスクのストリーミングへ再接続  |

### 実行パラメータの指定

[共通リクエストパラメータ](#%E5%85%B1%E9%80%9A%E3%83%AA%E3%82%AF%E3%82%A8%E3%82%B9%E3%83%88%E3%83%91%E3%83%A9%E3%83%A1%E3%83%BC%E3%82%BF) の `agentMode` / `agentLevel` / `reportMode` / `personaKey` を A2A から指定する場合は、`message.metadata` の flat keys として渡します（Agent Card の `capabilities.extensions` で宣言）。

```json
{
  "message": {
    "parts": [{ "kind": "text", "text": "..." }],
    "metadata": {
      "agentMode": true,
      "agentLevel": "high_performance",
      "reportMode": "without",
      "personaKey": "concise"
    }
  }
}
```

いずれも省略可能です。省略時は `agentMode: true` / `agentLevel: "default"` / `reportMode: "with"` で実行され、`personaKey` 省略時はペルソナを適用しません。

### Agent Card

A2A クライアントは以下の URL から Agent Card を取得し、スキル・認証方式・ケイパビリティを自動的に把握します。Agent Card は版で 2 種類あり、リクエストヘッダー `A2A-Version: 1.0` を付けると 1.0 の形だけ、付けないと 0.3 と 1.0 の両方の項目を持つ 1 枚が返ります（[A2A API リファレンス — Agent Card](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/reference/a2a-ref.md#agent-card)）。

```text
GET https://api.fd.agenticstar.tm.softbank.jp/.well-known/agent-card.json
```

### Gemini Enterprise から呼ぶ

Google の Gemini Enterprise のエージェントの一覧に AGENTIC STAR を足し、Gemini Enterprise の利用者が AGENTIC STAR に頼めるようにする手順です。Gemini Enterprise が使うのは A2A 0.3 で、上の Agent Card（`A2A-Version` を付けずに取った物）をそのまま使います。Gemini Enterprise の側の画面は、Google の Preview の機能です。

1. Console で、Gemini Enterprise が使うアプリを作る（[Console ガイド — アプリケーションの作成手順](https://developers.fd.agenticstar.tm.softbank.jp/docs/saas/api/agent/guide/console-guide.md#%E3%82%A2%E3%83%97%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AE%E4%BD%9C%E6%88%90%E6%89%8B%E9%A0%86)）

   <!-- -->

   - アプリケーションの種類: Web アプリケーション
   - Redirect URI: `https://vertexaisearch.cloud.google.com/oauth-redirect` と `https://vertexaisearch.cloud.google.com/static/oauth/oauth.html`
   - スコープ: `a2a:connect`・`chat:exec`・`chat:history`

2. Gemini Enterprise のアプリの「Agents」>「Add Agents」で「Custom agent via A2A」を選び、「Agent card JSON」に Agent Card の JSON を貼る

3. 次の画面で、1 のアプリの Client ID と Client Secret、Agent Card の `securitySchemes` にある認可の URL（Authorization URI）とトークンの URL（Token URI）、1 のスコープを入れる

- Gemini Enterprise の地域は `global`・`us`・`eu` です
- この方法で登録したエージェントへの通信は、Google の Agent Gateway を通りません
- AGENTIC STAR の管理者がエージェントを止めているときは、Gemini Enterprise から呼んでも AGENTIC STAR が断ります
