TavernHeadless

主题

Project Agent Jobs（后台 Agent 作业看板） ​

这组接口用于查看和管理某个 Project 下的后台 Agent 作业（agent.run）。它是面向高级开发者的运维视图，不是普通聊天界面接口。

各类后台作业共享的状态、轮询、重试与取消语义见 Background Jobs（后台作业）。

后台 Agent 作业由两种方式产生：事件自动触发（见 Agent Bindings）或手动 run。作业进入 Background Job Runtime 串行执行，这组接口让你按 Project 维度查询作业状态、错误，以及取消尚未运行的作业。

Worker 启用条件

作业入队不等于已经开始执行。后台 Agent 的真实消费依赖 API 进程启用 ENABLE_AGENT_RUNTIME_WORKER=true。未启用时，事件触发或手动 run 仍会创建 pending 作业，TaskBoard 也能看到这些作业，但不会有 worker 拉取并执行。

什么时候需要看这页 ​

  • 你触发了后台 Agent，想确认它执行到哪一步、是否成功。
  • 某个作业失败进入 dead letter，你要查看错误原因。
  • 你要取消一个尚未运行的后台作业。

如果你只是想启用 Agent 或手动 run，先看 Agent Bindings。

一个简单例子 ​

列出某个 Project 的后台 Agent 作业：

bash
curl http://localhost:3000/projects/proj_main/agent-jobs \
  -H 'x-api-key: <your-key>'

查看单个作业：

bash
curl http://localhost:3000/projects/proj_main/agent-jobs/<job_id> \
  -H 'x-api-key: <your-key>'

取消一个尚未运行的作业：

bash
curl -X POST http://localhost:3000/projects/proj_main/agent-jobs/<job_id>/cancel \
  -H 'x-api-key: <your-key>'

先理解几个词 ​

词这里的意思
后台 Agent 作业一条 agent.run 类型的后台作业记录
dry_run试运行标记。true 只演练不写输出，false 真实执行并写派生输出
dead letter作业因配置非法、权限越界或多次重试失败而停止的终态
scope作业的串行域，后台 Agent 使用 ${workspace_id}:${project_id}:${agent_type_id}
派生输出Agent 产出的 derived_output 等非主叙事数据

响应格式说明 ​

这组接口不使用通用的 data 包裹。列表接口返回 { "items": [...], "total": <number> }，详情和取消接口直接返回作业对象。

Agent Job 对象 ​

字段类型说明
idstring作业 ID
statusstring作业状态，见下方枚举
phasestring | null作业内部阶段标识
attempt_countinteger已尝试次数
max_attemptsinteger最大尝试次数
available_atinteger | null下次可执行时间戳（ms）
started_atinteger | null开始执行时间戳（ms）
finished_atinteger | null结束时间戳（ms）
last_errorstring | null最近一次错误信息
last_error_codestring | null最近一次错误码
last_error_classstring | null错误分类，如 fatal / retryable / uncertain
created_atinteger创建时间戳（ms）
updated_atinteger更新时间戳（ms）
agent_type_idstring | null触发作业的 Agent Type
agent_binding_idstring | null触发作业的 Agent Binding
source_event_idstring | null触发作业的事件 ID（手动 run 时为 null）
trigger_typestring | null触发方式，如 event / manual
dry_runboolean是否试运行
delivery_targetsarray作业声明的输出目标列表
resultobject | null作业结果摘要

状态枚举 ​

"pending" | "leased" | "running" | "retry_waiting" | "succeeded" | "dead_letter" | "cancelled"

列出 Agent 作业 ​

http
GET /projects/:id/agent-jobs

需要 project.agent.read 权限。只返回属于该 Project 的后台 Agent作业。

当前公开列表接口是 flat list：同一个 Agent Binding 或同一个 source event 触发的多条作业会逐条返回，不在 HTTP 响应中合并。服务层保留了按 source_event_id / agent_binding_id 聚合的最小 helper，供后续 UI 或治理阶段接入。

查询参数 ​

参数类型必填默认值说明
statusstring否-按状态过滤，取值见状态枚举
limitinteger否服务端默认返回数量上限，最大 100
offsetinteger否0偏移量

响应 200 ​

json
{
  "items": [
    {
      "id": "runtime-job:agent.run:...",
      "status": "succeeded",
      "phase": null,
  "attempt_count": 1,
      "max_attempts": 5,
      "available_at": null,
      "started_at": 1735689600000,
      "finished_at": 1735689601000,
      "last_error": null,
      "last_error_code": null,
      "last_error_class": null,
      "created_at": 1735689600000,
      "updated_at": 1735689601000,
      "agent_type_id": "agt_world_sim",
      "agent_binding_id": "agb_001",
      "source_event_id": "evt_123",
      "trigger_type": "event",
      "dry_run": false,
      "delivery_targets": ["derived_output"],
      "result": null
    }
  ],
  "total": 1
}

读取单个作业 ​

http
GET /projects/:id/agent-jobs/:job_id

需要 project.agent.read 权限。响应直接返回 Agent Job 对象。作业不属于该 Project 时返回 404。

取消作业 ​

http
POST /projects/:id/agent-jobs/:job_id/cancel

需要 project.agent.run 权限。只能取消尚未运行的作业（pending 或 retry_waiting）。不需要请求体，成功时返回更新后的作业对象，status 变为 cancelled。

已经在运行、已成功或已进入 dead letter 的作业不能取消，会返回 409。

权限 ​

操作所需权限ownerobserverderiver
列表、详情project.agent.read可以可以可以
取消project.agent.run可以不可以不可以

错误码汇总 ​

状态码error.code说明
403project_access_denied当前 Project 角色没有权限
404project_not_foundProject 不存在或不可见
404project_agent_job_not_found作业不存在或不属于该 Project
409project_agent_job_invalid_state作业当前状态不允许取消

相关页面 ​