メインコンテンツまでスキップ

接続方式ガイド

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

3つの接続方式​

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

Chat API / SSEMCPA2A
プロトコルREST + SSEStreamable HTTP / JSON-RPCJSON-RPC
エンドポイント/v1/chat/completions/v1/mcp/v1/a2a
スコープchat:execmcp:connect / mcp:alla2a: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 / MCP / A2A)を参照してください。

パラメータ型必須説明
prompt / textstring必須エージェントへの指示テキスト
conversationIdstring—既存の会話を継続する場合に指定。省略すると新しい会話が作成されます。
agentModeboolean—true(デフォルト)= 自律エージェント実行。false = LLM 直接応答。
agentLevelstring—"default"(デフォルト)または "high_performance"。エージェントの推論に使用する LLM モデルを切り替えます。
reportModestring—"with"(デフォルト)または "without"。完了時に作業報告書を生成するかを制御します。
personaKeystring—エージェントの応答人格(ペルソナ)。GET /v1/personas(MCP は list_personas)が返す personaKey を指定。省略時は適用なし。
filesarray—添付ファイル。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ユーザーに確認(承認/拒否)を求める承認/拒否をテキストとして送信
question1つ以上の設問への回答を求める回答をテキストとして送信。選択肢のある設問でも選択肢は本文に含まれる

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

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

SSE での具体的なフォーマットはストリーミングガイド — インタラクションを参照してください。

会話の継続​

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

注記

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

キャンセル​

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

プロトコルキャンセル方法対象の指定
Chat API / SSEPOST /v1/chat/completions/{conversationId}/cancelパスパラメータ conversationId
MCPcancel_chat ツール引数 conversationId
A2Atasks/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 リファレンスを参照してください。

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 リファレンス — 提供ツール、AI クライアントの設定とつなぎ方は AI クライアント接続ガイド(MCP) を参照してください。

A2A(Agent-to-Agent Protocol)​

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

接続仕様​

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

スキル一覧​

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

サポートメソッド​

0.31.0説明
message/sendSendMessageメッセージを送信し、完了まで待機
message/streamSendStreamingMessageメッセージを送信し、SSE でストリーミング受信
tasks/getGetTaskタスクの状態を取得
—ListTasks1 つの会話のタスクの一覧を取得
tasks/cancelCancelTaskタスクをキャンセル
tasks/resubscribeSubscribeToTaskSSE 切断後にタスクのストリーミングへ再接続

実行パラメータの指定​

共通リクエストパラメータ の 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)。

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 ガイド — アプリケーションの作成手順)
    • アプリケーションの種類: 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 が断ります