Build an Agent with the SDK

Define script or durable Agent behavior, call models, read history, and return replay-safe results.

Before you begin

Create an SDK project and bind a Model under the logical name model. Start with script mode; choose durable mode only when explicit resumable state improves the workflow.

Steps

Export a validated Agent definition:

src/index.ts

import { agent, type HistoryView } from "@constal/sdk";

export default agent({
  id: "support-agent",
  version: "1.0.0",
  model: "model",
  async onMessage(message, ctx) {
    const history = await ctx.ledger.view<HistoryView>("history");
    const turn = await ctx.turn({
      system: "Resolve the support request accurately.",
      objective: message,
      context: { previous: history.facts },
      stream: true,
    });
    return { answer: turn.message.content };
  },
});

Page older history only when the bounded view says more exists:

const first = await ctx.ledger.view<HistoryView>("history");
const older = first.more ? await ctx.ledger.page(first.more) : { facts: [], more: null };

Publish an explicit fact when the workflow needs a checkpoint before normal completion:

if (message.kind === "checkpoint") {
  return ctx.commit({ kind: "checkpoint", payload: message.payload });
}

Memoize bounded local nondeterminism with a stable step name:

const normalized = await ctx.step("normalize-v1", async () => normalize(message));

Register every Tool, subtask, view, partition function, fold, and analytics declaration used by the package. Do not accept a model CRN, Resource CRN, or Credential from message input; use the accepted bindings on ctx.

Verify

Deploy, start one controlled Run, and inspect the journal. Confirm the Agent revision, Model and Resource snapshot, Policy hash, turn, usage, and committed output. Send the same event id again; it must resolve to the recorded outcome without duplicate work.

Next steps

Use From primitives to production to select a composition and Durable execution for waits, tasks, Handles, state machines, and data stages. Use Resources and Tools before adding external effects, then Start a Run to invoke the deployed Agent.