Instrument analytics with the SDK

Declare bounded typed events and emit durable analytics intent from Agent or Channel runtime code.

Declare the event beside the executable, register it, and emit typed values from the durable invocation.

Declare and emit

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

const resolved = analyticsEvent({
  id: "support.resolved", version: "1",
  dimensions: ["queue"], metrics: ["duration_ms"],
} as const);

export default agent({
  id: "support", version: "1.0.0", model: "model", analytics: [resolved],
  async onMessage(message, ctx) {
    const startedAt = Date.now();
    const turn = await ctx.turn({ system: "Resolve the request.", objective: message });
    ctx.analytics.emit(resolved, {
      dimensions: { queue: "general" },
      metrics: { duration_ms: Date.now() - startedAt },
    });
    return turn.message.content;
  },
});

Dimensions must be bounded categories. Never emit secrets, prompts, customer content, session ids, request ids, or unbounded identifiers. Increment the version when meaning changes. Emission records intent with the invocation; code receives no archive, projection, or query authority.

Analytics is observation, not workflow authority. Read live Run state from its owner and query projected events later. Continue with Instrument custom analytics and CLI analytics guide.

Projection delay is expected.