From 4cba935e99704f10b45e4e347760d915fbda487f Mon Sep 17 00:00:00 2001 From: mnajafian-nv Date: Thu, 21 May 2026 13:51:52 -0700 Subject: [PATCH 1/2] docs: add migration guide Signed-off-by: mnajafian-nv --- docs/getting-started/migration.md | 97 +++++++++++++++++++++++++++++++ docs/index.md | 2 + 2 files changed, 99 insertions(+) create mode 100644 docs/getting-started/migration.md diff --git a/docs/getting-started/migration.md b/docs/getting-started/migration.md new file mode 100644 index 000000000..ef157313d --- /dev/null +++ b/docs/getting-started/migration.md @@ -0,0 +1,97 @@ + + +# Migrate Existing Agent Instrumentation to NeMo Flow + +Use this page as a routing guide when your agent application already has +callbacks, traces, or custom logging and you want to adopt NeMo Flow without +rewriting the application first. + +This is an adoption on-ramp, not a drop-in migration contract. Start by adding +NeMo Flow at the execution boundaries you can observe, validate that application +behavior stays the same, then add policy, adaptive behavior, or production +exporters after the basic event stream is correct. + +## Who This Guide Is For + +Use this guide when you are starting from one of these systems: + +- LangChain, LangGraph, Deep Agents, or another framework callback surface. +- Existing OpenTelemetry or OpenInference traces. +- A custom agent harness that emits JSON traces, run records, or callback logs. + +If you are building a new application without existing instrumentation, start +with the [Quick Start](quick-start.md) instead. + +## Migration Decision Tree + +Use the table below to choose the first NeMo Flow path. Pick one path first, +validate it, then add additional exporters or middleware. + +| Starting point | First NeMo Flow path | +|---|---| +| You own the direct tool or LLM call site | Use [Instrument Applications](../instrument-applications/about.md). | +| A framework owns the tool or LLM call site | Use [Supported Integrations](../integrations/about.md) if one exists; otherwise use [Integrate into Frameworks](../integrate-frameworks/about.md). | +| Your backend expects generic OTLP traces | Use the [OpenTelemetry exporter](../plugins/observability/opentelemetry.md). | +| Your backend expects OpenInference agent or LLM spans | Use the [OpenInference exporter](../plugins/observability/openinference.md). | +| You need portable offline trajectories for replay, analysis, or evaluation | Use [ATIF export](../plugins/observability/atif.md). | +| You need raw lifecycle events for a custom pipeline | Use [ATOF export](../plugins/observability/atof.md) or a direct subscriber. | + +## Preserve Behavior First + +Adopt NeMo Flow in this order: + +1. Add scopes around the request, run, or agent boundary. +2. Add a lightweight subscriber or local exporter so you can inspect emitted + events. +3. Instrument one tool or LLM boundary at a time. +4. Compare application outputs, framework callbacks, and existing traces before + enabling guardrails, intercepts, adaptive tuning, or production exporters. + +The first milestone is not performance tuning or policy coverage. The first +milestone is the same application behavior with a correct NeMo Flow event +stream. + +## Map Existing Concepts + +Use this mapping to translate current instrumentation concepts into NeMo Flow +terms before changing code. + +| Existing concept | NeMo Flow concept | +|---|---| +| LangChain callback run | Scope plus lifecycle event stream. | +| OpenInference span | OpenInference subscriber output from NeMo Flow events. | +| OpenTelemetry span | OpenTelemetry subscriber output from NeMo Flow events. | +| Custom trace object | Subscriber output, ATOF JSONL, or ATIF trajectory export. | +| Request-local state | Scope stack and context isolation. | +| Callback middleware | NeMo Flow middleware around managed tool and LLM calls. | +| Trace correlation ID | Root scope UUID and parent-child event IDs. | + +## Common Starting Scenarios + +If you already use LangChain callbacks, keep the framework behavior in place and +start with the [LangChain integration](../integrations/langchain.md). Validate +that the agent result and existing callback behavior do not change before adding +new middleware. + +If you already export OpenInference spans to Phoenix or another compatible +backend, start with the [OpenInference exporter](../plugins/observability/openinference.md). +NeMo Flow becomes the event source for those spans; the backend setup can stay +backend-specific. + +If your custom harness emits JSON traces, decide whether you need raw lifecycle +events, portable trajectories, or direct in-process handling. Use [ATOF export](../plugins/observability/atof.md) +for raw events, [ATIF export](../plugins/observability/atif.md) for trajectories, +or a direct subscriber when your application should own the output shape. + +## Next Steps + +After you pick the first path, use these pages for implementation details: + +- [Quick Start](quick-start.md) +- [Instrument a Tool Call](../instrument-applications/instrument-tool-call.md) +- [Instrument an LLM Call](../instrument-applications/instrument-llm-call.md) +- [Integrate into Frameworks](../integrate-frameworks/about.md) +- [Observability Plugin](../plugins/observability/about.md) diff --git a/docs/index.md b/docs/index.md index 498e6ff96..7afe8ee18 100644 --- a/docs/index.md +++ b/docs/index.md @@ -59,6 +59,7 @@ Use the reading path that matches your task: |---|---| | Run a minimal example | [Quick Start](getting-started/quick-start.md) | | Install packages | [Installation](getting-started/installation.md) | +| Adopt from existing callbacks, traces, or custom harnesses | [Migration Paths](getting-started/migration.md) | | Develop from source | [Development Setup](contribute/development-setup.md) | | Understand the runtime model | [Concepts](about/concepts/index.md) | | Instrument an application | [Instrument Applications](instrument-applications/about.md) | @@ -146,6 +147,7 @@ about/release-notes/index getting-started/prerequisites getting-started/installation Configuration / Setup +Migration Paths Quick Start ``` From 086dfd2bfa9ae8c47e935b278b7b10cc4d449158 Mon Sep 17 00:00:00 2001 From: mnajafian-nv Date: Thu, 21 May 2026 14:06:02 -0700 Subject: [PATCH 2/2] docs: address migration guide review Signed-off-by: mnajafian-nv --- docs/getting-started/migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/getting-started/migration.md b/docs/getting-started/migration.md index ef157313d..315c2ec0f 100644 --- a/docs/getting-started/migration.md +++ b/docs/getting-started/migration.md @@ -30,7 +30,7 @@ with the [Quick Start](quick-start.md) instead. Use the table below to choose the first NeMo Flow path. Pick one path first, validate it, then add additional exporters or middleware. -| Starting point | First NeMo Flow path | +| Starting Point | First NeMo Flow Path | |---|---| | You own the direct tool or LLM call site | Use [Instrument Applications](../instrument-applications/about.md). | | A framework owns the tool or LLM call site | Use [Supported Integrations](../integrations/about.md) if one exists; otherwise use [Integrate into Frameworks](../integrate-frameworks/about.md). | @@ -59,7 +59,7 @@ stream. Use this mapping to translate current instrumentation concepts into NeMo Flow terms before changing code. -| Existing concept | NeMo Flow concept | +| Existing Concept | NeMo Flow Concept | |---|---| | LangChain callback run | Scope plus lifecycle event stream. | | OpenInference span | OpenInference subscriber output from NeMo Flow events. |