エージェントとの会話

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

3つの接続方式

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

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

方式の選び方

どの方式を選ぶべきか

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

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

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

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

実行パス

タスクの複雑度に応じて、エージェントが自動的に実行パスを選択します。開発者側での指定は不要です。どの接続方式でも同じ動作です。

Simple Path

LLM が直接応答を生成するパス。通常のチャット応答やシンプルな質問で使用されます。数秒で完了します。

Complex Path

エージェントがツールを使って自律的にタスクを実行するパス。Web 検索、ファイル操作、コード実行等を含む長時間タスクで使用されます。30 秒〜数分かかります。

レスポンスモデル

どの接続方式でも、エージェントの応答には以下の情報が含まれます。フォーマットはプロトコルごとに異なりますが、内容は同じです。

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

インタラクション

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

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

会話の継続

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

注記

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

キャンセル

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

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

Task データモデル

エージェントがツール実行・ファイル操作・検索などのアクションを行うたびに、Task オブジェクトが生成されます。このデータモデルは Chat API / SSE、MCP、A2A の全プロトコルで共通です。

Task オブジェクトフィールド

パラメータ	型	必須	説明
`messageId`	`string`	✓	タスクが属するメッセージの ID
`conversationId`	`string`	✓	タスクが属する会話の ID
`actionType`	`string`	✓	アクション種別。詳細は下記の actionType 一覧を参照
`status`	`string`	✓	タスクの状態: "pending" \| "in_progress" \| "completed" \| "failed" \| "success" \| "error"。値は actionType とデータパスにより異なる
`timestamp`	`number`	✓	タスクのタイムスタンプ（Unix ミリ秒）
`createdAt`	`string`	✓	タスク作成日時（ISO 8601）
`updatedAt`	`string`	✓	タスク更新日時（ISO 8601）
`title`	`string`		タスクのタイトル（表示用）
`description`	`string`		タスクの詳細説明
`callId`	`string \| null`		ツール呼び出し ID。tool_start と対応する tool_result を紐付ける。file_operation / search_result / mcp_tool では null
`content`	`string`		タスクの出力コンテンツ
`metadata`	`object`		タスクのメタデータ。actionType に応じて異なるフィールドを含む
`files`	`TaskFile[]`		タスクに関連するファイルの配列

TaskFile オブジェクトフィールド

パラメータ	型	説明
`filename`	`string`	ファイル名
`fileType`	`string`	ファイル種別: "image" \| "pdf" \| "pptx" \| "text" \| "video" \| "other"
`size`	`number`	ファイルサイズ（バイト）
`filepath`	`string`	ファイルパス（相対パスまたは URL）

タスクライフサイクル

tool_start は特定のツール（local_assistant / generate_video / Sandbox）でのみ送信されます。対応する結果イベント（tool_result 等）と callId で紐付けできます。search_result / command_execution / mcp_tool / file_operation は tool_start なしで単独送信されます（callId は null）。

JSON
// パターン A: tool_start → tool_result ペア（callId で紐付け）
// local_assistant / generate_video / Sandbox のみ
{ "actionType": "tool_start", "callId": "0cf24f34-...", ... }
{ "actionType": "tool_result", "callId": "0cf24f34-...", ... }

// パターン B: 単独送信（callId は null）
{ "actionType": "search_result", "callId": null, ... }
{ "actionType": "file_operation", "callId": null, ... }
{ "actionType": "mcp_tool", "callId": null, ... }

// パターン C: tool_start なし + callId あり（LLM の call_id が保持される場合）
{ "actionType": "tool_result", "callId": "call_T3GIhcQQ...", ... }

actionType 一覧

actionType はタスクの種別を示します。tool_start は特定ツールのみで送信され、その他は結果イベントとして単独で送信されます。

actionType	フェーズ	説明	対象ツール例
`tool_start`	開始	特定ツールの開始通知。Sandbox 準備を含む	local_assistant, generate_video, Sandbox
`tool_result`	完了	汎用ツール実行の結果。metadata.sub_event_type でツール種別を識別	bash, read, write, edit, multiedit, grep, glob, ls, webfetch, task, local_assistant, generate_video, generation_image, create_slide
`search_result`	完了	Web 検索の完了結果	search_web
`command_execution`	完了	シェルコマンド実行の完了結果	execute_command
`mcp_tool`	完了	MCP ツール実行の結果（metadata なし）	mcp_tool, Perplexity
`file_operation`	単独	ファイル作成の完了通知（files[] を含む）	—

actionType 別の metadata 構造

metadata フィールドの内容は actionType によって異なります。以下に代表的なパターンを示します。

tool_start

local_assistant / generate_video / Sandbox で送信される開始通知です。

JSON
{
  "actionType": "tool_start",
  "callId": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
  "title": "local assistant",
  "description": "Processing local_assistant",
  "status": "in_progress",
  "metadata": {
    "tool_name": "local_assistant",
    "call_id": "0cf24f34-bbd9-4833-88c4-d7f520ce3aae",
    "status": "starting"
  }
}

search_result

Web 検索完了時の metadata には検索クエリ・結果件数・検索結果配列が含まれます。

JSON
{
  "actionType": "search_result",
  "status": "completed",
  "title": "Web 検索を実行しました",
  "description": "「AI market trends 2026」を検索しました",
  "metadata": {
    "query": "AI market trends 2026",
    "searchType": "web",
    "searchEngine": "brave",
    "resultCount": 5,
    "results": [
      { "title": "...", "url": "...", "description": "..." }
    ]
  },
  "timestamp": 1710410000000
}

command_execution

シェルコマンド実行結果の metadata にはコマンド・終了コード・出力が含まれます。

JSON
{
  "actionType": "command_execution",
  "status": "success",
  "callId": null,
  "metadata": {
    "command": "npm test",
    "exitCode": 0,
    "output": "Tests passed: 42/42",
    "errorOutput": "",
    "workingDirectory": "/workspace"
  }
}

mcp_tool

MCP ツール結果には metadata フィールドが含まれません。title と description にツール情報が設定されます。

JSON
{
  "actionType": "mcp_tool",
  "status": "in_progress",
  "callId": null,
  "title": "Perplexity",
  "description": "Perplexityを実行"
}

file_operation

ファイル作成完了時の Task には files[] 配列が含まれます。

JSON
{
  "actionType": "file_operation",
  "status": "completed",
  "callId": null,
  "metadata": {
    "operationType": "create",
    "filePaths": ["/home/ubuntu/todo.md"]
  },
  "files": [{
    "filename": "todo.md",
    "fileType": "text",
    "size": 1918,
    "filepath": "/plans/conv-id/files/todo.md"
  }]
}

tool_result

汎用ツール結果の metadata にはツール固有のフィールドと sub_event_type が含まれます。sub_event_type でツール種別を識別できます。

bash (sub_event_type: bash_executed)

JSON
{
  "actionType": "tool_result",
  "callId": "call_T3GIhcQQft13amxdhcJ4cBDz",
  "title": "success",
  "description": "{'result': 'ok'}",
  "status": "in_progress",
  "metadata": {
    "tool_name": "bash",
    "call_id": "call_T3GIhcQQft13amxdhcJ4cBDz",
    "sub_event_type": "bash_executed",
    "command": "python3 script.py",
    "exit_code": 0,
    "stdout": "{'result': 'ok'}\n",
    "stderr": "",
    "status": "success",
    "duration_ms": 24,
    "working_dir": "/opt/.autonomous_agent/.sandbox-runtime",
    "title": "Execute: python3 script.py"
  }
}

write (sub_event_type: file_edited)

JSON
{
  "actionType": "tool_result",
  "title": "created",
  "description": "File created: /workspace/src/app.py",
  "status": "in_progress",
  "metadata": {
    "tool_name": "write",
    "sub_event_type": "file_edited",
    "file_path": "/workspace/src/app.py",
    "lines_written": 45,
    "status": "created"
  }
}

代表的なツール一覧

tool_result の metadata.tool_name および metadata.sub_event_type でツール種別を識別できます。以下は代表的なツールです。

tool_name	説明
`bash`	Bash コマンド実行
`read`	ファイル読取
`write / edit / multiedit`	ファイル書込・編集
`grep / glob / ls`	ファイル検索
`webfetch`	Web ページ取得
`task`	サブタスク起動
`generate_video`	動画生成

Chat API / SSE

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

Chat API リファレンス

エンドポイント仕様・リクエストボディ・レスポンスヘッダー

→

SSE ストリーミングガイド

接続フロー・Delta 拡張・実行パターン・エラーハンドリング

→

MCP（Model Context Protocol）

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

接続仕様


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

ツール一覧

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

接続設定例

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

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

A2A（Agent-to-Agent Protocol）

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

接続仕様


Agent Card	`GET /.well-known/agent-card.json`
エンドポイント	`POST /v1/a2a`
プロトコル	`JSON-RPC 2.0`
認証	`Bearer JWT (scope: a2a:exec)`

スキル一覧

スキル名	スコープ	説明
`execute_task`	`a2a:exec`	エージェントにタスクを送信し、自律実行（agentMode: true）
`direct_llm`	`a2a:exec`	LLM に直接問い合わせ（agentMode: false）

サポートメソッド

メソッド	説明
`message/send`	メッセージを送信し、完了まで待機
`message/stream`	メッセージを送信し、SSE でストリーミング受信
`tasks/get`	タスクの状態を取得
`tasks/cancel`	タスクをキャンセル

Agent Card

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

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

3つの接続方式​

方式の選び方​

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

実行パス​

レスポンスモデル​

インタラクション​

会話の継続​

キャンセル​

Task データモデル​

Task オブジェクト フィールド​

TaskFile オブジェクト フィールド​

タスクライフサイクル​

actionType 一覧​

actionType 別の metadata 構造​

tool_start​

search_result​

command_execution​

mcp_tool​

file_operation​

tool_result​

代表的なツール一覧​

Chat API / SSE​

MCP（Model Context Protocol）​

接続仕様​

ツール一覧​

接続設定例​

A2A（Agent-to-Agent Protocol）​

接続仕様​

スキル一覧​

サポートメソッド​

Agent Card​

3つの接続方式

方式の選び方

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

実行パス

レスポンスモデル

インタラクション

会話の継続

キャンセル

Task データモデル

Task オブジェクトフィールド

TaskFile オブジェクトフィールド

タスクライフサイクル

actionType 一覧

actionType 別の metadata 構造

tool_start

search_result

command_execution

mcp_tool

file_operation

tool_result

代表的なツール一覧

Chat API / SSE

MCP（Model Context Protocol）

接続仕様

ツール一覧

接続設定例

A2A（Agent-to-Agent Protocol）

接続仕様

スキル一覧

サポートメソッド

Agent Card