> This page is for NeMo Fabric, version v0.5.0.
> For other versions, use one of these documentation indexes:
> - Latest (v0.4.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.5.0: https://docs.nvidia.com/nemo/fabric/v0.5.0/llms.txt
> - v0.4.0: https://docs.nvidia.com/nemo/fabric/v0.4.0/llms.txt
> - v0.3.0: https://docs.nvidia.com/nemo/fabric/v0.3.0/llms.txt
> - v0.2.0: https://docs.nvidia.com/nemo/fabric/v0.2.0/llms.txt
> - v0.1.1: https://docs.nvidia.com/nemo/fabric/v0.1.1/llms.txt
> - v0.1.0: https://docs.nvidia.com/nemo/fabric/v0.1.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/fabric/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/nemo/fabric/_mcp/server.

# Use the LangChain Deep Agents Adapter

> Install and configure the NeMo Fabric harness integration for LangChain Deep Agents.

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:

```bash
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:

```bash
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:

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

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

```bash
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:

```bash
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`:

```python
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:

```python
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:

```python
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

> **Warning**
>
> `LocalShellBackend` executes commands directly on the adapter host with the host
> user's permissions. It provides no process isolation, and shell commands can
> bypass `virtual_mode` filesystem restrictions. Use it only with trusted input
> in a controlled environment. Do not use it for production or multi-tenant
> workloads.

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:

```python
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](https://github.com/NVIDIA/NeMo-Fabric/tree/v0.5.0/adapters/python/deepagents).