Use the LangChain Deep Agents Adapter

The NVIDIA NeMo Fabric nvidia.fabric.langchain.deepagents adapter runs LangChain Deep Agents in the persistent NeMo Fabric Python adapter host. The adapter maps normalized NeMo Fabric configuration into the model, tools, skills, Model Context Protocol (MCP) servers, workspace, and telemetry.

Install the Adapter

To install the NeMo Fabric runtime, adapter, and supported LangChain Deep Agents dependencies in one environment:

pip install "nemo-fabric[deepagents]"

To install the adapter and supported Deep Agents stack without the NeMo Fabric runtime, use the adapter package’s harness extra:

pip install "nemo-fabric-adapters-deepagents[harness]"

The adapter package also provides relay and full extras. Use relay when the environment already manages the Deep Agents stack. Use full to install the stack and NeMo Relay Python package together.

To install the runtime, adapter, supported Deep Agents stack, and NeMo Relay Python package in one environment:

pip install "nemo-fabric[deepagents,relay]"

If the environment already manages a compatible Deep Agents stack, install only the adapter:

pip install nemo-fabric-adapters-deepagents

The bare adapter package does not install the NeMo Fabric runtime or harness. Use deepagents>=0.6.12,<0.8.0, langchain>=1.3,<2.0, and langgraph>=1.2,<2.0, the constraints supported by this release.

If the existing compatible Deep Agents stack and NeMo Fabric runtime share an environment, install the runtime and bare adapter together:

pip install nemo-fabric nemo-fabric-adapters-deepagents

For separate environments, set ADAPTER_PYTHON in the runtime environment to the adapter environment’s Python interpreter. Use matching NeMo Fabric release versions for the runtime and adapter package unless a different pairing has been explicitly validated.

Configure the Adapter

Select the LangChain Deep Agents harness integration in HarnessConfig:

from nemo_fabric import HarnessConfig
harness = HarnessConfig(adapter_id="nvidia.fabric.langchain.deepagents")

Configure nucleus sampling and the response token limit with the normalized models.<role>.top_p and models.<role>.max_tokens fields. top_p must be from 0 through 1, and max_tokens must be a positive integer:

from nemo_fabric import ModelConfig
model = ModelConfig(
    provider="nvidia",
    model="nvidia/nemotron-3-nano-omni-30b-a3b-reasoning",
    api_key_env="NVIDIA_API_KEY",
    base_url="https://integrate.api.nvidia.com/v1",
    top_p=0.8,
    max_tokens=512,
)

The adapter passes these fields to LangChain only when configured, so omitted fields preserve the model provider’s defaults. Planning rejects unknown top-level model fields and every key under models.<role>.settings.

Use normalized FabricConfig fields to configure the model, workspace, skills, MCP servers, replacement system instructions, blocked tools, and telemetry. The adapter rejects append system instructions. Use harness.settings.deepagents to configure the JSON-serializable Deep Agents-native interrupt_on and subagents options:

from nemo_fabric import HarnessConfig
harness = HarnessConfig(
    adapter_id="nvidia.fabric.langchain.deepagents",
    settings={
        "deepagents": {
            "interrupt_on": {
                "write_file": {
                    "allowed_decisions": ["approve", "edit", "reject"],
                    "description": "Review this file write.",
                }
            },
            "subagents": [
                {
                    "name": "researcher",
                    "description": "Researches the workspace before implementation.",
                    "system_prompt": "Investigate the request and return concise findings.",
                }
            ],
        }
    },
)

The descriptor closes both harness.settings and its nested deepagents object, so planning rejects unknown settings before runtime start. The optional backend object accepts only {"type": "local_shell"}. Omit it to preserve the existing filesystem or Deep Agents default backend behavior. runtime.max_turns=10 configures LangGraph with recursion_limit=10. This is a graph-superstep budget, not a promise of ten model responses or tool calls. One interaction can consume multiple supersteps. When runtime.max_turns is omitted, the adapter keeps the Deep Agents default. interrupt_on maps tool names to booleans or an object with allowed_decisions; supported decisions are approve, edit, reject, and respond. The object can also contain a static description and an args_schema JSON Schema.

Enable Local Shell Execution for a Supervised Demo

The adapter requires environment.workspace and an explicit Fabric tool policy when local_shell is selected. The policy is applied to the main agent and all declarative subagents, including a subagent that replaces the parent’s interrupt_on map. Include execute in tools.enabled to permit commands; omit it from that allowlist or add it to tools.blocked to prevent commands.

Do not configure interrupt_on.execute with local_shell. The current adapter lifecycle cannot surface and resume a LangGraph approval interrupt, so the adapter rejects that combination instead of reporting an interrupted command as a completed turn.

The following configuration opts in to local shell execution and limits the tool surface to execute. Because it does not provide per-command approval, use it only with trusted input under direct operator supervision:

from nemo_fabric import EnvironmentConfig, HarnessConfig, ToolsConfig
harness = HarnessConfig(
    adapter_id="nvidia.fabric.langchain.deepagents",
    settings={
        "deepagents": {"backend": {"type": "local_shell"}}
    },
)
environment = EnvironmentConfig(
    provider="local",
    workspace="/path/to/supervised-demo",
)
tools = ToolsConfig(enabled=["execute"])

LocalShellBackend keeps inherit_env=False, so commands do not inherit ambient adapter-host variables such as HOME. Values explicitly configured in environment.env are passed to shell commands and are available to agent-generated commands. If environment.env does not set PATH, the shell provides only its fallback path. Configure the required variables explicitly and use absolute executable paths when needed. The execute tool remains subject to tools.enabled and tools.blocked, like all other Deep Agents built-ins.

File tools and shell commands use different absolute-path namespaces when virtual_mode=True. For file tools, /report.txt resolves to <workspace>/report.txt; in execute, the same path refers to /report.txt on the adapter host. Shell commands start in environment.workspace, so use workspace-relative paths, such as cat report.txt, for files surfaced by file tools. Do not pass a file tool’s virtual absolute path directly to execute.

subagents accepts declarative synchronous subagents and Agent Protocol asynchronous subagents. A declarative subagent requires name, description, and system_prompt. An asynchronous subagent requires name, description, and graph_id. Refer to the adapter guide for the supported optional fields. Python middleware, permission objects, Python tool objects, and precompiled subagents cannot cross the JSON configuration boundary. NeMo Fabric rejects an asynchronous subagent when tools.enabled or tools.blocked is configured because a local tools policy cannot gate remote tools.

Understand the Runtime Lifecycle

Each NeMo Fabric runtime compiles one Deep Agents graph and retains its checkpointer and LangGraph thread across ordered invocations. The built-in and caller-defined declarative subagents are separate locally compiled graphs invoked through the task tool. They inherit the parent run’s model, tools, skills, workspace, telemetry, and permissions. runtime.max_turns configures only the main local graph, while declarative subagent graphs retain their Deep Agents limits. Agent Protocol subagents run in a separate service and manage their own recursion limit.

NeMo Relay provides the SDK-native observability integration for this adapter. Native OpenTelemetry and OpenInference exporters are also available through the model provider configuration.

For the complete configuration, subagent, lifecycle, and telemetry reference, refer to the LangChain Deep Agents adapter guide.