This page explains the lifecycle events emitted by scopes, tools, LLM calls, middleware, and subscribers.
Events are the runtime record of what happened. NeMo Relay uses Agent
Trajectory Observability Format (ATOF) 0.1 as the canonical event format for
scopes, managed execution helpers, manual lifecycle APIs, subscribers, and
exporters.
ATOF has two event kinds.
Emitted when lifecycle work starts or ends. scope_category is start or
end, and category identifies the kind of work, such as agent, function,
tool, llm, retriever, embedder, reranker, guardrail, evaluator,
custom, or unknown.
Emitted for named runtime checkpoints that are not full start/end lifecycle pairs.
Every event carries a shared envelope:
kindatof_versionuuidparent_uuidtimestampnamedatadata_schemametadataScope events add scope_category, category, attributes, and optional
category_profile. Mark events can optionally carry category and
category_profile, though the current public mark helpers emit generic marks
without those optional category fields.
Runtime helpers assign timestamps automatically by default. Manual lifecycle helpers for scopes, marks, tool calls, and LLM calls also accept an explicit timestamp for integrations that are replaying events or mirroring an upstream framework clock. Use explicit timestamps only when the caller owns a reliable event time; otherwise prefer the runtime-generated timestamp.
Native Rust, Python, Node.js, and FFI event-producing APIs construct canonical events synchronously, enqueue subscriber delivery, and return without waiting for subscriber callbacks, exporter work, file writes, or tracing processors. Use the binding flush API when a test or shutdown path must wait for queued subscriber work. WebAssembly keeps synchronous subscriber delivery.
These sections describe how event shapes and relationships should be interpreted by consumers.
Start and end scope events for the same lifecycle pair by UUID. That pairing lets subscribers compute durations, reconstruct call boundaries, and preserve nesting in downstream systems.
ATOF uses one data field. For scope events, data is the semantic input on
scope_category == "start" and the semantic output on
scope_category == "end".
Category-specific fields live under category_profile. NeMo Relay uses
model_name for LLM events, tool_call_id for tool events, and subtype for
custom-category events. LLM codec annotations, when present, are serialized
under category_profile.annotated_request on LLM start events and
category_profile.annotated_response on LLM end events. Unknown profile fields
are preserved so newer producers can interoperate with older consumers.
LLM codecs can enrich LLM events with annotated request and response data. These
annotations are part of the canonical event JSON under category_profile when
they are present, so ATOF JSONL export and in-process subscriber JSON expose the
same payload shape.
Scope APIs emit scope start and end events and can also emit named mark
events. Managed tool and LLM helpers emit scope events with category set to
tool or llm. Conditional-execution rejections and explicit mark points let
the runtime record important state transitions even when there is no full nested
callback to wrap. Subscriber delivery is downstream from event construction and
does not block the emitting call on native bindings.