@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(ctx: Context) {
    ctx.log.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,
        event.ts,
      ]);
    await ctx.publish("ack", { for: event.id });
  }

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

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

| Kind | Symbol | Notes | | --- | --- | --- | | Decorator | @OnEvent(type) | Bind an event type (string literal) to a handler. | | Decorator | @OnStart | Mark the start lifecycle hook. | | Decorator | @OnClose | Mark the close lifecycle hook. | | Type | Context | Per-instance ctx — cubby, models, fetch, publish, settings, close, log. | | Type | Event<P> | { id, type, ts, from, payload: P }. | | Type | CubbyHandle | query(sql, params) / exec(sql, params) over per-alias storage. | | Type | ModelHandle<I,O> | infer(input) / stream(input) per declared model alias. | | Type | Logger | Leveled structured log: info / warn / error / debug. | | Type | OnCloseReason | "revoked" \| "idle_timeout" \| "closed_by_agent" \| "failed". | | Type | FetchInit | Subset of RequestInit accepted by ctx.fetch. | | Interface | KnownEventTypes | Declaration-merged event-type map populated by typegen. | | Function | defineAgent(config) | Identity helper that preserves literal types of AgentConfig. | | Type | AgentConfig | Top-level config: id, version, entry, cubbies, models, settings, fetch, publishes, lifecycle. |

Subpath exports

| Specifier | Purpose | | --- | --- | | @cef-ai/agent-sdk | Decorators, Context, Event, KnownEventTypes, Logger, ModelHandle, CubbyHandle, FetchInit, OnCloseReason. | | @cef-ai/agent-sdk/config | defineAgent and the AgentConfig shape — used in cef.config.ts. |

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.