Observability
Use XState inspection for actor/runtime behavior and Agent traces for model-request behavior.
Inspect a run
The package does not ship a visualizer. A run streams XState's inspection events through the inspect option, and the Stately inspector renders them live: the machine diagram, the active state, and every event.
pnpm add -D @statelyai/sdkimport { createInspector } from "@statelyai/sdk/inspect";
const inspector = createInspector({ name: "Refund agent" });
await inspector.ready; // the URL is null until the relay registers the session
console.log("Open", inspector.inspectorUrl);
try {
const result = await runAgent(machine, { input, executors, inspect: inspector.inspect });
} finally {
inspector.destroy(); // also when runAgent throws, so the connection closes
}inspector.inspectis an XStateinspectcallback, so it is passed as is.createAgentRuntimetakes the same option.createInspectorconnects to the hosted relay (wss://sky.stately.ai) unlessurlorSTATELY_INSPECT_URLnames another one.- Create one inspector per run. Session ids are unique only within one actor system, so a reused inspector collides actor ids across runs.
- With the hosted relay,
inspectorUrlis a one-time claim link for that session. Open it while the process runs; a new run prints a new one. - Each actor in the run reaches the inspector once, under one handle, though the durable runtime re-creates actor objects between steps. Compare actors by
sessionId, not by object. - examples/tanstack-ai-stream/inspect.ts and examples/next-host/agent-runtime.ts wire it behind
STATELY_INSPECT=1. type: "choice"states and other transient states (left at once byalways) never appear in the viewer's snapshot sequence: they resolve within the same macrostep.canReachstill counts them as reached.- A
runAgentstarted inside a wrapped workflow (a nested run per tool call, for example) appears in the inspector only when it gets its owninspectoption: the workflow does not receive one, so pass the same inspector explicitly. It is a separate root actor with its own thread, and it does not resume with the outer run.
Local relay
For a test or an offline run, start a relay in the process instead of the hosted one:
pnpm add -D @statelyai/sdk wsimport { createInspector } from "@statelyai/sdk/inspect";
import { createNodeInspectionRelay } from "@statelyai/sdk/node-relay";
const relay = createNodeInspectionRelay({ port: 0 }); // any free port
await relay.start();
let inspector: ReturnType<typeof createInspector> | undefined;
try {
inspector = createInspector({ url: relay.url, roomId: "local", session: "direct" });
await inspector.ready;
await runAgent(machine, { input, executors, inspect: inspector.inspect });
} finally {
inspector?.destroy();
await relay.stop();
}@statelyai/sdk/node-relayimportsws, an optional peer of@statelyai/sdk. Without it, the import fails withCannot find package 'ws'.- A
choicestate, or one left at once byalways, is passed through within one step, so no snapshot shows it. Read it fromdescribeMachineorexplorePaths'sreachedStates. session: "direct"connects with the room id only, which is what a local relay expects.- A test's viewer connects a WebSocket to
${relay.url}?r=<roomId>and registers as a viewer. That is the relay endpoint, not an inspector page.
Trace one run
await runToQuiescence(
createAgentRuntime(machine, {
executors,
inspect: (event) => xstateInspector.next(event),
onTrace: (event) => exporter.write(serializeTraceEvent(event)),
}),
{ input },
);Agent trace kinds are run.start, request.start, request.end, request.error, stream.chunk, machine.transition, emit, usage.dropped, and run.end.
A machine.transition event carries from.value, the state value the event arrived in, next to snapshot, the state after it. The first transition of a stream (the init event, or a restore on resume) has no earlier state, so its from.value equals its snapshot.value. traceTransitions sets it the same way for a plain actor. When the host's own event had no transition in the active state, the runtime's machine.transition also carries ignored: true (the event result.ignored reports), so evals can count those events from the trace alone.
A request.end event carries the call's output and raw, plus what the executor reported about the call itself: usage when it reported tokens, and finishReason when it reported why the call stopped, normalized to 'stop', 'length', 'tool-calls', 'content-filter', or 'other'. See Finish reason and truncation.
Trace handlers are observers: an onTrace, onTransition, onChunk, onResult, onEvent, or on handler that throws is reported with console.error, and the run continues.
serializeTraceEvent creates a JSON-safe projection. Traces are observations, not a persistence protocol; the event log is.
usage.dropped means the @agent.usage event was not delivered to the machine, because no active state accepted it or the leg had already settled. The spend is still journaled and still counted: the entry is in the event log, and getUsageFromEvents folds it into the totals. Only the machine event is dropped.
Live progress
Use onTrace for stream.chunk and machine.transition events while the run
is active. The returned AgentRunResult supplies the terminal done, idle,
or error status. Domain failure remains part of the machine's typed output.
State paths in logs
getStatePath(snapshot) renders a state value as one deterministic string, so a log line or a progress field survives nesting and parallel regions. String(snapshot.value) renders every non-atomic value as [object Object].
onTransition: (snapshot) => log.info({ state: getStatePath(snapshot) });An atomic state renders as writing, a nested one as review.editing.draft, and a parallel one as p:{left.x,right.a.b} with its regions sorted by name.
OpenTelemetry
Use createOtelTraceHandler from @statelyai/agent/otel as an onTrace sink. Framework telemetry and XState inspection remain composable with it.
Models and providers
Reuse models and executors from other AI frameworks via AI SDK LanguageModel objects, TanStack AI text adapters, and OpenAI-compatible endpoints.
Usage and budgets
Read token usage off a run, cap runaway loops with maxModelCalls, and enforce turn and token budgets as ordinary machine guards.