Migration Guide#

NeMo Agent Toolkit deprecation#

Attention

⚠️ Deprecation Notice: NVIDIA NeMo Agent Toolkit has been deprecated as of October 2026 and will reach end of life (EOL) by end of year 2026. Depending on your needs, migrate to: NeMo Relay for observability, middleware, and governance. NeMo Helix for a unified CLI with evaluation, optimization, and hardening capabilities. NeMo Fabric for a consistent interface to run agent harnesses and custom agents. We recommend completing your migration before the EOL date.

Alternatives#

Choose the projects that match the capabilities you use in NeMo Agent Toolkit. You can use them together when your application needs observability, agent execution, and evaluation or optimization.

NeMo Relay: Observability, Middleware, and Governance#

NVIDIA NeMo Relay provides visibility into and control over agent runs without requiring changes to the existing agent stack. It gives applications, coding agents, and framework integrations a shared runtime for scopes, policy, plugins, and lifecycle events.

Use NeMo Relay to instrument LLM and tool calls, capture agent trajectories, and export traces, logs, and metrics to observability backends. Its plugin system supports reusable middleware and exporters. Start with the NeMo Relay documentation.

NeMo Fabric: Agent Harness and Custom Agent Execution#

NVIDIA NeMo Fabric gives applications, evaluation systems, and rollout platforms a consistent interface for running agent harnesses and custom agents. It separates the application integration from the execution target through adapters.

Use NeMo Fabric to configure models, tools, skills, and MCP servers, validate supported configurations before execution, and collect normalized results, errors, artifacts, and telemetry references. Capabilities vary by adapter; consult the adapter compatibility matrix when selecting a harness.

NeMo Helix: Evaluation, Optimization, and Hardening#

NVIDIA NeMo Helix is an open-source control plane for improving and hardening production agents. It runs on your infrastructure and exposes repeatable workflows through a unified CLI, REST APIs, and a Python SDK.

Use NeMo Helix to evaluate agent behavior, optimize prompts and configurations, and test agent safety with guardrails and red-teaming tools. Its modular plugins let you connect agent execution, sandboxing, storage, secrets, and other infrastructure to your platform. Start with the NeMo Helix documentation.

Version Specific Changes#

v1.9.0#

Redis Package Migration#

Redis memory and object store support moved from the in-repository nvidia-nat-redis implementation to the Redis-maintained nemo-agent-toolkit-redis package.

This provider migration preserves the supported NeMo Agent Toolkit interfaces. The nvidia-nat[redis] extra, the historical nvidia-nat-redis distribution name, Python imports under nat.plugins.redis, and the existing Redis component configuration names continue to work through the compatibility package.

For new projects, install the Redis plugin package directly:

pip install nemo-agent-toolkit-redis

Alternatively, install the NeMo Agent Toolkit Redis extra:

pip install "nvidia-nat[redis]"

Existing configurations that use _type: redis or _type: redis_memory continue to work after the Redis plugin package is installed. The external package also provides the redis_agent_memory_backend and redis_agent_memory_auto_memory component types.

The historical nvidia-nat-redis distribution remains as a no-code compatibility package that depends on nemo-agent-toolkit-redis. New projects should install nemo-agent-toolkit-redis directly. Report Redis integration bugs and package release issues in the Redis plugin issue tracker.

The external plugin requires redis>=5.0.0,<6.0.0, replacing the previous redis>=4.3.4,<5.0.0 constraint. Environments that explicitly constrain the Redis Python client to a version earlier than 5.0.0 must update that constraint.

v1.8.0#

Tavily Internet Search Package Migration (Breaking)#

Tavily web search support moved from the LangChain-backed tavily_internet_search function in nvidia-nat[langchain] to the provider-managed nemo-agent-toolkit-tavily package.

This is a breaking change for workflows that configure:

functions:
  internet_search:
    _type: tavily_internet_search

Those workflows no longer get Tavily search by installing only nvidia-nat[langchain]. Install the Tavily package and migrate the configuration to a function group:

pip install nemo-agent-toolkit-tavily

function_groups:
  internet_search:
    _type: tavily
    include: [search]

workflow:
  tool_names: [internet_search__search]

The old _type: tavily_internet_search remains registered as a migration stub in nvidia-nat-langchain, but it raises an error with these migration instructions instead of performing a search. The old implementation depended on langchain-tavily; the new package uses the public NeMo Agent Toolkit plugin API and is not limited to LangChain workflows.

Workflow YAML environment variable interpolation#

Bare $VAR (without braces) is not supported. Use ${VAR} instead.

Configuration loading only expands braced environment references (${VAR}, ${VAR:-default}). Bare $VAR in a workflow YAML file is left unchanged and is not read from the environment.

Previously, the loader applied shell-style expansion to the entire config file, so bare $VAR could be substituted (and $ inside longer strings could be altered unintentionally).

To migrate:

  • Replace bare references with braced form, for example api_key: $OPENAI_API_KEY → api_key: ${OPENAI_API_KEY}.

  • See Environment Variable Interpolation for supported syntax.

v1.6.0#

User Identity Resolution#

User identity is now resolved by a centralized UserManager component. The following changes apply:

  • User IDs are now UUID v5 hashes. Previously, user IDs were raw credential strings (cookie values, JWT claim values). They are now deterministic UUID v5 values derived from the credential. User IDs are opaque routing keys — no downstream code depends on a specific format.

  • JWT claim precedence corrected to RFC 7519. The previous precedence (name > email > preferred_username > sub) was non-standard. The new precedence is sub > email > preferred_username per RFC 7519 and OpenID Connect Core 1.0. Users whose identity was previously resolved from the name claim will be assigned a new user_id based on sub after upgrade.

  • Security model removed from WebSocket messages. The Security Pydantic model and the security field on WebSocketUserMessage and WebSocketUserInteractionResponseMessage have been removed. User identity is now resolved via the auth_message flow or from connection headers. See User Identity Resolution for details.

Evaluator Package Split (Breaking)#

As part of dependency reduction, evaluator ownership is being moved out of nvidia-nat-eval and into framework-specific packages.

  • trajectory evaluator moved to nvidia-nat-langchain.

  • tunable_rag_evaluator moved to nvidia-nat-langchain.

  • ragas evaluator moved to nvidia-nat-ragas.

  • Performance evaluators moved to nvidia-nat-profiler:

    • avg_llm_latency

    • avg_workflow_runtime

    • avg_num_llm_calls

    • avg_tokens_per_llm_end

  • nvidia-nat-eval no longer includes a direct ragas dependency.

  • swe_bench evaluator has been removed (no replacement package in this release).

This is a breaking change:

  • nvidia-nat-eval no longer owns these built-in evaluator implementations.

  • nvidia-nat-langchain now imports evaluator base contracts from nvidia-nat-eval.

  • If nvidia-nat-langchain is installed without nvidia-nat-eval, LangChain evaluator registration imports can fail.

To migrate:

  • Install both packages when using these evaluators:

    • pip install "nvidia-nat-eval" nvidia-nat-langchain

  • Install the RAGAS evaluator package when using _type: ragas:

    • pip install nvidia-nat-ragas

  • Install the profiler package when using performance evaluators or profiling workflows:

    • pip install nvidia-nat-profiler

    • Note: the previous dependency group name nvidia-nat-profiling is now nvidia-nat-profiler.

  • Keep evaluator config names unchanged (trajectory, tunable_rag_evaluator, avg_llm_latency, avg_workflow_runtime, avg_num_llm_calls, avg_tokens_per_llm_end).

  • Remove any _type: swe_bench evaluator entries from evaluation configurations.

  • If you only need custom evaluators, keep nvidia-nat-eval installed for evaluator contracts and do not rely on moved built-ins.

Eval Exporter Callback Split#

Eval metric exporting now uses generic eval-callback hooks owned by nvidia-nat-eval, while provider-specific implementations live in provider packages.

  • Weave eval metric export callback now lives in nvidia-nat-weave.

  • nvidia-nat-eval no longer hard-couples directly to Weave internals for eval metric publishing.

  • If a telemetry exporter is configured but its eval callback provider package is missing, nvidia-nat-eval now logs a warning and continues evaluation without exporter publishing.

To migrate:

  • Install the matching provider package for configured telemetry exporters (for Weave: pip install nvidia-nat-weave).

  • Keep existing telemetry exporter config names unchanged (for example _type: weave).

Eval CLI Command Package Split#

CLI command ownership is now aligned to package domains:

  • nat eval is provided by nvidia-nat-eval.

  • nat sizing is provided by nvidia-nat-profiler.

  • nat red-team is provided by nvidia-nat-security.

To migrate:

  • Install command-specific packages as needed:

    • pip install "nvidia-nat[eval]"

    • pip install "nvidia-nat-eval[full]"

    • pip install nvidia-nat-profiler

    • pip install nvidia-nat-security

Configuration Optimizer Package Extraction (Breaking)#

Optimizer ownership now lives in the optional nvidia-nat-config-optimizer package.

This is a breaking change:

  • The nat optimize command is no longer owned by core and is only available when nvidia-nat-config-optimizer is installed.

  • Optimizer implementation modules moved from core paths into nat.plugins.config_optimizer.*.

  • The nvidia-nat[optimizer] extra has been renamed to nvidia-nat[config-optimizer].

To migrate:

  • Install config optimizer support when needed:

    • pip install "nvidia-nat[config-optimizer]"

    • pip install nvidia-nat-config-optimizer

  • Update optimizer imports:

    • nat.parameter_optimization.prompt_optimizer => nat.plugins.config_optimizer.prompts.ga_prompt_optimizer

    • nat.parameter_optimization.parameter_optimizer => nat.plugins.config_optimizer.parameters.optimizer

    • nat.parameter_optimization.optimizer_runtime => nat.plugins.config_optimizer.optimizer_runtime

  • Keep optimizer callbacks at their core path:

    • nat.profiler.parameter_optimization.optimizer_callbacks

v1.5.0#

Removing Old Aliases and Transitional Packages#

NVIDIA NeMo Agent Toolkit 1.2 changed the name and API. Compatibility aliases and transitional packages were provided to reduce development friction. Since three releases have passed, compatibility aliases and transitional packages are now removed.

  • aiqtoolkit transitional package is removed. Use nvidia-nat.

  • All AIQ compatibility aliases have been removed.

  • aiq module is removed. Use nat instead.

  • The aiq command is removed. Use nat instead.

Packaging Restructure#

  • NeMo Agent Toolkit adds support for new libraries, frameworks, and integrations. With these added subpackages, conflicting dependencies have arisen.

  • nvidia-nat is now a meta-package. All code has been moved into nvidia-nat-core

  • All prior meta-packages have been removed.

    • nvidia-nat-all (no replacement, though nvidia-nat[most] extra does exist)

    • nvidia-nat-ingestion (no replacement; examples directly use dependencies)

    • nvidia-nat-profiling (use nvidia-nat[profiler])

Evaluation Package Split#

Evaluation and profiling implementations moved out of core into the nvidia-nat-eval and nvidia-nat-profiler packages.

To migrate:

  • Install evaluation support when needed:

    • pip install "nvidia-nat[eval]"

    • pip install nvidia-nat-eval

  • Install profiling support when needed:

    • pip install "nvidia-nat[profiler]"

    • pip install "nvidia-nat[eval, profiler]"

  • Treat these commands as eval-owned commands that require nvidia-nat-eval: nat eval, nat red-team, and nat sizing.

Import Path Changes#

For users migrating existing integrations, the primary import change is (old => new):

  • nat.eval.* => nat.plugins.eval.*

  • nat.profiler.* => nat.plugins.eval.profiler.* (except nat.profiler.parameter_optimization.*, which remains in core)

  • nat.eval.runtime_event_subscriber.pull_intermediate => nat.builder.runtime_event_subscriber.pull_intermediate

For evaluation data models, prefer canonical core paths:

  • nat.data_models.evaluator for EvalInput* / EvalOutput*

  • nat.data_models.evaluate_runtime for EvaluationRunConfig / EvaluationRunOutput

  • nat.data_models.token_usage.TokenUsageBaseModel for token usage counters (replaces nat.plugins.eval.profiler.callbacks.token_usage_base_model)

Internal module reorganization inside nat.plugins.eval is implementation detail and may change between releases.

nat.eval Deprecation Shim#

Core provides a temporary compatibility shim for nat.eval imports.

What to expect:

  • Importing from nat.eval emits a UserWarning that the path is deprecated.

  • The shim requires nvidia-nat-eval to be installed.

  • Update imports to externally supported nat.plugins.eval.* and nat.data_models.* paths now, because the shim will be removed in a future major release.

v1.4.0#

Weave Trace Identifier Namespace#

Weave trace identifiers now use the nat namespace.

If you depend on Weave trace names, update your dashboards and alert filters:

  • Replace any old namespace prefixes (aiq) with nat.

  • Re-run any saved queries that filter on trace or span names.

Calculator Function Group Migration#

The calculator tools moved to a single function group with new names and input schemas.

Update your configurations and tool calls:

  • Use the calculator function group with names such as calculator__add and calculator__compare.

  • Pass numeric arrays for arithmetic inputs instead of parsing strings.

Sensitive Configuration Fields Use Secret Types#

Sensitive configuration fields now use Pydantic SecretStr types for redaction and serialization.

If you read or set secret fields in code:

  • Use .get_secret_value() when you need the raw value.

  • Update any tests that compare secrets to expect SecretStr behavior.

Zep Cloud v3 Migration#

The Zep Cloud integration now targets the v3 API and thread-based memory.

To migrate existing Zep configurations:

  • Upgrade your dependency to zep-cloud~=3.0.

  • Update any session-based references to thread-based APIs and ensure conversation_id is set for per-thread storage.

LLM and Embedder Model Dump Changes#

All LLM and embedder providers now use exclude_unset=True for model_dump.

If you rely on implicit defaults being forwarded:

  • Set explicit values in your configuration for fields you need to send.

  • Update any custom providers that serialize configuration files to use the same behavior.

Per-User Function Instantiation#

Functions and function groups can now be registered as per-user components.

If you enabled per-user workflows:

  • Register per-user functions with @register_per_user_function() and ensure schemas are explicit.

  • Verify your nat serve usage sets a nat-session cookie so per-user workflows can resolve a user ID.

Removal of default_user_id in General config#

The default_user_id field was removed to prevent unsafe per-user workflow sharing.

To migrate existing configurations:

  • Remove default_user_id from the general configuration section.

  • For nat run and nat eval, set the new user_id fields in ConsoleFrontEndConfig and EvaluationRunConfig.

Function Group Separator Change#

Function group names now use __ instead of ..

To migrate:

  • Update function names from group.function to group__function in configuration files and tool calls.

  • Watch for deprecation warnings if you still use the legacy separator.

MCP Frontend Refactor#

MCP server and frontend code moved into the nvidia-nat-mcp package.

Update your MCP usage:

  • Import MCPFrontEndPluginWorker from nat.plugins.mcp.server.front_end_plugin_worker.

  • Recommended: migrate any mcp_tool_wrapper usage to mcp_client.

nvidia-nat-all Packaging Changes#

The nvidia-nat-all meta-package removed conflicting optional dependencies.

If you rely on extras:

  • Reinstall nvidia-nat-all and review the updated optional dependency list.

  • Install additional frameworks explicitly when needed to avoid conflicts.

v1.3.0#

CLI Changes#

The MCP server CLI commands have been restructured.

  • nat mcp is now a command group and can no longer be used to start the MCP server.

  • nat mcp serve is now the main command to start the MCP server.

  • nat info mcp has been removed. Use the new nat mcp client command instead.

Listing MCP Tools:

# Old (v1.2)
nat info mcp
nat info mcp --tool tool_name

# New (v1.3)
nat mcp client tool list
nat mcp client tool list --tool tool_name

Pinging MCP Server:

# Old (v1.2)
nat info mcp ping --url http://localhost:9901/sse

# New (v1.3)
nat mcp client ping --url http://localhost:9901/mcp

API Changes#

API Server Data Models#

The nat.data_models.api_server module has been updated to improve type safety and OpenAI API compatibility.

Builder get_* methods switched to asynchronous#

The following builder methods have been switched to asynchronous to be aligned with other builder methods.

  • nat.builder.Builder.get_function() is now marked as async

  • nat.builder.Builder.get_functions() is now marked as async

  • nat.builder.Builder.get_memory_client() is now marked as async

  • nat.builder.Builder.get_memory_clients() is now marked as async

  • nat.builder.Builder.get_tool() is now marked as async

  • nat.builder.Builder.get_tools() is now marked as async

Migration example:

# Old (v1.2)
function = builder.get_function("my_function")

# New (v1.3)
function = await builder.get_function("my_function")
MCP Default Transport Changed#

  • v1.2: Used SSE transport at http://localhost:9901/sse

  • v1.3: Uses streamable-http transport at http://localhost:9901/mcp

To use SSE transport for backward compatibility:

nat mcp serve --config_file config.yml --transport sse

Warning

SSE transport does not support authentication. For production deployments, use streamable-http transport with authentication configured.

Package Changes#

Core MCP functionality has been moved to the nvidia-nat-mcp package.

If you are using MCP functionality, you will need to install the nvidia-nat[mcp] extra.

Package Dependency Updates#

The following dependency updates may affect your workflows:

  • mcp updated from ~1.10 to ~1.13 - Update your MCP server configurations if needed

  • uvicorn limited to <0.36 for nest_asyncio compatibility

  • langchain-core updated to ~0.3.75 - Review any custom LangChain workflows for compatibility

  • langgraph updated to ~0.6.7 - Review any custom LangGraph workflows for compatibility

  • crewai updated to ~0.193.2 - Review any custom CrewAI workflows for compatibility

  • semantic-kernel updated to ~1.35 - Review any custom Semantic Kernel workflows for compatibility

Deprecations#

Warning

The following features are deprecated and will be removed in a future release.

  • nat.telemetry_exporters.weave.WeaveTelemetryExporter.entity - The entity field is deprecated. Remove this field from your Weave exporter configuration.

  • use_uvloop configuration option - This setting in the general section of the config is deprecated. Remove this option from your workflow configurations.

v1.2.0#

Package Changes#

  • The aiqtoolkit package has been renamed to nvidia-nat.

Warning

aiqtoolkit will be removed in a future release and is published as a transitional package.

Module Changes#

  • The aiq module has been deprecated. Use nat instead.

Warning

aiq will be removed in a future release.

CLI Changes#

  • The aiq command has been deprecated. Use nat instead.

Warning

The aiq command will be removed in a future release.

API Changes#

Note

Compatibility aliases are in place to ensure backwards compatibility, however it is strongly encouraged to migrate to the new names.

v1.1.0#

Package Changes#

  • The agentiq package has been renamed to aiqtoolkit.

Warning

agentiq will be removed in a future release and is published as a transitional package.