> ## 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.
# エージェント実行
> リサーチエージェントを直接実行する API
# エージェント実行
リサーチエージェントを直接実行します。エージェントの実行が完了するまでレスポンスを返しません（同期実行）。
**クライアントタイムアウトの注意点。** このエンドポイントは `executeAgentRun` が
LLM 推論・ツール実行（ブラウジング/検索）・RAG・グラフ抽出をすべて完了するまで
HTTP コネクションを保持します。エージェント実行はタスク内容により **10秒〜数分** かかります。
クライアント側のタイムアウト（多くのHTTPライブラリでデフォルト 30〜120秒）で切断された
場合、**サーバー側は最後まで実行を続けます** が、結果はチャット履歴に積まれるだけで
呼び出し元には返りません。後から [`GET /turn/list`](/ja/api-reference/list-turns) で回収できます。
**推奨**: 単純な Q\&A を超える用途では [エージェント実行（ストリーミング）](/ja/api-reference/stream-agent-run)
を使ってください。SSE は最初のイベントで即 `runId` が返り、切断時は `/agent/run/stream/{runId}`
で再接続できます。非ストリーミングで使う場合はクライアント側の timeout を
**最低300秒** に設定してください。
## リクエスト
```
POST /api/v1/agent/run
```
### ヘッダー
| ヘッダー | 必須 | 説明 |
| --------------- | -- | ------------------------------ |
| `Authorization` | はい | `Bearer snorbe_...` 形式の API キー |
| `Content-Type` | はい | `application/json` |
### リクエストボディ
```json theme={null}
{
"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（`` 形式） |
`workspaceId` は不要です。API キーから自動的に取得されます。
## レスポンス
```json theme={null}
{
"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"` 等） |
## 使用例
```bash cURL theme={null}
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"
}'
```
```python Python theme={null}
import requests
# timeout は長めに設定する。エージェント実行はツール使用・RAG・グラフ抽出により
# 数分かかることが普通。クライアントタイムアウトでもサーバー側は完走するので、
# 切断した場合は GET /turn/list で結果を回収する。
resp = requests.post(
"https://app.snorbe.deskrex.ai/api/v1/agent/run",
headers={
"Authorization": "Bearer snorbe_your_api_key_here",
"Content-Type": "application/json",
},
json={
"modelName": "gpt-5-mini-2025-08-07",
"inputText": "半導体の最新トレンドを調べて",
"promptKey": "chat-routing",
"locale": "ja",
},
timeout=600,
)
data = resp.json()
print(data["text"])
print(f"Run ID: {data['runId']}")
```
```typescript TypeScript theme={null}
const resp = await fetch("https://app.snorbe.deskrex.ai/api/v1/agent/run", {
method: "POST",
headers: {
Authorization: "Bearer snorbe_your_api_key_here",
"Content-Type": "application/json",
},
body: JSON.stringify({
modelName: "gpt-5-mini-2025-08-07",
inputText: "半導体の最新トレンドを調べて",
promptKey: "chat-routing",
locale: "ja",
}),
});
const data = await resp.json();
console.log(data.text);
console.log(`Run ID: ${data.runId}`);
```
## ラン完了後の詳細データ取得
`GET /agent/run/{runId}/status` は軽量（`status` と `pending*Draft` フラグのみ）です。
**ラン後の詳細（ブラウズ手順・ツール呼び出し・プラン/レポート/マトリクスドラフト・
グラフ抽出イベント・参照ソース）を取得するには
[`GET /turn/list`](/ja/api-reference/list-turns) を使ってください**。
各ターンエントリには次が含まれます:
* `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 体指名
```json theme={null}
{
"inputText": "[agent-beta](agent://b-id) さんに「好きな色を一言で」と聞いて",
"mentions": [
{ "id": "b-id", "type": "agent", "label": "agent-beta" }
]
}
```
処理の流れ:
1. 呼び出し先 Agent（例: agent-alpha）の run が開始
2. LLM が `mentionAgent` tool を選択し、最終メッセージに `[@agent-beta](agent://b-id) 好きな色を一言で` を出力
3. alpha の run 完了後、サーバが自動で agent-beta の新しい AgentRun を起動（入力 = alpha の最終メッセージ）
4. 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` | エージェント実行エラー |