Agent Trajectory Interchange Format (ATIF)

Use the atif section when you want one Agent Trajectory Interchange Format (ATIF) trajectory artifact per top-level agent run.

The plugin-managed ATIF dispatcher watches for direct child scopes with category agent, creates a scope-local exporter for each one, and writes the trajectory when that agent scope ends. Nested agent scopes remain in the parent trajectory.

plugins.toml Example

1
version = 1
2
3
[[components]]
4
kind = "observability"
5
enabled = true
6
7
[components.config]
8
version = 1
9
10
[components.config.atif]
11
enabled = true
12
agent_name = "Planner"
13
agent_version = "1.0.0"
14
model_name = "unknown"
15
output_directory = "logs"
16
filename_template = "trajectory-{session_id}.json"

This configuration writes a trajectory file such as logs/trajectory-<scope-uuid>.json for each top-level agent scope.

Fields

Remote storage

For sandboxed runtimes such as NemoClaw / Omnistation / OpenShell, where local trace files are not durable across sessions, configure storage to ship completed trajectories directly to object storage. When storage is non-empty the local file write is replaced by uploads to every configured backend; output_directory is ignored.

Each storage entry is tagged with a type discriminator so additional backends can be added without breaking existing configs. Today, S3-compatible object storage is supported.

S3-compatible storage

1
[components.config.atif]
2
enabled = true
3
filename_template = "trajectory-{session_id}.json"
4
5
[[components.config.atif.storage]]
6
type = "s3"
7
bucket = "nemo-relay-traces"
8
key_prefix = "openshell/"

Multiple destinations

Add additional [[components.config.atif.storage]] tables to fan out the same trajectory to every destination — for example, an in-cluster MinIO target and a remote AWS target:

1
[components.config.atif]
2
enabled = true
3
filename_template = "trajectory-{session_id}.json"
4
5
[[components.config.atif.storage]]
6
type = "s3"
7
bucket = "nemo-relay-traces"
8
key_prefix = "openshell/"
9
10
[[components.config.atif.storage]]
11
type = "s3"
12
bucket = "team-archive"
13
key_prefix = "openshell/"
14
endpoint_url = "http://localhost:9000"
15
allow_http = true

Connection fields

By default, credentials, region, and endpoint URL are read from the standard AWS environment variables. Any non-secret connection field can also be set directly in the config so a single file can describe a complete destination, which is what unblocks running multiple S3-compatible endpoints side by side (for example, an in-cluster MinIO target and a remote AWS target):

Explicit fields take precedence; anything left unset falls back to the matching AWS_* environment variable.

Secret credential fields

Secret values stay out of checked-in config files. Each secret field carries a _var suffix and holds the name of an environment variable that contains the secret value. The name is validated at plugin initialization time:

Each trajectory is uploaded under {key_prefix}{rendered_filename}. The filename_template is rendered the same way it would be for local files, so a local→remote transition keeps object names stable. A trailing / is added to key_prefix when one is missing.

If an upload fails for a given destination, that destination is recorded as unhealthy and skipped on later trajectories. The other destinations continue to receive writes. All recorded sink failures are joined into the dispatcher’s last-error result on plugin teardown.

Expected Output

The exporter translates NeMo Relay lifecycle events into ATIF v1.7 trajectory data. LLM start and end events become model steps, tool events become tool calls and observations, and scope nesting contributes lineage metadata. Nested agent scopes are embedded in the parent file as subagent_trajectories and referenced from parent observation results with subagent_trajectory_ref.trajectory_id. The reference points to the embedded child trajectory by ID so consumers can validate the parent and child as one single-file ATIF v1.7 artifact.

The plugin writes each trajectory when the top-level agent scope closes. If the plugin is cleared while an agent is still open, teardown flushes the partial trajectory.

To correlate ATIF with OpenTelemetry or OpenInference traces from the same run, join on NeMo Relay UUIDs. The plugin-managed ATIF session_id is the top-level agent scope UUID. Each step’s extra.ancestry.function_id is the event UUID, and extra.ancestry.parent_id is the parent event UUID. Trace spans expose the same values as nemo_relay.uuid and nemo_relay.parent_uuid attributes.

Plugin Configuration

Use plugin configuration when the application should let NeMo Relay own the ATIF dispatcher lifecycle.

1
from nemo_relay import plugin
2
from nemo_relay.observability import AtifConfig, ComponentSpec, ObservabilityConfig
3
4
config = plugin.PluginConfig(
5
    components=[
6
        ComponentSpec(
7
            ObservabilityConfig(
8
                atif=AtifConfig(
9
                    enabled=True,
10
                    agent_name="Planner",
11
                    agent_version="1.0.0",
12
                    model_name="unknown",
13
                    output_directory="logs",
14
                    filename_template="trajectory-{session_id}.json",
15
                )
16
            )
17
        )
18
    ]
19
)
20
21
report = plugin.validate(config)
22
if any(diagnostic["level"] == "error" for diagnostic in report["diagnostics"]):
23
    raise RuntimeError(report["diagnostics"])
24
25
await plugin.initialize(config)
26
try:
27
    # Run instrumented application work here.
28
    pass
29
finally:
30
    plugin.clear()

Manual API

Use the manual AtifExporter API when you need explicit collection boundaries or one exporter object per run.

1
from nemo_relay import AtifExporter
2
3
exporter = AtifExporter("session-1", "agent", "1.0.0", model_name="demo-model")
4
exporter.register("atif-exporter")
5
6
# Run instrumented application work here.
7
8
trajectory = exporter.export()
9
exporter.deregister("atif-exporter")
10
exporter.clear()

Common Validation Failures

• filename_template does not contain {session_id}.
• The output directory is not writable at runtime.
• Tool definitions or extra metadata are not JSON-compatible.
• The application never opens a top-level agent scope, so no trajectory file is created.
• storage[i].type is unknown or storage[i].bucket is empty for some entry.
• storage is non-empty in a build that was compiled without the atif-storage feature, or on a target (such as WebAssembly) where remote storage is not supported.