# 接続方式ガイド

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/agents/{agentId}/・/v1/a2a/projects/{projectId}/` |
| トークン     | `アプリケーションまたはシステム連携`                   | `アプリケーションまたはシステム連携`                      | `アプリケーションまたはシステム連携`                                       |
| ディスカバリー  | `なし（API仕様を参照）`                        | `tools/list で自動取得`                       | `Agent Card（トークンが必要）`                                     |
| 想定クライアント | `自社アプリ / HTTP クライアント`                 | `Claude Code・Codex など MCP 対応の AI クライアント` | `A2A 対応のエージェント・アプリケーション`                                  |
| ドキュメント詳細 | `ユーザー API リファレンス・システム連携 API リファレンス参照` | `下記参照`                                   | `下記参照`                                                    |

### 方式の選び方

> **どの方式を選ぶべきか**
>
> - **Chat API / SSE** — 自社アプリケーションにエージェント機能を組み込む場合。リクエスト・レスポンスを自分で制御できます。
> - **MCP** — Claude Code・Codex などの MCP 対応の AI クライアントから AGENTIC STAR に接続する場合。クライアントがツール定義を自動取得します。MCP は、管理者が MCP の受け口を開けた環境でだけ使えます。
> - **A2A** — A2A に対応した外のエージェントやアプリケーションから、登録 Agent や公開したワークフローを呼ぶ場合。A2A は、管理者が受け口を開け、標準のトークンエンドポイントを設定した環境でだけ使えます。

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

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

A2A のうち、公開したワークフローのエンドポイントは、この節の共通の形とは違います（1 つのメッセージで 1 回の実行を始め、ファイル・会話の続き・質問はありません。止めると、その実行（run）が中断されます）。[A2A API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/a2a-ref.md)を参照してください。

> **方式ごとの送信キー**
>
> パラメータ名は概念上の共通名です。実際のキーや構造は方式ごとに異なります:
>
> - **Chat API / SSE**: `messages[].content`（OpenAI 互換形式）
> - **MCP**: ツール引数の `prompt`
> - **A2A**: `message.parts[]` の文の部品の `text`（0.3 は `kind: "text"` が付き、1.0 は `kind` が付きません）
>
> 詳細は各方式のセクション（[Chat API](#chat-api--sse) / [MCP](#mcpmodel-context-protocol) / [A2A](#a2aagent-to-agent-protocol)）を参照してください。

| パラメータ            | 型        | 必須 | 説明                                                                                                                                                    |
| ---------------- | -------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`         | `string` | 必須 | エージェントへの指示テキスト                                                                                                                                        |
| `agentId`        | `string` | 必須 | 動かす登録 Agent の ID。チャットでは `GET /v1/marketplace-agents` が返す marketplaceAgentId、MCP では list\_agents が返す agentId を指定します。A2A ではエンドポイントの URL の {agentId} です。 |
| `conversationId` | `string` | —  | 既存の会話を継続する場合に指定。省略すると新しい会話が作成されます。                                                                                                                    |
| `files`          | `array`  | —  | 添付ファイル。Chat API では事前アップロード + fileId、MCP では base64 エンコードで送信します。                                                                                        |

## レスポンスモデル

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

| 要素               | 説明                                        |
| ---------------- | ----------------------------------------- |
| `text`           | エージェントの応答テキスト                             |
| `conversationId` | 会話 ID。次回のリクエストで指定すると会話を継続できます。            |
| `deliverables`   | エージェントが生成した成果物ファイルの一覧（ファイル名、パス、MIME タイプ等） |
| `executionSteps` | エージェントの実行トレース（ツール呼び出し、コード実行等のステップ詳細）      |
| `interaction`    | ユーザーへの対話リクエスト（発生した場合のみ）                   |

## インタラクション

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

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

<!-- -->

SSE での具体的なフォーマットは[ストリーミングガイド — インタラクション](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/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（登録 Agent）  | `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/marketplace/api/reference/user-api-reference.md#chat)

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

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

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

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

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

## MCP（Model Context Protocol）

MCP 対応の AI クライアント（Claude Code・Codex など）から AGENTIC STAR に接続するためのインターフェースです。クライアントは接続時にツール定義を自動取得し、登録 Agent への依頼・ファイルの取得・キャンセル・プロジェクトの操作・公開したワークフローの実行を行います。

### 接続仕様

| 項目      | 値                                                              |
| ------- | -------------------------------------------------------------- |
| エンドポイント | `POST /v1/mcp`                                                 |
| プロトコル   | `Streamable HTTP / JSON-RPC 2.0`                               |
| 認証      | `Bearer JWT（アプリケーションの利用者のトークン、またはシステム連携のトークン。スコープによる制限はありません）` |
| モード     | `Stateless`                                                    |

ツールは [MCP API リファレンス — 提供ツール](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/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/marketplace/api/guide/ai-client-guide.md) を参照してください。

## A2A（Agent-to-Agent Protocol）

A2A（0.3 と 1.0）に対応した外のエージェントやアプリケーションから、AGENTIC STAR の登録 Agent と公開したワークフローを呼ぶためのインターフェースです。登録 Agent と公開したワークフローごとにエンドポイントと Agent Card があり、クライアントは Agent Card からスキルと認証方式を取得します。

### 接続仕様

| 項目                  | 値                                                              |
| ------------------- | -------------------------------------------------------------- |
| エンドポイント（登録 Agent）   | `POST /v1/a2a/agents/{agentId}/`                               |
| エンドポイント（公開したワークフロー） | `POST /v1/a2a/projects/{projectId}/`                           |
| Agent Card          | `各エンドポイントの .well-known/agent-card.json（トークンが必要）`               |
| プロトコル               | `JSON-RPC 2.0`                                                 |
| 認証                  | `Bearer JWT（アプリケーションの利用者のトークン、またはシステム連携のトークン。スコープによる制限はありません）` |

登録 Agent のエンドポイントは、チャットと同じく会話でタスクを進めます。公開したワークフローのエンドポイントは、1 つのメッセージで 1 回の実行（run）を始めます。メソッド・入力・エラーの詳細は [A2A API リファレンス](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/reference/a2a-ref.md) を参照してください。
