@cef-ai/agent-sdk

Author agents for the Cere Execution Fabric: a small surface of decorators and types that maps directly to the runtime contract.

Install

pnpm add @cef-ai/agent-sdk

For tests, also install the harness:

pnpm add -D @cef-ai/testing

Quickstart

An agent is a default-exported class with decorated methods. @OnEvent binds an event type to a handler; @OnStart and @OnClose are lifecycle hooks. Context is the single object the runtime threads through every call.

import {
  OnClose,
  OnEvent,
  OnStart,
  type Context,
  type Event,
  type OnCloseReason,
} from "@cef-ai/agent-sdk";

interface UserMessage {
  text: string;
}

export default class Echo {
  @OnStart
  async onStart() {
    // Logging + HTTP are plain Web globals, not ctx members:
    console.info("started");
  }

  @OnEvent("user_message")
  async onMessage(event: Event<UserMessage>, ctx: Context) {
    await ctx
      .cubby("history")
      .exec("INSERT INTO messages(text, ts) VALUES (?, ?)", [
        event.payload.text,
        Date.now(),
      ]);
    await ctx.publish("ack", { for: event.eventId });
  }

  @OnClose
  async onClose(_ctx: Context, reason: OnCloseReason) {
    console.info("closing", { reason });
  }
}

ctx carries only the CEF-specific platform calls. For plain capabilities, use the sandbox globals directly: console.* for logging (the runtime captures it) and fetch for HTTP.

Pair the class with a cef.config.ts:

import { defineAgent } from "@cef-ai/agent-sdk/config";

export default defineAgent({
  id: "echo",
  version: "1.0.0",
  entry: "./agent.ts",
  cubbies: [{ alias: "history", migrations: "./migrations/history" }],
});

API summary

How it runs (runtime model)

Per Agent Runtime ADR-001, the Cere Network runtime is a CEF-agnostic bundle executor: it exposes only Web-platform globals (fetch, console, URL, crypto, TextEncoder, timers, …) plus one opaque globalThis.context object, and dispatches invocations as globalThis.__handlers[name](event, context).

ctx is CEF-specific add-ons only — SDK code compiled into your bundle by cef build, not a runtime-provided binding:

• ctx.publish / ctx.cubby / ctx.models[…].infer / ctx.close → fetch calls to the endpoints the orchestrator places in globalThis.context (context.endpoints.*, with context.auth headers).
• ctx.settings → context.settings.

Plain Web-platform capabilities are not mirrored on ctx — use the sandbox globals directly: console.* for logging (captured out-of-band by the runtime) and fetch for HTTP.

You never write the shim code — you author the decorated class, and the shims (the @cef-ai/agent-sdk/runtime subpath) are bundled in automatically.

Inference usage is reported automatically. Each ctx.models[…].infer call captures the gateway's usage and the SDK folds a _modelCalls array into your handler's return value; the orchestrator reads it to record per-model token/GPU usage (ADR-004). _modelCalls is a reserved result key — don't set it yourself.

Subpath exports

For testing, use @cef-ai/testing directly — import { testAgent } from "@cef-ai/testing".

Companion packages

• @cef-ai/cli — cef build (esbuild + manifest), cef typegen (populates KnownEventTypes), cef inspect.
• @cef-ai/testing — simulator harness for unit and integration tests.
• @cef-ai/eslint-plugin — editor-time lints mirroring the build-time checks.

References

• Agent SDK spec: ../../../company-memory-bank/specs/platform/03-components/agent-sdk.md
• Runtime integration contract: ../../../company-memory-bank/specs/platform/03-components/sdk-runtime-integration-contract.md
• Implementation plan: ../../../company-memory-bank/plans/2026-04-27-sdk-implementation-plan.md

The ../company-memory-bank/... paths are local references to an internal sibling repo and are not browsable from a fresh clone.