Agent runs

一次 agent 运行是一个自主任务：模型自行规划、调用工具（网页、代码、工作区数据、文件生成、真实浏览器）、验证，并交付结果——逐步流式输出。与聊天不同，它端到端地负责任务。

启动一次运行

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

启动运行。运行与连接解耦：该端点立即返回一个小的 JSON 对象，引擎在后台继续执行。用 GET …/attach（见下文）追踪实时流。

最简对接——只需一个字段。 只发 {"task": "…"} 就完成了。平台自动路由到最佳模型、自动选择并调用合适的工具（网页搜索、你的知识库、代码、浏览器……），并把结果流式返回。你无需自己对接工具、模型或提示词——下方所有其他字段都是可选的覆盖项，仅在你需要更多控制时使用。可复制的完整示例见 Cookbook。

POST 返回 {"run_id", "trace_id"}——run id 是你跟进运行所需的全部信息。客户端断开连接绝不会终止运行；计费、持久化和最终答案总是会落地。

必填：

task——要做什么，用自然语言描述（最多 20,000 字符）。这是你唯一必须传的字段。

可选（均有合理默认值，仅在需要时覆盖）：

model——留空让平台选择一个擅长工具调用的驱动模型。仅在需要强制指定时填写。
max_steps——工具/思考迭代次数上限（1–50）。
budget_usd——硬性成本上限（> 0，最高 100）。
pro——解锁更深入、多线程的推理（在复杂任务上并行运行子 agent）。
project_id——在某个Project的指令与文件上下文中运行。
conversation_id——将本次运行挂到一条已有的聊天会话下（结果会写回该会话）。省略则作为独立任务。
skills——用户显式选择的Skills slug（最多 8 个）；留空则运行纯基线（技能永远不会被自动附加）。
persona_slug——来自 agency-agents 库的专家角色；作为身份头部注入本次运行。最多一个。
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": "对比 Wise 和 Airwallex 的费率表，输出一张表格。",
       "pro": true, "budget_usd": 0.5}'
# -> {"run_id": "…", "trace_id": "…"}

跟进运行（Server-Sent Events）

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

追踪运行的事件流（text/event-stream）。每一帧是 data: 行上的一个 JSON 对象。

它是可重连的：id: 行携带一个流条目 id，因此 EventSource 原生跟踪 lastEventId，并在重连时将其作为 Last-Event-ID 重发——刷新页面、WiFi 中断、或第二台设备打开该运行，都能从上次中断处精确恢复（积压的帧会从你最后看到的 id 开始回放）。生成器在运行的终止帧后关闭；空闲时段会发送 : 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 恢复，因此重连的客户端不会丢失帧。无论是否有连接附着，运行都会继续。

管理运行

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

列出运行（查询参数：limit、project_id、scheduled_only、include_archived）。

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

获取单个运行：状态、持久化的 final_text、完整的 steps 轨迹、成本及产出的 artifacts。

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

停止运行中的任务。协作式且跨 worker（设置一个标志，循环在下一个步骤边界检查）；幂等——取消已完成的运行是无操作，返回其终止状态。

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} —

从历史中删除运行（其步骤级联删除）。请先取消运行中的任务。

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

将该运行产出的所有 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_end.status（以及 GET …/runs/{run_id}）取值为 pending、running、succeeded、failed、cancelled 或 partial（任务完成但带有仍可用的部分结果）。终止状态为 succeeded、failed、cancelled 和 partial。

Agent 产出的文件（文档、表格、幻灯片、图表、Web 应用）会作为 artifacts 附在运行上。一次运行同时受 budget_usd 和工作区余额约束，因此永远不会失控。