#Agent v2 API（Threads / Turns）

新一代 codex 风格 Agent 执行引擎的 HTTP 接口。以 Thread（会话线程）→ Turn（一次执行）→ Item（原子事件） 三级模型组织对话，统一 SSE 事件流贯穿引擎、SDK 与前端。

基础路径: /v2

相较 v1 Chat API 的核心增强：

• 采样循环引擎：不限固定轮数，模型持续调用工具直至任务完成（needs_follow_up 驱动）
• 并行工具执行：只读工具并发、写类工具串行（读写锁语义）
• 运行中干预：steer（追加输入）、interrupt（中断）、审批、用户输入均可在 turn 执行中进行
• 上下文自动压缩：token 超预算时 pre-turn / mid-turn 自动摘要压缩
• 沙箱与安全：exec_command / apply_patch 在沙箱内执行，approval × sandbox 二维策略 + 危险命令规则引擎
• 可恢复：thread 全量持久化，支持 resume / fork / rollback

#认证

• X-Organization-Id（必填）：组织 ID，缺失时返回 404 Tenant context missing
• X-API-Key 或 Authorization: Bearer <token>：身份凭证（见认证）
• X-Project-Id / X-User-Id（可选）：项目 / 用户上下文

#创建 Thread

CopyPOST /v2/threads

#请求体

#响应

jsonCopy{
  "id": "thr_abc123",
  "agentId": "agent_abc123",
  "title": "New Thread",
  "status": "active"
}

#列出 Threads

CopyGET /v2/threads?agentId=agent_abc123

返回最近 100 条活跃线程（按更新时间倒序）：

jsonCopy[
  { "id": "thr_abc123", "agentId": "agent_abc123", "title": "New Thread", "updatedAt": "2026-07-04T12:00:00.000Z" }
]

#读取 Thread（Resume）

CopyGET /v2/threads/:id

返回线程与全部 Item（按 seq 排序），用于恢复/渲染完整历史：

jsonCopy{
  "id": "thr_abc123",
  "agentId": "agent_abc123",
  "title": "New Thread",
  "status": "active",
  "tokenUsage": { "inputTokens": 1200, "outputTokens": 480, "totalTokens": 1680 },
  "items": [
    { "id": "item_1", "seq": 0, "type": "user_message", "status": "completed", "payload": { "content": [{ "type": "text", "text": "你好" }] } },
    { "id": "item_2", "seq": 1, "type": "agent_message", "status": "completed", "payload": { "content": "你好！有什么可以帮你？" } }
  ]
}

#Item 类型

#运行 Turn（SSE 流式）

CopyPOST /v2/threads/:id/turns
Content-Type: application/json
Accept: text/event-stream

#请求体

bashCopycurl -N -X POST "https://your-domain.com/v2/threads/thr_abc123/turns" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "X-Organization-Id: org_abc123" \
  -H "Content-Type: application/json" \
  -d '{"input": "查一下今天的新闻并总结"}'

#SSE 事件流（AgentEvent）

每行 data: 是一个 JSON 序列化的 AgentEvent，流末尾发送 data: [DONE]。

客户端断开连接会自动中断正在运行的 turn。

#事件归约建议

前端只需按 item.{started,updated,completed} 三段式归约渲染（delta 字段做增量合并），turn/thread 生命周期事件用于状态机控制——与 codex SDK 契约一致。

#运行中干预

#追加输入（Steer）

向正在运行的 turn 追加用户输入（mailbox 机制，模型在下一次采样前消费）：

CopyPOST /v2/turns/:id/steer

响应 { "ok": true }；turn 不存在或已结束返回 404。

#中断（Interrupt）

CopyPOST /v2/turns/:id/interrupt

取消令牌贯穿引擎与所有执行中的工具。响应 { "ok": true }。

#审批决议

收到 approval.requested 事件后，调用：

CopyPOST /v2/approvals/:requestId

同类审批（相同命令 + 目录 + 权限）在会话内缓存，不会重复询问。

#回答用户输入请求

收到 user_input.requested 事件后，调用：

CopyPOST /v2/user-input/:requestId

#Fork / Rollback

#Fork（分叉线程）

复制全部历史到新线程（记录 forkedFromId），原线程不受影响：

CopyPOST /v2/threads/:id/fork

jsonCopy{ "id": "thr_new456", "forkedFromId": "thr_abc123", "title": "New Thread (fork)" }

#Rollback（回滚）

删除线程尾部 N 个 turn 及其 Item：

CopyPOST /v2/threads/:id/rollback

jsonCopy{ "removed": 1 }

#Agent 行为配置（settings）

以下 Agent settings 字段控制 v2 引擎行为：

#计费

v2 引擎完整接入计量计费：turn 开始前校验组织用量限额（超限返回错误），turn.completed 时按模型费率记录用量与成本。用量查询接口与 v1 相同（见 Billing / Usage）。

#TypeScript SDK

服务端配套 SDK（sdk-v2/）封装了全部 v2 能力：

typescriptCopyimport { Creatoria } from '@creatoria/sdk-v2';

const client = new Creatoria({
  baseUrl: 'https://your-domain.com',
  organizationId: 'org_abc123',
  apiKey: 'sk_your_api_key_here',
});
const thread = await client.startThread('agent_abc123');

// 缓冲运行：等待完成并返回最终结果
const result = await thread.run('帮我调研这个课题');

// 流式运行：Item 三段式事件
let turnId = '';
for await (const event of thread.runStreamed('继续深入第二点')) {
  if (event.kind === 'turn.started') turnId = event.turnId;
  if (event.kind === 'item.completed') console.log(event.item);
}

// 干预与线程管理
await thread.steer('补充：只看中文来源', turnId);
await thread.interrupt(turnId);
await client.resolveApproval('req_id', true);
await client.resolveUserInput('req_id', '我的回答');
const forked = await thread.fork();
await thread.rollback(1);
const resumed = client.resumeThread(thread.id);

#与 v1 Chat API 的关系

• v1 /agent/chat、/agent/chat/stream、/agentic/run 仍可用，但已标记 Deprecation 响应头；设置 AGENTIC_LEGACY_DISABLED=true 后返回 410 Gone 并指向 v2。
• 历史会话可通过迁移脚本（npm run migrate:legacy-v2）转换为 v2 Thread/Item。
• 新集成一律使用 v2 接口。