Events#

This page explains the lifecycle events emitted by scopes, tools, LLM calls, middleware, and subscribers.

What Events Represent#

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.

Event Kinds#

ATOF has two event kinds.

scope#

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.

mark#

Emitted for named runtime checkpoints that are not full start/end lifecycle pairs.

Shared Envelope#

Every event carries a shared envelope:

  • kind

  • atof_version

  • uuid

  • parent_uuid

  • timestamp

  • name

  • data

  • data_schema

  • metadata

Scope 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.

Semantic Meaning#

These sections describe how event shapes and relationships should be interpreted by consumers.

Start and End Pairing#

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.

Input and Output Payloads#

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 Profiles#

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.

Annotated Request and Response Data#

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.

How Events Are Produced#

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.