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

接続方式ガイド

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:alla2a:all
ディスカバリーなし（API仕様を参照）tools/list で自動取得Agent Card で自動取得
想定クライアント自社アプリ / HTTP クライアントClaude / MCP 対応 AI エージェントA2A 対応 AI エージェント
対応エディションSaaS / MarketplaceSaaSSaaS
ドキュメント詳細ユーザー API リファレンス参照下記参照下記参照
マーケットプレイス版をご利用の方へ

マーケットプレイス版で利用できる接続方式は Chat API / SSE のみ です。MCP / A2A は SaaS 版専用の機能です。

方式の選び方​

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

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

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

方式ごとの送信キー

パラメータ名は概念上の共通名です。実際のキーや構造は方式ごとに異なります:

  • Chat API / SSE: messages[].content（OpenAI 互換形式）
  • MCP: ツール引数の prompt
  • A2A: message.parts[] 内 kind: "text" の text

詳細は各方式のセクション（Chat API / MCP / A2A）を参照してください。

パラメータ型必須説明
prompt / textstring必須エージェントへの指示テキスト
conversationIdstring—既存の会話を継続する場合に指定。省略すると新しい会話が作成されます。
agentModeboolean—true（デフォルト）= 自律エージェント実行。false = LLM 直接応答。
agentLevelstring—"default"（デフォルト）または "high_performance"。エージェントの推論に使用する LLM モデルを切り替えます。
filesarray—添付ファイル。Chat API では事前アップロード + fileId、MCP では base64 エンコードで送信します。

レスポンスモデル​

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

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

インタラクション​

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

型説明クライアントの対応
choice選択肢を提示し、ユーザーに1つを選択させる選択結果をテキストとして送信
confirmationユーザーに確認（承認/拒否）を求める承認/拒否をテキストとして送信

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

会話の継続​

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

注記

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

キャンセル​

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

プロトコルキャンセル方法
Chat API / SSEPOST /v1/chat/completions/{conversationId}/cancel
MCP（SaaS のみ）cancel_chat ツールを呼び出し
A2A（SaaS のみ）tasks/cancel メソッドを送信

Chat API / SSE​

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

ユーザー API リファレンス（Chat）
エンドポイント仕様・リクエストボディ・レスポンスヘッダー
→
SSE ストリーミングガイド
接続フロー・Delta 拡張・実行パターン・エラーハンドリング
→

MCP（Model Context Protocol） SaaS​

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

接続仕様​

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

ツール一覧​

ツール名スコープ説明
execute_chatmcp:allエージェントにタスクを送信し、実行結果を取得
get_file_contentmcp:allエージェントが生成した成果物ファイルをダウンロード
cancel_chatmcp:all進行中のタスクをキャンセル

接続設定例​

MCP クライアントの設定ファイルに以下を追加します。

JSON
{
  "mcpServers": {
    "agenticstar": {
      "url": "https://api.fd.agenticstar.tm.softbank.jp/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer <access_token>"
      }
    }
  }
}

A2A（Agent-to-Agent Protocol） SaaS​

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

接続仕様​

項目値
Agent CardGET /.well-known/agent-card.json
エンドポイントPOST /v1/a2a
プロトコルJSON-RPC 2.0
認証Bearer JWT (scope: a2a:all)

スキル一覧​

スキル名スコープ説明
execute_taska2a:allエージェントにタスクを送信し、自律実行（agentMode: true）
direct_llma2a:allLLM に直接問い合わせ（agentMode: false）

サポートメソッド​

メソッド説明
message/sendメッセージを送信し、完了まで待機
message/streamメッセージを送信し、SSE でストリーミング受信
tasks/getタスクの状態を取得
tasks/cancelタスクをキャンセル
tasks/resubscribeSSE 切断後にタスクのストリーミングへ再接続（途中から再開）

実行パラメータの指定​

共通リクエストパラメータ の agentMode / agentLevel を A2A から指定する場合は、message.metadata の flat keys として渡します（Agent Card の capabilities.extensions で宣言）。

JSON
{
  "message": {
    "parts": [{ "kind": "text", "text": "..." }],
    "metadata": {
      "agentMode": true,
      "agentLevel": "high_performance"
    }
  }
}

両方とも省略可能です。省略時は agentMode: true / agentLevel: "default" で実行されます。

Agent Card​

A2A クライアントは以下の URL から Agent Card を取得し、スキル・認証方式・ケイパビリティを自動的に把握します。

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