エージェント実行
リサーチエージェントを直接実行します。エージェントの実行が完了するまでレスポンスを返しません(同期実行)。
クライアントタイムアウトの注意点。 このエンドポイントは executeAgentRun が
LLM 推論・ツール実行(ブラウジング/検索)・RAG・グラフ抽出をすべて完了するまで
HTTP コネクションを保持します。エージェント実行はタスク内容により 10秒〜数分 かかります。クライアント側のタイムアウト(多くのHTTPライブラリでデフォルト 30〜120秒)で切断された
場合、サーバー側は最後まで実行を続けます が、結果はチャット履歴に積まれるだけで
呼び出し元には返りません。後から GET /turn/list で回収できます。推奨: 単純な Q&A を超える用途では エージェント実行(ストリーミング)
を使ってください。SSE は最初のイベントで即 runId が返り、切断時は /agent/run/stream/{runId}
で再接続できます。非ストリーミングで使う場合はクライアント側の timeout を
最低300秒 に設定してください。
リクエスト
ヘッダー
リクエストボディ
パラメータ
workspaceId は不要です。API キーから自動的に取得されます。
レスポンス
レスポンスフィールド
使用例
ラン完了後の詳細データ取得
GET /agent/run/{runId}/status は軽量(status と pending*Draft フラグのみ)です。
ラン後の詳細(ブラウズ手順・ツール呼び出し・プラン/レポート/マトリクスドラフト・
グラフ抽出イベント・参照ソース)を取得するには
GET /turn/list を使ってください。
各ターンエントリには次が含まれます:
agentRun.process — 実行中に発行された全 SSE イベントの永続化タイムライン
(config・delta・step・browse-*・plan-*・report-structure-*・
matrix-*・source-summary-*・graph-* すべて)
agentRun.publicSourceAgentRuns / privateSourceAgentRuns — エージェントが
参照した URL ソース(bodyLinks のメタデータ含む)
agentRun.agent — エージェント情報
runId を直接指定して取得するエンドポイントは提供されていません。特定の runId
を探すには /turn/list を降順でページングし、turns[].agentRun.id と照合してください。
Agent 間メンション委譲
mentions に type: "agent" を含めると、呼び出し先 Agent が実行中に指名先 Agent へ委譲できます。
1 体指名
処理の流れ:
- 呼び出し先 Agent(例: agent-alpha)の run が開始
- LLM が
mentionAgent tool を選択し、最終メッセージに [@agent-beta](agent://b-id) 好きな色を一言で を出力
- alpha の run 完了後、サーバが自動で agent-beta の新しい AgentRun を起動(入力 = alpha の最終メッセージ)
- beta は独立した run として応答し、チャット履歴に積まれる
レスポンスの runId は親 run(alpha)のみです。child run(beta)の結果を取得するには /turn/list または /agent/run/{childRunId}/status を使います。
2 体以上指名
2 体以上 mention すると、サーバ側 LLM 分類器が文意から parallel / chain を自動判定します。
- parallel(独立意見): 全 Agent を並列実行。例: 「A と B にそれぞれ意見ください」
- chain(順序依存): primary が先行実行し、
mentionAgent で他 Agent に連鎖。例: 「A が企画を作って、それを B がレビューして」
ガード
- 自己ループ防止: 指名先 agentId が呼び出し元と同一なら spawn しない
- 深度制限:
maxChainSteps(1-50、default 10)で再帰的 mentionAgent ファンアウトを打ち止め
- エラー隔離: 1 つの child が失敗しても他の siblings の spawn は続行
エラーレスポンス