后台作业 API 与结果状态

宿主管理的无工具模型作业：提交冻结输入，按 Schema 验证输出，通过完成事件读取结果。

API 参考

按章节查看契约、签名、字段与示例；未注明的默认值不作推断。

本页内容

01提交与读取

预览能力 · SDK 0.1.0-alpha.9

submit 持久化后立即返回作业，不等待模型完成。get 返回宿主保存的状态与结果。需要项目权限 background.jobs；使用轮次引用还需授权读取对应项目。

代码示例

interface BackgroundJobInput {
  projectId: string; eventKey: string; prompt: string;
  turns: TurnReference[]; outputSchema: JsonObject;
}
interface BackgroundJob {
  id: string; eventKey: string; projectId: string;
  status: 'queued' | 'running' | 'succeeded' | 'failed' | 'unknown' | 'cancelled';
  providerId: string; model: string; createdAt: number; result?: Json; error?: string;
}
jobs.submit(input: BackgroundJobInput): Promise<BackgroundJob>;
jobs.get(jobId: string): Promise<BackgroundJob>;

02状态与恢复

根据 jobs.get 的权威状态处理，不能只收到完成 Hook 就执行成功分支。

字段 / API	说明
queued	已持久化，等待策略、授权、额度与执行槽。
running	已开始模型请求；重启后恢复为 unknown。
succeeded	输出通过 Schema 校验，读取 result。
failed	请求或输出校验失败，读取 error；不自动修复格式。
unknown	无法确认请求结果；不换 key 自动重发。
cancelled	排队作业被取消，例如授权撤销。

03Schema、限制与模型调用

输出必须符合 outputSchema。只发送单次非流式 Chat Completions / Responses 请求，无工具，不执行 Agent 或模型建议的业务操作；格式不符直接 failed，不额外请求修复。

字段 / API	说明
turns	每次 1–10 个明确引用；冻结正文最多 48000 bytes。
prompt / input	提示词最多 8000 字符；提交 JSON 最多 24000 bytes。
output	最多 2048 tokens；响应最多 256 KB；请求最长 120 秒。
budget	滚动 24 小时默认 20 次，范围 1–100；失败/未知也计入。

04幂等与错误

eventKey 在扩展安装范围内去重：同 key 同输入返回原 job，输入改变为 CONFLICT。超限按宿主返回 QUOTA_EXCEEDED 或失败；不自动截断输入。停用或撤权取消排队作业，已有结果不重新生成。unknown 通过宿主管理页核对；显式重新生成可能重复计费。扩展不能修改策略、获取凭据或调用管理端清理/重投 API。

05保留精确重试表示

去重使用 JSON.stringify(content) 的哈希，不排序对象键。同 eventKey 只有在序列化内容哈希一致时复用，内容变化会冲突。保留原请求表示。unknown 时核对原 job，不换键、重排字段或自动重提。公开 jobs API 仅 submit/get，没有 cancel/retry/manage。

SDK / CLI 0.1.0-alpha.9 · 接口基线兼容性与预览说明 · 案例源码