Streaming & tracing

Agent runs emit a chronological TraceEvent stream — LM calls, tokens, tool invocations, guardrails, memory writes, and terminal final / error markers. Streaming APIs wrap those events in a tagged StreamEnvelope so consumers can distinguish live events from the terminal result (and HITL pause checkpoints).

Use the in-memory Tracer for UIs, channel bots, and tests. Export the same events to OpenTelemetry with OTelTracer from @maniac-ai/agents/observability.

Entry points

import { runAgentStream } from "@maniac-ai/agents";

for await (const env of runAgentStream(spec, "Hello")) {
  if (env.type === "event" && env.event.kind === "token") {
    process.stdout.write(env.event.delta ?? "");
  }
  if (env.type === "result") {
    console.log("\nStatus:", env.result.status);
  }
}

Pass a shared tracer via RunOptions.tracer so nested runs, background tasks, and OTel export all correlate under one run_id.

Topics

• Stream envelopes — StreamEnvelope variants (event, paused, result), cancellation contract
• Correlation IDs — turn_id, message_id, thread_id, block_id, span fields
• Tracer — in-memory collector, emit, aiter, trace kinds
• OTelTracer — GenAI semantic conventions, OTLP export, span model

API reference

Generated TypeDoc: observability module and agents schemas.

Non-TypeScript consumers can validate events against @maniac-ai/agents/trace-event.schema.json.