<!--
SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
SPDX-License-Identifier: Apache-2.0
-->

# 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 Flow 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 Flow 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.
