Documentation / Runs / Interfaces

Create durable work with the SDK

Understand which Run behavior is authored through runtime Ctx and which controls remain operator API operations.

An accepted event creates the Run. Agent code receives the Run’s immutable execution snapshot through Ctx; it does not construct Run records.

Suspend and delegate

ts
import { agent, subtask } from "@constal/sdk";

const investigate = subtask({
  id: "investigate", version: "1",
  async run(input, ctx) {
    const turn = await ctx.turn({ system: "Investigate the case.", objective: input });
    return turn.message.content;
  },
});

export default agent({
  id: "approval-flow", version: "1.0.0", model: "model",
  subtasks: [investigate],
  async onMessage(message, ctx) {
    const report = await ctx.spawn(investigate, message, { retries: 2 });
    const approval = await ctx.await<{ approved: boolean }>("approval", {
      schema: { type: "object", required: ["approved"], properties: { approved: { type: "boolean" } } },
    });
    return { report, approval };
  },
});

Handles have stable ids and recorded outcomes. Await them in their execution scope; never suppress runtime suspension or invent success for an unknown external result.

The Run pins the Agent revision, Policy, Resources, Tools, budgets, and accepted identity before this code executes. Replaying the handler therefore reuses the same authority and the same positional operation results.

Operator controls stay outside Ctx

sh
constal runs pause support session-42 run-7
constal runs resume support session-42 run-7
constal runs cancel support session-42 run-7

Pause, resume, cancel, interrupt, Policy changes, rebind, truncate, branch, and wait resolution are authenticated administrative operations. See Run control API and Durable execution.