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.

Set harness.settings.reasoning_effort to none, minimal, low, medium, high, or xhigh to pass a reasoning effort to ChatOpenAI. For example, settings={"reasoning_effort": "none"} disables reasoning on endpoints that support that value. This setting requires an OpenAI-compatible provider, and the endpoint must support the selected value. Omit the setting to preserve the model default. Subagents inherit the setting when they inherit the main model; a subagent with its own model override uses that model’s defaults.

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 or named by environment.env_names are passed to shell commands and are available to agent-generated commands. If neither sets 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.

On POSIX, with local_shell, file tools accept absolute paths inside environment.workspace as aliases for workspace files. For example, with workspace /app, both file-tool paths /app/report.txt and /report.txt refer to /app/report.txt on disk. Shell commands use host paths and start in the workspace, so cat report.txt and cat /app/report.txt read that file.

On POSIX, listings and searches return canonical physical paths inside the workspace. These paths identify the same file in subsequent reads and edits, even when a nested directory repeats the workspace prefix. For example, /app/app/report.txt remains distinct from /app/report.txt; the relative file-tool path app/report.txt also identifies the nested file.

On Windows, listings and searches retain workspace-rooted virtual paths, such as /nested/report.txt. Use these paths with file tools; Deep Agents rejects drive-prefixed paths such as C:/workspace/nested/report.txt before backend resolution. Shell commands continue to use native host paths.

File-tool traversal and symlink-escape checks remain enabled. Paths outside the workspace retain the existing virtual-root interpretation; they do not grant access to host files.

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.

Runtime Health

Fabric.check() supports live, active, and ready. The adapter checks the owned checkpoint connection, the compiled graph interface, and a fresh native state response for the selected thread.

Refer to the SDK health-check overview for shared behavior and a comparison of native evidence across adapters.