Agent runs

一次 agent run 是一項自主任務：模型自行規劃、呼叫工具（網頁、程式碼、workspace 的資料、檔案生成、真實瀏覽器）、驗證，並交付結果——逐步串流輸出。與聊天不同，它端到端地負責整個任務。

啟動一次 run

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

啟動 run。run 與連線解耦：此端點會立即回傳一個小型 JSON 物件，引擎則在背景繼續執行。用 GET …/attach（見下文）追蹤即時串流。

最簡對接——只需一個欄位。 只送 {"task": "…"} 就完成了。平台會自動路由到最佳模型、自動挑選並呼叫合適的工具（網頁搜尋、你的知識庫、程式碼、瀏覽器……），並將結果串流回傳。你無需自行接線工具、模型或 prompt——下方所有其他欄位都是選用的覆寫項，僅在你需要更多控制時使用。可複製的完整範例請見 Cookbook。

POST 回傳 {"run_id", "trace_id"}——run id 是你追蹤 run 所需的全部資訊。用戶端斷線絕不會終止 run；計費、持久化與最終答案總是會落地。

必填：

task——要做什麼，以自然語言描述（最多 20,000 字元）。這是你唯一必須傳送的欄位。

選用（均有合理預設值，僅在需要時覆寫）：

model——留空讓平台挑選一個擅長工具呼叫的驅動模型。僅在需要強制指定時填寫。
max_steps——工具／思考迭代次數上限（1–50）。
budget_usd——硬性成本上限（> 0，最高 100）。
pro——解鎖更深入、多執行緒的推理（在複雜任務上並行執行子 agent）。
project_id——在某個專案的指令與檔案上下文中執行。
conversation_id——將本次 run 掛到一條既有的聊天 conversation 下（結果會寫回該對話串）。省略則作為獨立任務。
skills——使用者顯式選擇的技能 slug（最多 8 個）；留空則執行純基線（技能永遠不會被自動附加）。
persona_slug——來自 agency-agents 程式庫的專家角色；作為身份頭部注入本次 run。最多一個。
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: 行上的一個 JSON 物件。

它是可重連的：id: 行帶有一個串流項目 id，因此 EventSource 原生追蹤 lastEventId，並在重連時將其作為 Last-Event-ID 重送——重新整理頁面、WiFi 中斷、或第二台裝置開啟該 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":"…",…}

優先使用 GET …/attach 而非重放 POST：它支援從 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} —

取得單一 run：狀態、持久化的 final_text、完整的 steps 軌跡、成本及產出的 artifacts。

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

停止執行中的任務。協作式且跨 worker（設定一個旗標，迴圈會在下一個步驟邊界檢查）；冪等——取消已完成的 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 —

建立／撤銷一個唯讀的公開回放連結（請求 body：選用的 expires_in_days）。

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

回應一個危險本機操作的審批請求（請求 body：{approved: true|false}），即 approval_request 事件所呈現的那類。

Run 狀態

run_end.status（以及 GET …/runs/{run_id}）取值為 pending、running、succeeded、failed、cancelled 或 partial（任務完成但帶有仍可用的部分結果）。終止狀態為 succeeded、failed、cancelled 與 partial。

Agent 產出的檔案（文件、試算表、簡報、圖表、Web 應用）會作為 artifacts 附在 run 上。一次 run 同時受 budget_usd 與 workspace 餘額約束，因此永遠不會失控。