Documentation Index
Fetch the complete documentation index at: https://docs.snorbe.deskrex.ai/llms.txt
Use this file to discover all available pages before exploring further.
エージェント実行
リサーチエージェントを直接実行します。エージェントの実行が完了するまでレスポンスを返しません（同期実行）。
クライアントタイムアウトの注意点。 このエンドポイントは executeAgentRun が
LLM 推論・ツール実行（ブラウジング/検索）・RAG・グラフ抽出をすべて完了するまで
HTTP コネクションを保持します。エージェント実行はタスク内容により 10秒〜数分 かかります。クライアント側のタイムアウト（多くのHTTPライブラリでデフォルト 30〜120秒）で切断された
場合、サーバー側は最後まで実行を続けます が、結果はチャット履歴に積まれるだけで
呼び出し元には返りません。後から GET /turn/list で回収できます。推奨: 単純な Q&A を超える用途では エージェント実行（ストリーミング）
を使ってください。SSE は最初のイベントで即 runId が返り、切断時は /agent/run/stream/{runId}
で再接続できます。非ストリーミングで使う場合はクライアント側の timeout を
最低300秒 に設定してください。 リクエスト
ヘッダー
| ヘッダー | 必須 | 説明 |
|---|
Authorization | はい | Bearer snorbe_... 形式の API キー |
Content-Type | はい | application/json |
リクエストボディ
{
"modelName": "gpt-5-mini-2025-08-07",
"inputText": "半導体の最新トレンドを調べて",
"promptKey": "chat-routing",
"locale": "ja",
"fileUrls": []
}
パラメータ
| パラメータ | 型 | 必須 | 説明 |
|---|
modelName | string | はい | 使用するモデル名 |
inputText | string | はい | エージェントへの入力テキスト |
promptKey | string | はい | プロンプトキー（通常は "chat-routing"） |
locale | string | はい | "ja" または "en" |
fileUrls | string[] | いいえ | 添付ファイル URL（最大10件）。デフォルト: [] |
agentId | string | いいえ | エージェント ID。省略時はデフォルトエージェント |
mentions | Mention[] | いいえ | @メンション（エンティティ・AgentRun・ソース・他 Agent の参照）。デフォルト: []。type: "agent" を含めると、呼び出し先が mentionAgent 経由で指名 Agent に委譲できる。詳細は「Agent 間メンション委譲」セクション |
maxBrowsingSteps | number | いいえ | ブラウジングの最大ステップ数（1-100） |
maxChainSteps | number | いいえ | Agent 間メンション連鎖の最大深さ（1-50、デフォルト 10）。再帰的な mentionAgent ファンアウトがこの値に達すると打ち止められる |
maxRetries | number | いいえ | リトライ回数（0-5） |
retryDelayMs | number | いいえ | リトライ間隔（ms、0-10000） |
includeOthersEntities | boolean | いいえ | 他ユーザーのエンティティも RAG 検索対象にする。デフォルト: true |
extendedContextEnabled | boolean | いいえ | 拡張コンテキスト（モデル最大トークンの 80% を使用）。デフォルト: false |
matrixEditContext | object | いいえ | マトリクス編集コンテキスト（sourceRunId + selection） |
matrixContinueContext | object | いいえ | マトリクス継続コンテキスト（sourceRunId） |
matrixSelectionContent | string | いいえ | マトリクス選択 XML（<matrix_selection> 形式） |
workspaceId は不要です。API キーから自動的に取得されます。
レスポンス
{
"text": "調査結果...",
"finishReason": "stop",
"model": {
"id": "gpt-5-mini-2025-08-07",
"provider": "openai"
},
"runId": "clxyz...",
"status": "completed",
"assistantTurnId": "clxyz...",
"agentId": "clxyz...",
"agentName": "agent"
}
レスポンスフィールド
| フィールド | 型 | 説明 |
|---|
text | string | エージェントの応答テキスト |
finishReason | string | 終了理由（"stop"、"tool-calls" 等） |
model | object | 使用したモデル情報 |
runId | string | エージェント実行 ID |
status | string | 実行ステータス（"completed"、"error" 等） |
使用例
curl -X POST "https://app.snorbe.deskrex.ai/api/v1/agent/run" \
-H "Authorization: Bearer snorbe_your_api_key_here" \
-H "Content-Type: application/json" \
-d '{
"modelName": "gpt-5-mini-2025-08-07",
"inputText": "半導体の最新トレンドを調べて",
"promptKey": "chat-routing",
"locale": "ja"
}'
ラン完了後の詳細データ取得
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 体指名
{
"inputText": "[agent-beta](agent://b-id) さんに「好きな色を一言で」と聞いて",
"mentions": [
{ "id": "b-id", "type": "agent", "label": "agent-beta" }
]
}
- 呼び出し先 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 は続行
エラーレスポンス
| HTTP ステータス | コード | 説明 |
|---|
| 400 | BAD_REQUEST | バリデーションエラー |
| 401 | UNAUTHORIZED | API キーが無効 |
| 429 | TOO_MANY_REQUESTS | レート制限超過 |
| 500 | INTERNAL_SERVER_ERROR | エージェント実行エラー |
