TypeScript Agent SDK

从可信的服务端或 Worker 运行已保存的 Centidor Agent，并保留可继续的 Session。

@centidor/agent-sdk 是面向外部开发者的轻量执行 SDK。它只包含 Agent Run 与 Session 生命周期接口，不包含 Centidor Console 的内部管理客户端。

1. 创建 Agent Access Key

在控制台密钥设置创建现有的 cai_... 平台密钥，并显式勾选 agent:run。旧密钥不会自动获得 Agent 权限。

只在可信环境使用

长期密钥只能保存在服务端 Secret、Worker Secret 或企业 Secret Manager 中。不要放入浏览器 bundle、localStorage 或公开客户端。

2. 安装 SDK

npm install @centidor/agent-sdk

SDK 使用标准 fetch、Web Streams、AbortSignal 和 TextDecoder，可用于 Node.js、Bun、 Deno 和 Cloudflare Workers 等标准 Web API 运行时。

3. 运行已保存的 Agent

agent 使用已保存 Agent 的 slug 或 agt_... 公共 ID。执行目标来自 Agent 定义，调用方不能覆盖。

import { Centidor } from "@centidor/agent-sdk"

const centidor = new Centidor({
  apiKey: process.env.CENTIDOR_API_KEY!, // cai_...
})

const run = await centidor.agents.run({
  agent: "codex",
  input: "修复测试并解释改动",
})

for await (const event of run.events()) {
  console.log(event.type, event.payload)
}

const result = await run.result()
console.log(result.output)

4. Project 是可选的

省略 project 会创建真正的 Projectless Session，不会隐式选择第一个 Project。传入 prj_... 时，Session 会固定绑定该 Project 并快照仓库信息。

const run = await centidor.agents.run({
  agent: "agt_...",
  project: "prj_...", // 可选
  input: "检查仓库并修复测试",
})

5. Session 生命周期

RunHandle 支持事件断线重连、结果读取、继续运行、活动输入、审批、取消和幂等 Session 销毁。

const next = await run.continue("补充回归测试")

await next.send("yes")
await next.resolveApproval("approval-id", "approved")
await next.cancel()
await next.destroySession()

请求失败时 SDK 抛出 CentidorError，其中包含 HTTP status、稳定的 code 和可用于排查的 requestId，不会暴露未经约束的服务端响应正文。