Agent runs

agent run は自律タスクです：モデルが自ら計画し、ツール（Web、コード、ワークスペースのデータ、ファイル作成、実際のブラウザ）を呼び出し、検証し、結果を提供します——ステップごとにストリーミングされます。チャットとは異なり、タスクをエンドツーエンドで引き受けます。

run の開始

POST/v1/workspaces/{workspace_id}/agent/runs —

run を開始します。run は接続と切り離されています：このエンドポイントは小さな JSON オブジェクトを即座に返し、エンジンは切り離されたまま処理を続けます。ライブストリームは GET …/attach（後述）で追跡します。

最小限の連携——フィールド 1 つだけ。 {"task": "…"} を送るだけで完了です。プラットフォームが最適なモデルへ自動ルーティングし、適切なツール（Web 検索、あなたのナレッジベース、コード、ブラウザ……）を自動で選んで呼び出し、結果をストリーミングで返します。ツール、モデル、プロンプトを自ら結線する必要はありません——以下の他のすべてのボディフィールドは、さらに制御したいときのための任意の上書き項目です。コピペできる完全な例は Cookbook を参照してください。

POST は {"run_id", "trace_id"} を返します——run id が run を追跡するために必要なすべてです。クライアントの切断によって run が強制終了されることはありません；課金、永続化、最終回答は必ず反映されます。

必須：

task——何をするか、自然言語で記述（最大 20,000 文字）。送らなければならない唯一のフィールドです。

任意（いずれも妥当なデフォルトがあり、必要時のみ上書き）：

model——空にするとプラットフォームがツール対応のドライバを選びます。特定のものを強制したい場合のみ指定してください。
max_steps——ツール／思考の反復回数の上限（1–50）。
budget_usd——ハードなコスト上限（> 0、最大 100）。
pro——より深く、マルチスレッドな推論をアンロックします（複雑なタスクで並列サブエージェントを実行）。
project_id——あるプロジェクトの指示とファイルをコンテキストとして注入して実行します。
conversation_id——今回の run を既存のチャット conversation 配下に紐付けます（結果はそのスレッドに書き戻されます）。省略すると単独のタスクとして扱われます。
skills——ユーザーが明示的に選んだスキルの slug（最大 8 つ）；空にすると純粋なベースラインを実行します（スキルが自動付与されることはありません）。
persona_slug——agency-agents ライブラリのスペシャリストロール；今回の run のアイデンティティヘッドとして注入されます。最大 1 つ。
history——直近のターン（{role, content}、role は user または assistant）。ターンをまたぐ連続性のために使用します。conversation_id を設定すると無視されます（履歴はサーバー側で再構築されます）。
mode——コンポーザーのレーンヒント（auto はルーターに chat／agent／cowork／code の選択を委ねます）。統合ルーターが有効な場合にのみ参照されます。
approval_mode——危険なローカルマシン操作に対する姿勢：ask（デフォルト、ユーザーの承認を待って一時停止）または auto（一時停止せずに実行）。

bash

curl https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs \
  -H "Authorization: Bearer $NEXEVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"task": "Compare the fee schedules of Wise and Airwallex; output a table.",
       "pro": true, "budget_usd": 0.5}'
# -> {"run_id": "…", "trace_id": "…"}

run の追跡（Server-Sent Events）

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/attach —

run のイベントストリーム（text/event-stream）を追跡します。各フレームは data: 行の 1 つの JSON オブジェクトです。

再接続セーフです：id: 行がストリームエントリ id を保持するため、EventSource はネイティブに lastEventId を追跡し、再接続時に Last-Event-ID として再送します——リロード、WiFi の切り替え、2 台目のデバイスでの run のオープンでも、最後に見た位置から正確に再開します（バックログは最後に確認した id から再生されます）。ジェネレータは run の終端フレームの後に終了し、アイドル期間には : ping ハートビートが送られるため、プロキシが接続を落とすことはありません。

イベントの type 一覧：

type	フィールド	発生タイミング
`step_start`	`step_no`	ループの反復が開始
`llm_delta`	`step_no`, `text`	ストリーミングされるモデルのテキスト
`reasoning` / `reasoning_delta`	`step_no`, `text`	ステップの思考の連鎖（ターン終了時に完全版、delta はライブストリーミング）
`tool_call` / `tool_call_delta`	`step_no`, `tool_name`, `arguments`	モデルがツールの呼び出しを要求（delta は引数をストリーミング）
`tool_progress`	`step_no`, `tool_name`, `message`, `progress?`	長時間のツールが中間進捗を報告
`tool_result`	`step_no`, `tool_name`, `ok`, `preview`, `duration_ms`, …	ツールが完了（`artifacts`、`sources`、`screenshot_url` を伴う場合あり）
`approval_request` / `approval_resolved`	`step_no`, `approval_id`, …	危険なローカル操作がユーザーの決定を待機中（または決定された）
`step_end`	`step_no`, `cost_usd`	反復が完了
`context_compacted`	`step_no`, `summary`	以前のターンがコンテキストウィンドウに収まるよう要約に圧縮
`run_end`	`status`, `step_count`, `cost_usd`, `final_text`, `latency_ms`	終端——最終回答は `final_text` に入っています
`error`	`message`	終端的な失敗

各イベントはさらに run_id（と step_no）を運ぶため、多重化されたコンシューマは接続ごとの状態なしでフレームをルーティングできます。ストリームは終端フレーム run_end（または error）で終了し——[DONE] センチネルはありません。

bash

curl -N https://nexevo.ai/v1/workspaces/$NEXEVO_WORKSPACE/agent/runs/$RUN_ID/attach \
  -H "Authorization: Bearer $NEXEVO_API_KEY"
# id: 1719900000-0
# data: {"type":"step_start","run_id":"…","step_no":1}
# id: 1719900000-1
# data: {"type":"llm_delta","run_id":"…","step_no":1,"text":"…"}
# …
# data: {"type":"run_end","run_id":"…","status":"succeeded","final_text":"…",…}

POST を再実行するよりも GET …/attach を優先してください：Last-Event-ID から再開できるため、再接続したクライアントはフレームを失いません。誰もアタッチしていなくても run は進行し続けます。

run の管理

GET/v1/workspaces/{workspace_id}/agent/runs —

run を一覧表示します（クエリ：limit、project_id、scheduled_only、include_archived）。

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

1 件取得：ステータス、永続化された final_text、完全な steps 軌跡、コスト、生成された artifacts。

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/cancel —

実行中のタスクを停止します。協調的かつワーカーをまたぎます（ループが次のステップ境界で確認するフラグを設定）；冪等であり、完了済みの run のキャンセルは無操作で、その終端ステータスを返します。

PATCH/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

最近リストのエントリを編集：title、archived、favorited、または project_id の移動（project_id が null ならプロジェクト外へ）。

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id} —

履歴から run を削除します（ステップはカスケード削除）。実行中の run は先にキャンセルしてください。

GET/v1/workspaces/{workspace_id}/agent/runs/{run_id}/artifacts.zip —

その run が生成したすべての artifact を単一の .zip でダウンロードします。

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

DELETE/v1/workspaces/{workspace_id}/agent/runs/{run_id}/share —

読み取り専用の公開リプレイリンクを作成／失効します（ボディ：任意の expires_in_days）。

POST/v1/workspaces/{workspace_id}/agent/runs/{run_id}/approvals/{approval_id} —

危険なローカル操作の承認要求に応答します（ボディ：{approved: true|false}）。approval_request イベントで提示される種類のものです。

run のステータス

run_end.status（および GET …/runs/{run_id}）は pending、running、succeeded、failed、cancelled、または partial（タスクは完了したが、まだ利用可能な部分的な結果を伴う）のいずれかです。終端状態は succeeded、failed、cancelled、partial です。

エージェントが生成したファイル（ドキュメント、スプレッドシート、スライド、チャート、Web アプリ）は run の artifacts として返されます。run は budget_usd とワークスペース残高の両方で制限されるため、暴走することはありません。