> This page is for NeMo Fabric, version v0.7.0.
> For other versions, use one of these documentation indexes:
> - Latest (v0.7.0) (default): https://docs.nvidia.com/nemo/fabric/latest/llms.txt
> - dev: https://docs.nvidia.com/nemo/fabric/dev/llms.txt
> - v0.7.0: https://docs.nvidia.com/nemo/fabric/v0.7.0/llms.txt
> - v0.6.1: https://docs.nvidia.com/nemo/fabric/v0.6.1/llms.txt
> - v0.6.0: https://docs.nvidia.com/nemo/fabric/v0.6.0/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.

# 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`.

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.

MCP-reported tool errors (`ToolException`) and argument validation failures return error tool messages to the model rather than aborting the invocation. Local argument-validation feedback includes field paths and reasons, such as `command: Field required`, without dumping argument payloads. The model can then correct a call. The adapter does not automatically retry or replay commands, and other exceptions still propagate.

The runtime starts even when some configured MCP servers are unavailable. A server that cannot be reached, or that does not list its tools within 60 seconds, is skipped, and the agent starts with the tools of the remaining servers. Each result from that runtime lists the skipped servers under `output.mcp.unavailable_servers`, with the server `name`, `transport`, `reason` (`failed`, `timed_out` or `authentication_required`) and `error_type`. The adapter also writes a warning to standard error. Error messages are not reported, because they can contain URLs, headers or other credentials. Discovery runs again on every runtime start, so a new runtime picks up a server that has recovered. Invalid server configuration, such as an unsupported transport or authentication mode, still fails startup.

MCP servers on `sse` or `streamable-http` can use `service_account` authentication (OAuth 2.0 client credentials). The adapter requests a token from `token_url` with the client secret read from the variable named by `client_secret_env`, sends it as a bearer token with each MCP request, and renews it before it expires. If the MCP server answers `401`, the adapter requests a new token and retries the request once. Tokens are kept in memory only. Startup fails for a `stdio` or `websocket` server, if the secret variable is unset, if `token_url` or the server `url` is not `https` (plain `http` is accepted only for a loopback host), or if the server also sets an `Authorization` custom header. A server is skipped and reported with reason `authentication_required` when its token endpoint rejects the client credentials (HTTP `400` or `401`), or when the MCP server still answers `401` after the token is renewed. Any MCP server that answers `401` during discovery, with or without `authentication`, is reported the same way. A token endpoint that cannot be reached, answers with another error status such as `5xx`, or returns no access token gives reason `failed`. The `local_shell` backend does not receive the secret variable. For servers that also need a second token in their own header, add it with `custom_headers` and a `${NAME}` reference; the adapter sends it unchanged with each request and does not renew it. Deep Agents does not support `oauth2` authentication.

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` 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.
Permission 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.

### Add Custom Python Tools and Middleware

The configuration names custom LangChain code that is already installed in the
adapter environment, as `package.module:attribute`. The adapter imports it when
the runtime starts; NeMo Fabric never fetches or installs it.

```python
from nemo_fabric import HarnessConfig, ToolDefinitionConfig, ToolsConfig

tools = ToolsConfig(
    definitions={
        "convert_units": ToolDefinitionConfig(
            kind="python", ref="acme_agent_ext.tools:convert_units"
        ),
        "erp_lookup": ToolDefinitionConfig(
            kind="python",
            ref="acme_agent_ext.tools:ErpLookup",
            settings={"endpoint": "https://erp.example.com/api"},
        ),
    },
)
harness = HarnessConfig(
    adapter_id="nvidia.fabric.langchain.deepagents",
    settings={
        "deepagents": {
            "middleware": [
                {
                    "ref": "acme_agent_ext.middleware:DateContext",
                    "settings": {"timezone": "Europe/Berlin"},
                }
            ]
        }
    },
)
```

A tool `ref` names a LangChain `BaseTool` instance, such as a `@tool`
function, or a `BaseTool` subclass that the adapter constructs with `settings`.
A middleware `ref` names a LangChain `AgentMiddleware` subclass. The adapter
rejects any other object without calling it. Each tool's name must equal its
definition key, so `tools.enabled` and `tools.blocked` apply to it. Custom
middleware runs on the main agent before NeMo Relay. The NeMo Fabric tool
policy checks each tool call both before and after it, and custom middleware
must implement the async hooks it wraps, such as
`awrap_model_call`. Planning checks the shape of each entry; a missing package
or attribute fails when the runtime starts. Refer to the adapter guide for the
complete rules.

## Skills

Configure skills with `skills.paths` or `skills.directories`. Skills load whether or not they are inside the workspace, and also without a workspace. Refer to [Configure Skills](/nemo/fabric/integrations/harness-integrations/configure-skills) for the shared rules.

* Each entry is one Deep Agents `skills` source, in list order. Deep Agents loads the source's immediate child folders that hold a `SKILL.md` with `name` and `description` in its front matter.
* The adapter routes each entry's skills into the Deep Agents backend at the path of the folder that holds them. File tools read and write the skills in place, and `local_shell` commands can run skill scripts at the same paths. Nothing is copied, and the mount decides whether the agent can change a skill.
* A `paths` entry that holds `SKILL.md` is one skill. Any other folder is a folder of skills. An absolute `paths` entry that exists only under the workspace, such as `/.agents/skills`, names that workspace folder and loads like any other entry.
* `skills.duplicates` accepts `reject`, `first_wins`, and `last_wins`. When it is left out, the copy from the later entry loads, as in Deep Agents.
* Deep Agents ships no bundled skills, so planning rejects `skills.bundled`.
* A missing or invalid entry, or two skills with the same name under `reject`, fails startup with `deepagents_skill_not_found` or `deepagents_skill_invalid` and names the field.
* Each result reports the loaded skills under `output.skills`, with any skipped candidates, empty entries, and duplicates.

## 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.7.0/adapters/python/deepagents).

## 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](/nemo/fabric/sdk/health-checks) for shared behavior and a comparison of native evidence across adapters.