TypeScript Agent SDK

Run a saved Centidor Agent from a trusted server or Worker while retaining a resumable Session.

@centidor/agent-sdk is a lightweight execution SDK for external developers. It exposes only the Agent Run and Session lifecycle APIs; it does not include Centidor Console's internal administration client.

1. Create an Agent Access Key

Create a cai_... platform key in Gateway Key settings and explicitly grant agent:run. Existing keys do not receive Agent permissions automatically.

Use only in trusted environments

Store long-lived keys only in server-side Secrets, Worker Secrets, or an enterprise Secret Manager. Never include them in a browser bundle, localStorage, or a public client.

2. Install the SDK

npm install @centidor/agent-sdk

The SDK uses standard fetch, Web Streams, AbortSignal, and TextDecoder APIs. It works in Node.js, Bun, Deno, Cloudflare Workers, and other Web API-compatible Runtimes.

3. Run a Saved Agent

Set agent to the saved Agent's slug or agt_... public ID. The execution target comes from the Agent definition and cannot be overridden by the caller.

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: "Fix the tests and explain the changes.",
})

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

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

4. Project Is Optional

Omitting project creates a genuinely Projectless Session; it does not implicitly select the first Project. When you pass a prj_... ID, the Session is permanently bound to that Project and captures a snapshot of its repository configuration.

const run = await centidor.agents.run({
  agent: "agt_...",
  project: "prj_...", // optional
  input: "Inspect the repository and fix the tests.",
})

5. Session Lifecycle

RunHandle supports event-stream reconnection, result retrieval, continuation, active input, approvals, cancellation, and idempotent Session destruction.

const next = await run.continue("Add regression tests.")

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

When a request fails, the SDK throws CentidorError. The error includes the HTTP status, a stable code, and a requestId for diagnostics, without exposing an unconstrained server response body.