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

接続方式ガイド

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

3 つの接続方式​

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

Chat API / SSEMCPA2A
プロトコルREST + SSEStreamable HTTP / JSON-RPCJSON-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 回の実行を始め、ファイル・会話の続き・質問・止めるはありません)。A2A API リファレンスを参照してください。

方式ごとの送信キー

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

  • Chat API / SSE: messages[].content(OpenAI 互換形式)
  • MCP: ツール引数の prompt
  • A2A: message.parts[] の文の部品の text(0.3 は kind: "text" が付き、1.0 は kind が付きません)

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

パラメータ型必須説明
promptstring必須エージェントへの指示テキスト
agentIdstring必須動かす登録 Agent の ID。MCP では list_agents が返す agentId を指定します。A2A ではエンドポイントの URL の {agentId} です。
conversationIdstring—既存の会話を継続する場合に指定。省略すると新しい会話が作成されます。
filesarray—添付ファイル。Chat API では事前アップロード + fileId、MCP では base64 エンコードで送信します。

レスポンスモデル​

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

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

インタラクション​

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

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

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

会話の継続​

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

注記

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

キャンセル​

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

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

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

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 リファレンス を参照してください。