Agent authoring reference

Define an agent as ordinary TypeScript data. Composition helpers return frozen serializable definitions; compileAgent resolves graph references and environment bindings without making requests. The authoring workflow previews remote state, applies revision-checked draft edits, validates with Cumulus and publishes an immutable version.

Import from @cumulus/sdk/agent. This page documents SDK 0.3.4. Follow the agent authoring guide for a worked workflow.

Define an agent

Save this as agent.ts. It exports the graph, environment, integration and project used in the publication example below. The integration’s number alias is applied separately when you choose to route a published agent.

import {
  defineAgent, defineNode, defineEdge, defineComponent,
  defineProject, defineIntegration, defineEnvironment, compileAgent,
} from "@cumulus/sdk/agent";

const greet = defineNode({ key: "greet", kind: "conversation",
  instruction: { type: "prompt", text: "Ask how you can help." } });
const done = defineNode({ key: "done", kind: "end" });
export const agent = defineAgent({
  key: "support", name: "Support", startNode: greet, nodes: [greet, done],
  edges: [defineEdge({ from: greet, to: done, slot: "edges",
    condition: { type: "prompt", prompt: "The caller is finished." } })],
});
export const integration = defineIntegration({
  key: "support_line", agent, outbound: { callerIdBinding: "support" },
});
export const project = defineProject({ key: "service_desk", agents: [agent],
  integrations: [integration] });
export const environment = defineEnvironment({ numbers: { support: "number-id" } });
export const compiled = compileAgent(agent, environment, integration);

// A reusable component is its own scoped graph; attach it to an agent as needed.
export const goodbye = defineComponent({ key: "goodbye", startNode: done,
  nodes: [done] });

Preview, review, then publish

Download the complete authoring example. It contains this definition, the two files below and a storage helper. Save this helper as publish.ts. It accepts a saved plan that you have reviewed; it never creates a fresh preview. It checks the current source, bindings, integration and project against that plan before applying its exact revision and publishing a test-only version.

import { Cumulus } from "@cumulus/sdk";
import { authoring, compileAgent, definitionHash, DraftConflict,
  type AgentDefinition, type EnvironmentBindings, type AuthoringPreview,
  type ApplyReceipt, type PreviewOptions } from "@cumulus/sdk/agent";

// sourceHash is review metadata for this example, not an SDK request field.
export type ReviewedPlan = AuthoringPreview & { sourceHash: string };
export function reviewedSourceHash(agent: AgentDefinition, bindings: EnvironmentBindings,
  options: PreviewOptions = {}) {
  return definitionHash({ agent, bindings, integration: options.integration ?? null,
    projectKey: options.projectKey ?? options.receipt?.projectKey ?? agent.key });
}

export async function publishAgent(client: Cumulus, agent: AgentDefinition,
  bindings: EnvironmentBindings, plan: ReviewedPlan,
  save: (receipt: ApplyReceipt) => Promise<void>, options: PreviewOptions = {}) {
  const current = compileAgent(agent, bindings, options.integration);
  const projectKey = options.projectKey ?? options.receipt?.projectKey ?? agent.key;
  const agentId = options.agentId ?? options.receipt?.agentId;
  if (plan.projectKey !== projectKey || definitionHash(current) !== plan.definitionHash ||
      reviewedSourceHash(agent, bindings, options) !== plan.sourceHash ||
      (agentId && plan.agentId !== agentId)) {
    throw new DraftConflict("Source or management scope changed; preview and review again");
  }
  const receipt = await authoring.apply(client, plan, {
    expectedRevision: plan.baseRevision, onCheckpoint: save,
  });
  const validation = await authoring.validate(client, receipt);
  if (!validation.ok) return { ok: false as const, diagnostics: validation.diagnostics };
  const published = await authoring.publish(client, receipt, {
    live: false, onCheckpoint: save,
  });
  await save(published);
  return { ok: true as const, publication: published.publication };
}

Run the two steps separately

The example’s authoring.ts entrypoint passes project.key, integration and the previous receipt into preview. Its storage helper saves the full plan and durably checkpoints later edits; the helper is application code included in the download.

import { pathToFileURL } from "node:url";
import { Cumulus } from "@cumulus/sdk";
import { authoring, effectiveTenant } from "@cumulus/sdk/agent";
import { agent, project, environment, integration } from "./agent.js";
import { publishAgent, reviewedSourceHash } from "./publish.js";
import { openAuthoringStore } from "./authoring-store.js";

export async function runAuthoring(command: "preview" | "publish") {
  const baseUrl = process.env.CUMULUS_API_URL;
  const apiKey = process.env.CUMULUS_API_KEY;
  if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_API_URL and CUMULUS_API_KEY");
  const client = new Cumulus({ baseUrl, apiKey });
  const tenant = await effectiveTenant(client);
  const store = await openAuthoringStore(tenant, project.key, agent.key);
  const receipt = await store.readReceipt();
  if (receipt?.pendingBatch || receipt?.pendingPublication) {
    throw new Error("Reconcile the interrupted operation in receipt.json first");
  }
  const options = { projectKey: project.key, integration, receipt };
  if (command === "preview") {
    const plan = await authoring.preview(client, agent, environment, options);
    await store.savePlan({ ...plan, sourceHash: reviewedSourceHash(agent, environment, options) });
    console.log({ tenant: plan.tenantId, revision: plan.baseRevision, changes: plan.changes });
    console.log("Review the full plan at " + store.directory + "/preview.json");
    return; // No draft edit or publication has been sent.
  }
  const plan = await store.readPlan();
  if (!plan) throw new Error("Run preview and review preview.json before publishing");
  const result = await publishAgent(client, agent, environment, plan, store.saveReceipt, options);
  console.log(result);
}

if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const command = process.argv[2];
  if (command !== "preview" && command !== "publish") throw new Error("Use preview or publish");
  await runAuthoring(command);
}

After installing SDK 0.3.4 in the downloaded example and setting CUMULUS_API_URL and CUMULUS_API_KEY, run:

npm run build
npm run preview

Preview prints the effective tenant, draft revision and proposed changes, then exits without editing or publishing. Open the printed preview.json path and review its complete definition and edits. Keep the file unchanged. When you approve that saved plan, run:

npm run publish

Publish reads that saved plan rather than calculating another one. A source, binding or integration change requires another preview and review. The SDK also checks the target tenant and draft revision before applying. sourceHash is extra review metadata used by this example; it is not a Cumulus request field. This command creates a test-only publication and does not route numbers or place calls.

Later previews load receipt.json to continue managing the same agent under the same tenant and project. The support helper stores private plan and receipt files under .cumulus/<tenant>/<project>/<agent>/. Keep them across builds and out of version control. A pending edit or publication stops the command so you can reconcile the interrupted operation.

If someone changes the draft in Studio, export and backport the intended change before explicitly adopting its reviewed revision. Run one authoring process per managed agent.

Compose an agent

defineAgent

Give a graph a stable agent key, display name and start node. The helper freezes a serializable copy; compileAgent checks the graph and native configuration.

Related types and helpers: AgentDefinition.

export declare function defineAgent<const T extends AgentDefinition>(v: T): T;

defineNode

Define one native conversation, tool, branch, extraction, transfer, end, component, verification or tokenization node. key becomes its native ID within its graph scope.

Related types and helpers: NodeDefinition.

export declare function defineNode<const T extends NodeDefinition>(v: T): T;

defineEdge

Connect nodes by object reference or stable key. Set the native transition slot and condition. compileAgent verifies both endpoints exist in the same graph scope.

Related types and helpers: EdgeDefinition.

export declare function defineEdge<const T extends EdgeDefinition>(v: T): T;

defineComponent

Define a reusable subgraph with its own start node and node scope. Instantiate separate component keys when reusing a factory in one agent.

Related types and helpers: ComponentDefinition.

export declare function defineComponent<const T extends ComponentDefinition>(v: T): T;

defineTool

Declare the customer-hosted HTTP contract: input/output JSON schemas, endpoint binding, timeout and idempotency policy. JSON schemas are validated immediately; handler functions remain in your backend.

Related types and helpers: JSONSchema · ToolDefinition.

export declare function defineTool<const I extends JSONSchema, const O extends JSONSchema>(v: ToolDefinition<I, O>): ToolDefinition<I, O>;

defineIntegration

Associate an agent with inbound/outbound number aliases and optional event delivery. compileAgent resolves context and notification configuration; assignIntegration applies number routing separately.

Related types and helpers: IntegrationDefinition.

export declare function defineIntegration<const T extends IntegrationDefinition>(v: T): T;

defineProject

Group agent and integration definitions in a portable project. Its key identifies source management scope; applying agents remains an explicit workflow.

Related types and helpers: ProjectDefinition.

export declare function defineProject<const T extends ProjectDefinition>(v: T): T;

defineEnvironment

Keep deployment-specific endpoint, number and event-destination bindings separate from portable agent source. Return a frozen serializable binding object.

Related types and helpers: EnvironmentBindings.

export declare function defineEnvironment<const T extends EnvironmentBindings>(v: T): T;

compileAgent

Resolve tools, components, graph references and environment bindings into a native CompiledDefinition. Reject missing bindings, conflicting identities and invalid native edits. Defaults: phone channel, English, agent starts, empty global prompt/settings/variables, strict tool calls. Tool defaults: failure_edge on uncertainty, required response mappings and no automatic speech after execution. No network request is made.

Related types and helpers: AgentDefinition · EnvironmentBindings · IntegrationDefinition · CompiledDefinition.

export declare function compileAgent(agent: AgentDefinition, bindings?: EnvironmentBindings, integration?: IntegrationDefinition): CompiledDefinition;

Review and publish changes

authoring

The authoring workflow object exposes the same preview, apply, validate, publish, promote and exportDraft functions exported individually below.

Related types and helpers: preview · apply · validate · publish · promote · exportDraft.

export declare const authoring: {
    preview: typeof preview;
    apply: typeof apply;
    validate: typeof validate;
    publish: typeof publish;
    promote: typeof promote;
    exportDraft: typeof exportDraft;
};

preview

Compile the definition and read the effective tenant, draft and publication head. Return planned edits and their revision/fingerprint baseline without opening a draft or placing a call. A changed remote draft needs explicit acceptRemoteRevision after review/backport.

Pass projectKey to name the source project, integration to include that agent’s context and notification configuration, and the saved receipt when continuing to manage an agent. The receipt supplies its agent ID and baseline. You can supply agentId directly when adopting an existing agent; review/export its draft first.

The project defaults to receipt.projectKey, then agent.key. A receipt must match the effective tenant, agent key and selected project. acceptRemoteRevision explicitly adopts the exact remote revision you reviewed and backported; it does not disable future revision checks. See the complete invocation above.

Related types and helpers: Cumulus · AgentDefinition · EnvironmentBindings · PreviewOptions · AuthoringPreview.

export declare function preview(client: Cumulus, agent: AgentDefinition, bindings?: EnvironmentBindings, options?: PreviewOptions): Promise<AuthoringPreview>;

apply

Apply exactly the reviewed preview. expectedRevision must equal plan.baseRevision. Creates a blank agent when needed, applies native edits in batches of at most 100, and calls onCheckpoint before each batch. Returns an ApplyReceipt; a partial failure carries its last checkpoint in PartialApplyError. Does not publish.

Related types and helpers: Cumulus · AuthoringPreview · ApplyOptions · ApplyReceipt.

export declare function apply(client: Cumulus, plan: AuthoringPreview, options: ApplyOptions): Promise<ApplyReceipt>;

validate

Ask Cumulus to validate the receipt’s draft ID and revision and include the execution plan. Read ok and diagnostics before publication.

Related types and helpers: Cumulus · ApplyReceipt · components.

export declare function validate(client: Cumulus, receipt: ApplyReceipt): Promise<{
    ok: boolean;
    version: number;
    digest: string | null;
    diagnostics: components["schemas"]["Diagnostic"][];
    plan?: components["schemas"]["PublicationPlan"];
}>;

publish

Re-read and fingerprint the draft, validate it, then publish its immutable version. Defaults to live:false and keep_draft:true. onCheckpoint records pending publication before sending, allowing the original publication request to be reconciled after interruption.

Related types and helpers: Cumulus · ApplyReceipt.

export declare function publish(client: Cumulus, receipt: ApplyReceipt, options?: {
    live?: boolean;
    onCheckpoint?: (receipt: ApplyReceipt) => void | Promise<void>;
}): Promise<ApplyReceipt>;

promote

Move the current head to receipt.publication.version using the expected head version and draft ID. Requires a publication in the receipt; promotion does not change that publication’s test/live mode.

Related types and helpers: Cumulus · ApplyReceipt.

export declare function promote(client: Cumulus, receipt: ApplyReceipt): Promise<ApplyReceipt>;

exportDraft

Return the current public draft, revision and semantic fingerprint for review or backport into source. This is a canonical public view, not reconstructed TypeScript.

exportDraft(client, agentId)

The resolved object contains schemaVersion, kind, agentId, revision, draftHash, draft and note. The draft property is the current draft response.

Use Awaited<ReturnType<typeof exportDraft>> for the exact inferred result type in your application. Full TypeScript declaration.

Related types and helpers: Cumulus · draftHash · components.

Define private workflows

defineVerification

Build a verify_identity node with matched and declined exits. The successful native receipt sets rpc_confirmed; the language model does not select this trust decision.

Related types and helpers: Cumulus · VerificationPolicy · NodeDefinition.

/** Cumulus selects these exits from verified private evidence. A model cannot grant verification. */
export declare function defineVerification(v: {
    key: string;
    policy: VerificationPolicy;
    matched: Destination;
    declined: Destination;
}): NodeDefinition;

defineTokenization

Build a tokenize_private node with tokenized and declined exits. Require a tokenization-purpose POST tool using effect_key idempotency; the policy’s tool identity is filled from the tool definition.

Related types and helpers: TokenizationPolicy · ToolDefinition · NodeDefinition.

/** Capture is phone-only and requires matching native verification and keypad consent. */
export declare function defineTokenization(v: {
    key: string;
    policy: Omit<TokenizationPolicy, "toolId">;
    tool: ToolDefinition;
    tokenized: Destination;
    declined: Destination;
}): NodeDefinition;

Resolve identities and bindings

keyOf

Read a stable key from a definition object or return a supplied string key. Useful in graph factories that accept either form.

export declare function keyOf(v: string | {
    key: string;
}): string;

secretReference

Convert server SecretMetadata into its opaque id and current_version pair. This pins the secret version used by a published endpoint binding.

Related types and helpers: components.

/** Pin the opaque server-issued secret identity, not the human-readable URL/name used to provision it. */
export declare function secretReference(metadata: components["schemas"]["SecretMetadata"]): {
    id: string;
    version: string;
};

resolveEndpoint

Resolve an absolute tool path against a credential-free HTTPS endpoint. Require port 443, no query/fragment and the same origin; return the absolute URL.

export declare function resolveEndpoint(base: string, path: string): string;

effectiveTenant

Resolve the API client’s current effective tenant. The result scopes authoring receipts and guards against applying a plan to another tenant.

Related types and helpers: Cumulus.

export declare function effectiveTenant(client: Cumulus): Promise<string>;

definitionHash

Return a SHA-256 identity for canonical serializable definition data. Object key order does not change the identity.

export declare const definitionHash: (value: unknown) => string;

draftHash

Fingerprint a draft’s semantic definition while excluding state, layout and flow version. Used to detect remote configuration changes around authoring operations.

export declare function draftHash(draft: Draft): string;

Handle authoring failures

DefinitionError

A definition, binding or schema is invalid. code is definition_invalid; diagnostics contains path/message pairs when available.

export declare class DefinitionError extends Error {
    readonly diagnostics: readonly {
        path: string;
        message: string;
    }[];
    readonly code = "definition_invalid";
    constructor(message: string, diagnostics?: readonly {
        path: string;
        message: string;
    }[]);
}

DraftConflict

The reviewed draft, tenant or source baseline changed. code is draft_conflict; remote may contain the current public draft for reconciliation.

export declare class DraftConflict extends Error {
    readonly remote?: Draft | undefined;
    readonly code = "draft_conflict";
    constructor(message: string, remote?: Draft | undefined);
}

PartialApplyError

Draft application stopped after partial progress. code is partial_apply; receipt contains the last checkpoint and cause retains the underlying error. Inspect/export the remote draft before resuming.

Related types and helpers: ApplyReceipt.

export declare class PartialApplyError extends Error {
    readonly receipt: ApplyReceipt;
    readonly cause: unknown;
    readonly code = "partial_apply";
    constructor(receipt: ApplyReceipt, cause: unknown);
}

Types and declarations

Action

The native customer HTTP action contract generated from a ToolDefinition and EndpointBinding.

Related types and helpers: DraftEdit.

export type Action = Extract<DraftEdit, {
    type: "action.put";
}>["action"];

AgentDefinition

Portable source graph: stable key/name, start node, nodes and optional edges/components/tools/settings. edits carries explicit native domain edits after generated graph changes.

Related types and helpers: NodeDefinition · EdgeDefinition · components · ComponentDefinition · ToolDefinition · NativeNode · DraftEdit.

export interface AgentDefinition {
    key: string;
    name: string;
    channels?: ("phone" | "cloud")[];
    languages?: ("en" | "es")[];
    startNode: NodeDefinition | string;
    nodes: NodeDefinition[];
    edges?: EdgeDefinition[];
    components?: ComponentDefinition[];
    tools?: ToolDefinition[];
    settings?: Settings;
    prompt?: string;
    startSpeaker?: "agent" | "user";
    variables?: Record<string, string>;
    contextVariables?: string[];
    modelChoice?: NativeNode["modelChoice"];
    toolCallStrictMode?: boolean;
    /** Native domain edits expose the full configuration contract. Applied after generated graph edits. */
    edits?: DraftEdit[];
}

ApplyOptions

Require the reviewed base revision, optionally record sourceCommit, and persist onCheckpoint receipts before consequential network steps.

Related types and helpers: ApplyReceipt.

export interface ApplyOptions {
    expectedRevision: number | null;
    sourceCommit?: string;
    onCheckpoint?: (receipt: ApplyReceipt) => void | Promise<void>;
}

ApplyReceipt

Persisted management checkpoint identifying tenant, agent, draft revision, fingerprints and managed definition. pendingBatch/pendingPublication record unfinished operations; publication identifies a published version.

Related types and helpers: definitionHash · CompiledDefinition · draftHash · components · DraftEdit.

export interface ApplyReceipt {
    schemaVersion: 1;
    projectKey: string;
    agentKey: string;
    agentId: string;
    tenantId: string;
    draftId: string;
    revision: number;
    headVersion: number | null;
    definitionHash: string;
    definition: CompiledDefinition;
    draftHash: string;
    sourceCommit?: string;
    publication?: {
        agent_id: string;
        version: number;
        digest: string;
    };
    pendingPublication?: components["schemas"]["PublicationsPublishRequest"];
    pendingBatch?: {
        expectedRevision: number;
        edits: DraftEdit[];
    };
}

AuthoringPreview

The immutable proposed change: compiled definition, effective tenant, remote draft/head baseline, create key and edit summary. Pass it unchanged to apply.

Related types and helpers: CompiledDefinition · definitionHash · DraftEdit.

export interface AuthoringPreview {
    schemaVersion: 1;
    projectKey: string;
    definition: CompiledDefinition;
    definitionHash: string;
    agentId?: string;
    tenantId: string;
    baseRevision: number | null;
    draftId: string | null;
    baseHash: string | null;
    headVersion: number | null;
    createKey: string;
    edits: DraftEdit[];
    changes: {
        operation: string;
        target: string;
    }[];
}

CompiledDefinition

The immutable, serializable native output of compileAgent: nodes, components, actions, flow, settings and explicit edits.

Related types and helpers: NativeNode · components · DraftEdit.

export interface CompiledDefinition {
    schemaVersion: 1;
    key: string;
    name: string;
    channels: ("phone" | "cloud")[];
    languages: ("en" | "es")[];
    nodes: NativeNode[];
    components: {
        id: string;
        startNodeId: string;
        nodes: NativeNode[];
        tools: any[];
        flexMode?: boolean;
    }[];
    actions: Extract<DraftEdit, {
        type: "action.put";
    }>[];
    flow: Extract<DraftEdit, {
        type: "flow.configure";
    }>["changes"];
    settings: Settings;
    edits: DraftEdit[];
}

ComponentDefinition

A scoped graph with a start node, nodes and optional edges/tools. flexMode is the native component flexibility option.

Related types and helpers: NodeDefinition · EdgeDefinition · ToolDefinition.

export interface ComponentDefinition {
    key: string;
    startNode: NodeDefinition | string;
    nodes: NodeDefinition[];
    edges?: EdgeDefinition[];
    tools?: ToolDefinition[];
    flexMode?: boolean;
}

DraftEdit

The full discriminated union of native authoring edits. Use agent.edits or environment.edits when a native setting has no dedicated composition helper.

Related types and helpers: components.

export type DraftEdit = components["schemas"]["DraftEdit"];

EdgeDefinition

A native transition with source from/to references and optional key. slot and condition keep their native graph meanings.

Related types and helpers: NativeEdge · NodeDefinition.

export type EdgeDefinition = Omit<NativeEdge, "id" | "destinationNodeId"> & {
    key?: string;
    from: NodeDefinition | string;
    to?: NodeDefinition | string;
};

EndpointBinding

A deployed HTTPS base URL, native authentication policy and optional non-secret headers. Credentials are pinned secret references.

Related types and helpers: Action.

export interface EndpointBinding {
    baseUrl: string;
    auth: Action["auth"];
    headers?: Record<string, string>;
}

EnvironmentBindings

Maps portable endpoint, phone number and notification aliases to one deployment’s resources; optional edits adds native environment configuration.

Related types and helpers: EndpointBinding · SecretRef · DraftEdit.

export interface EnvironmentBindings {
    endpoints?: Record<string, EndpointBinding>;
    numbers?: Record<string, string>;
    notifications?: Record<string, {
        url: string;
        secretRef: SecretRef;
    }>;
    edits?: DraftEdit[];
}

InferSchema

Infer common JSON Schema primitives, enum/const, objects, arrays and unions. Other valid patterns remain unknown at the TypeScript level.

/** Inference covers primitives, objects, arrays, enums and unions. Other valid schemas remain unknown. */
export type InferSchema<S> = S extends {
    enum: readonly (infer V)[];
} ? V : S extends {
    const: infer V;
} ? V : S extends {
    anyOf: readonly (infer U)[];
} ? InferSchema<U> : S extends {
    oneOf: readonly (infer U)[];
} ? InferSchema<U> : S extends {
    type: "string";
} ? string : S extends {
    type: "number" | "integer";
} ? number : S extends {
    type: "boolean";
} ? boolean : S extends {
    type: "null";
} ? null : S extends {
    type: "array";
    items: infer I;
} ? InferSchema<I>[] : S extends {
    type: "object";
} ? {
    [K in keyof Properties<S> as K extends RequiredKeys<S> ? K : never]: InferSchema<Properties<S>[K]>;
} & {
    [K in keyof Properties<S> as K extends RequiredKeys<S> ? never : K]?: InferSchema<Properties<S>[K]>;
} : unknown;

IntegrationDefinition

The agent plus optional inbound context, caller-ID binding and semantic-event subscriptions.

Related types and helpers: AgentDefinition.

export interface IntegrationDefinition {
    key: string;
    agent: AgentDefinition;
    inbound?: {
        numberBinding: string;
        contextResolver?: string;
        contextOutputs?: string[];
    };
    outbound?: {
        callerIdBinding: string;
    };
    events?: {
        destinationBinding: string;
        subscriptions: ("run.admitted" | "run.ended" | "recording.updated" | "analysis.updated")[];
    };
}

JSONSchema

A JSON Schema object used for tool contracts. The SDK validates supported schema structure at runtime.

export type JSONSchema = {
    readonly [keyword: string]: unknown;
};

NativeEdge

The native transition contract shared by node edges and EdgeDefinition.

Related types and helpers: NativeNode.

export type NativeEdge = NativeNode["edges"][number];

NativeNode

The complete native node union extracted from node.create. NodeDefinition adapts it for source references.

Related types and helpers: DraftEdit.

export type NativeNode = Extract<DraftEdit, {
    type: "node.create";
}>["node"];

NodeDefinition

A native node with a source key instead of ID. tool and component accept source objects or keys; native IDs can also be supplied explicitly.

Related types and helpers: NativeNode · NativeEdge · ToolDefinition · ComponentDefinition.

export type NodeDefinition = Omit<NativeNode, "id" | "edges" | "toolId" | "componentId"> & {
    key: string;
    edges?: NativeEdge[];
    tool?: ToolDefinition | string;
    component?: ComponentDefinition | string;
    toolId?: string;
    componentId?: string;
};

PreviewOptions

Choose an existing agent, management project and previous receipt. acceptRemoteRevision explicitly adopts a remote draft revision after reviewing/backporting it.

projectKey names your source management scope. receipt identifies the managed agent and last applied baseline. integration selects the context and notification connections to compile. agentId explicitly selects an existing agent; it takes precedence over the receipt’s agent ID. acceptRemoteRevision adopts only that reviewed draft revision. Forward these options to authoring.preview when writing your own deployment helper.

Related types and helpers: ApplyReceipt · IntegrationDefinition.

export interface PreviewOptions {
    projectKey?: string;
    agentId?: string;
    receipt?: ApplyReceipt;
    integration?: IntegrationDefinition;
    /** Explicitly adopt this remote revision after review/backport. Never use an implicit force overwrite. */
    acceptRemoteRevision?: number;
}

ProjectDefinition

A stable project key with optional arrays of agents and integrations.

Related types and helpers: AgentDefinition · IntegrationDefinition.

export interface ProjectDefinition {
    key: string;
    agents?: AgentDefinition[];
    integrations?: IntegrationDefinition[];
}

SecretRef

Opaque secret identity plus version. It references a provisioned credential; it contains no credential value.

export type SecretRef = {
    id: string;
    version: string;
};

TokenizationPolicy

The full native tokenize_private policy. defineTokenization fills its toolId from the selected tool.

Related types and helpers: NativeNode.

export type TokenizationPolicy = NonNullable<NativeNode["tokenization"]>;

ToolDefinition

A portable tool schema and HTTP execution policy. responseVariables maps output JSON paths to native scalar variables; responseVariablePolicy selects required versus replace_available mapping.

Related types and helpers: JSONSchema · Action.

export interface ToolDefinition<I extends JSONSchema = JSONSchema, O extends JSONSchema = JSONSchema> {
    key: string;
    description: string;
    input: I;
    output: O;
    channels?: Action["channels"];
    purpose?: "tokenization";
    execution: {
        type: "http";
        binding: string;
        path: string;
        method: Action["method"];
        timeoutMs: number;
        idempotency: Action["idempotency"];
        onUncertain?: Action["on_uncertain"];
    };
    responseVariables?: Record<string, string>;
    responseVariablePolicy?: "required" | "replace_available";
    speakAfterExecution?: boolean;
}

ToolInput

Infer the application input type from a ToolDefinition’s JSON input schema.

Related types and helpers: ToolDefinition · InferSchema.

export type ToolInput<T extends ToolDefinition> = InferSchema<T["input"]>;

ToolOutput

Infer the application output type from a ToolDefinition’s JSON output schema.

Related types and helpers: ToolDefinition · InferSchema.

export type ToolOutput<T extends ToolDefinition> = InferSchema<T["output"]>;

VerificationPolicy

The full native verify_identity policy, including verification method and trust output rules.

Related types and helpers: NativeNode.

export type VerificationPolicy = NonNullable<NativeNode["verification"]>;

Supporting types

These local type expressions appear in the signatures above. They are not separate package exports.

type Properties<S> = S extends {
    properties: infer P;
} ? P : {};

type RequiredKeys<S> = S extends {
    required: readonly (infer K)[];
} ? K : never;

type Settings = Extract<DraftEdit, {
    type: "agent.settings";
}>["values"];

type Draft = components["schemas"]["DraftsGetResponse200"];

type Destination = NodeDefinition | string;

Export index

• Compose an agent: defineAgent · defineNode · defineEdge · defineComponent · defineTool · defineIntegration · defineProject · defineEnvironment · compileAgent
• Review and publish changes: authoring · preview · apply · validate · publish · promote · exportDraft
• Define private workflows: defineVerification · defineTokenization
• Resolve identities and bindings: keyOf · secretReference · resolveEndpoint · effectiveTenant · definitionHash · draftHash
• Handle authoring failures: DefinitionError · DraftConflict · PartialApplyError
• Types: Action · AgentDefinition · ApplyOptions · ApplyReceipt · AuthoringPreview · CompiledDefinition · ComponentDefinition · DraftEdit · EdgeDefinition · EndpointBinding · EnvironmentBindings · InferSchema · IntegrationDefinition · JSONSchema · NativeEdge · NativeNode · NodeDefinition · PreviewOptions · ProjectDefinition · SecretRef · TokenizationPolicy · ToolDefinition · ToolInput · ToolOutput · VerificationPolicy