epic: Support LangChain Deep Agents Code as a NemoClaw agent harness

Summary

Make LangChain Deep Agents Code (dcode) a supported NemoClaw agent harness.

The intended user-facing shape is a supported onboard path such as:

nemoclaw onboard --agent langchain-deepagents-code

or the final equivalent agent name, which creates a NemoClaw/OpenShell sandbox with LangChain Deep Agents Code installed and usable as the agent entry point.

Context

LangChain Deep Agents Code is an open source terminal coding agent built on the Deep Agents SDK. It supports provider/model selection, persistent memory, skills, MCP tools, web search, human approval for sensitive tool operations, interactive TUI use, and non-interactive runs.

Team context: this came up as the LangChain equivalent of the Hermes TUI. The ask is for NemoClaw to make it a supported harness rather than a one-off custom sandbox.

Problem

NemoClaw users should be able to choose LangChain Deep Agents Code as a first-class harness during onboarding, with the same level of support expected from other NemoClaw agent paths:

sandbox image/runtime setup,
provider and model wiring,
credential handling,
policy and tool approval behavior,
status/log diagnostics,
tests,
docs and launch material.

Without this, users can only experiment through custom images or manual setup, which is harder to support and harder to market.

Proposed Scope

Add a supported NemoClaw agent selector for LangChain Deep Agents Code.
Build or select a sandbox image with deepagents-code and required provider extras installed.
Launch the LangChain CLI entry point (dcode) or a NemoClaw wrapper around it.
Map NemoClaw provider/model settings into Deep Agents Code's --model, config, or environment-variable surface.
Preserve NemoClaw's secret handling model; do not leak provider keys into image layers, logs, registry state, or generated docs examples.
Support NVIDIA provider configuration where practical via langchain-nvidia-ai-endpoints / NVIDIA_API_KEY.
Decide how NemoClaw web search settings map to Deep Agents Code's Tavily-backed web_search support.
Add harness-specific setup validation, status output, logs, and troubleshooting.
Update docs, release notes, and web/marketing/demo material to list LangChain Deep Agents Code as a supported harness.

Open Questions

What should the canonical agent ID be: langchain-deepagents-code, deepagents-code, or something shorter?
Should NemoClaw prebuild a dedicated image variant, or install Deep Agents Code during sandbox image build?
Which provider extras should ship by default for launch: NVIDIA only, NVIDIA plus OpenAI/Anthropic/Gemini, or broader parity with NemoClaw providers?
Should the first release support both interactive TUI and non-interactive dcode -n, or make headless mode a follow-up?
Does NemoClaw need to disable Deep Agents Code auto-update inside managed sandbox images?
How should NemoClaw policy presets map onto Deep Agents Code approval controls and shell allow-list behavior?

Acceptance Criteria

References

LangChain Deep Agents Code overview: https://docs.langchain.com/oss/python/deepagents/code/overview
LangChain Deep Agents Code configuration: https://docs.langchain.com/oss/python/deepagents/code/configuration
LangChain model provider reference, including NVIDIA: https://docs.langchain.com/oss/python/deepagents/code/providers
LangChain remote sandbox docs: https://docs.langchain.com/oss/python/deepagents/code/remote-sandboxes

Stacked PR plan: LangChain Deep Agents Code harness

Summary

Build langchain-deepagents-code as a third NemoClaw agent runtime, using the Hermes-style manifest path rather than the OpenClaw plugin path. V1 supports both interactive dcode and headless dcode -n, routes NVIDIA and OpenAI-compatible models through OpenShell https://inference.local/v1, and keeps provider credentials out of .deepagents files.

Stacked PRs

Generic terminal-agent contract
- Extend the agent manifest/loader to support terminal-oriented agents with interactive and headless entry commands.
- Add lifecycle behavior for agents without a long-running gateway health surface: binary/version check, config sync, optional command smoke, and status metadata.
- Add unit tests with temporary manifests; do not expose Deep Agents Code yet.
Deep Agents Code image and manifest
- Add agents/langchain-deepagents-code/manifest.yaml, Dockerfile/base image setup, start wrapper, state dirs, and policy additions.
- Canonical agent ID is langchain-deepagents-code; no aliases in V1.
- Install deepagents-code plus the NVIDIA and OpenAI-compatible provider dependencies needed for the launch path.
- Preserve .deepagents state for config, memory, skills, threads, hooks, MCP config, and app state.
Deep Agents config generation
- Add a build-time config generator that writes /sandbox/.deepagents/config.toml and only non-secret env/config values.
- Configure the selected model against OpenShell’s managed route: base URL https://inference.local/v1, provider modeled as OpenAI-compatible unless the NVIDIA LangChain package path is explicitly required by the selected model.
- Use a placeholder API key value only where Deep Agents requires one; never write real provider keys into image layers, logs, generated config, or docs.
Interactive and headless command plumbing
- Make nemoclaw onboard --agent langchain-deepagents-code create a sandbox where dcode --version succeeds and the generated config is present.
- Define interactive launch as dcode from the sandbox workspace.
- Define headless launch as dcode -n "<prompt>", with shell execution disabled unless NemoClaw explicitly maps a policy-approved allow list to DEEPAGENTS_CODE_SHELL_ALLOW_LIST.
- Add user-facing errors for missing binary, missing config, unsupported inference API, and failed smoke runs.
Provider and web-search behavior
- Limit first-series provider support to NVIDIA plus OpenAI-compatible routing through existing NemoClaw provider selection.
- Treat Tavily web search as optional: configure it only when NemoClaw web-search setup has a credential; otherwise leave Deep Agents Code’s web search disabled with a clear status/troubleshooting message.
- Add policy entries for inference.local, required Python/package hosts, optional Tavily, and optional LangSmith tracing; do not enable unrelated Deep Agents remote sandbox providers in V1.
Status, logs, resume, rebuild, and backup
- Persist agent: langchain-deepagents-code and agent version in sandbox registry/session state.
- Ensure resume/rebuild preserves .deepagents state and re-syncs generated NemoClaw selection config.
- Make status/log output identify the LangChain Deep Agents Code harness, configured model/provider, and whether interactive/headless smoke checks passed.
Docs and CLI help
- Add docs for onboarding, interactive use, headless use, credential model, web search, state backup, and troubleshooting.
- Add a third docs guide variant only if the existing OpenClaw/Hermes variant generator can support it cleanly; otherwise add a focused single-agent page and defer full variant navigation.
- Do not regenerate or commit generated nemoclaw-user-* skills outside release prep.
E2E and acceptance PR
- Add scenario manifests for langchain-deepagents-code with NVIDIA/OpenAI-compatible provider routing.
- Validate onboard, resume, rebuild, dcode --version, interactive startup smoke, headless dcode -n smoke, state preservation, and no-secret leakage checks.
- Close the epic only after docs, unit tests, integration tests, and at least one sandbox E2E path pass.

Public interfaces

New supported agent ID: langchain-deepagents-code.
Existing command shape remains: nemoclaw onboard --agent langchain-deepagents-code.
Add terminal-agent manifest fields for interactive/headless commands and smoke behavior.
Add status/log text identifying terminal-agent health separately from gateway-agent health.
No new raw credential env vars are introduced for provider keys.

Test plan

Unit tests: manifest parsing, terminal-agent command resolution, config TOML generation, secret redaction, policy filtering, resume registry state.
Integration tests: non-interactive onboard selection, Dockerfile patching with NEMOCLAW_INFERENCE_BASE_URL, config sync, backup/restore of .deepagents.
E2E tests: NVIDIA/OpenAI-compatible route, dcode --version, interactive startup smoke, dcode -n headless smoke, rebuild/resume preservation, missing credential/provider errors.
Docs tests: variant rendering or focused-page navigation, npm run docs, and link validation.

Assumptions

V1 ships both interactive and headless support.
Canonical ID is exactly langchain-deepagents-code.
V1 provider scope is NVIDIA plus OpenAI-compatible routing through OpenShell.
Deep Agents Code remote sandbox providers are out of scope for V1 because NemoClaw’s OpenShell sandbox is the containment layer.
Messaging-channel support is out of scope for V1 unless Deep Agents Code later exposes a stable always-on gateway/channel integration.

@miyoungc

@miyoungc note for docs track to mark this experimental.

@wscurran

Design answers after Deep Agents Code review

I reviewed the current issue open questions, the stacked PR plan above, and upstream LangChain Deep Agents Code docs/source. Proposed answers and amendments:

Open questions

Canonical agent ID
- Use langchain-deepagents-code.
- Do not add aliases in V1. Display name can be LangChain Deep Agents Code, but the persisted agent ID should stay explicit and stable.
Image strategy
- Add a dedicated NemoClaw-managed image path under agents/langchain-deepagents-code/ with its own manifest, Dockerfile/base setup, start wrapper, policy additions, and state contract.
- Install deepagents-code during the sandbox image build, pinned by NemoClaw, rather than doing first-run or user-runtime installs inside the sandbox.
- Publishing/prebuilding can follow NemoClaw's existing managed-image flow, but the integration should not rely on ad hoc install steps after onboard.
Provider extras to ship
- Ship the base deepagents-code package plus the nvidia extra/provider dependency needed for langchain-nvidia-ai-endpoints.
- V1 support scope should still be narrower than the installed package surface: NVIDIA plus OpenAI-compatible routing through OpenShell https://inference.local/v1.
- Do not promise broad Anthropic/Gemini/etc. parity in V1 just because some provider packages are installed transitively by upstream Deep Agents Code.
Interactive vs headless
- V1 should support both interactive dcode and headless dcode -n "<prompt>".
- This is feasible because upstream already exposes --non-interactive/-n, and shell execution is disabled in non-interactive mode unless --shell-allow-list or DEEPAGENTS_CODE_SHELL_ALLOW_LIST is set.
- The first PR should add a generic terminal-agent contract before exposing Deep Agents Code, since current NemoClaw agent runtime assumptions are gateway/health-probe oriented.
Auto-update behavior
- Disable update checks/auto-updates in NemoClaw-managed images, for example with DEEPAGENTS_CODE_NO_UPDATE_CHECK=1 and by not enabling DEEPAGENTS_CODE_AUTO_UPDATE.
- Managed sandboxes should be reproducible; updates should happen through NemoClaw image rebuild/upgrade flows, not dcode self-mutation.
Policy presets and approval controls
- Keep OpenShell network policy as the outer enforcement boundary.
- Map NemoClaw's approved shell posture into Deep Agents Code using DEEPAGENTS_CODE_SHELL_ALLOW_LIST / --shell-allow-list only when NemoClaw has an explicit allow list.
- Default to no shell allow-list for headless runs. Do not map broad/permissive policy presets to all unless a future design explicitly accepts that risk.
- Treat remote Deep Agents sandbox providers (agentcore, daytona, modal, runloop, langsmith) as out of scope for V1 because NemoClaw/OpenShell is already the containment layer.

Amendments to the stacked plan

Mark docs experimental. Per @wscurran's note, all docs and launch material for this harness should label it experimental in V1.
Set HOME deliberately. Upstream Deep Agents Code stores config/state under Path.home()/.deepagents. The sandbox wrapper/image should make HOME=/sandbox (or otherwise align Path.home() with the manifest state directory) so generated config, runtime state, backup, and restore all target /sandbox/.deepagents.
Generate config, not credentials. NemoClaw should generate /sandbox/.deepagents/config.toml with model/provider metadata, base URL, model params, and env var names only. Do not generate ~/.deepagents/.state/auth.json with real provider keys.
Use scoped placeholder credentials only for managed inference. If Deep Agents Code requires an API key value to instantiate the LangChain provider, set a clearly non-secret placeholder via a scoped env var such as DEEPAGENTS_CODE_OPENAI_API_KEY for the inference.local route. Do not copy host/provider secrets into .deepagents files, image layers, logs, or registry state.
Prefer OpenAI-compatible routing first. Model https://inference.local/v1 as the OpenAI-compatible provider unless a specific selected model requires the NVIDIA LangChain package path and that path is covered by tests.
Force Chat Completions compatibility for the gateway. For the OpenAI-compatible route, generated config should set the OpenAI provider params to avoid the Responses API, for example use_responses_api = false, because many OpenAI-compatible gateways expose Chat Completions but not Responses.
Tavily remains optional. Configure web search only if NemoClaw has a Tavily credential to pass through; otherwise leave it disabled and surface a clear status/troubleshooting message.
MCP should be conservative. Preserve Deep Agents Code MCP config/state, but do not auto-trust project MCP configs beyond upstream's trust gate unless NemoClaw adds an explicit policy-backed decision.
Status should be terminal-agent aware. nemoclaw status should report binary/version check, generated config sync, selected provider/model, update-check disabled state, web-search status, shell allow-list posture, and interactive/headless smoke results rather than trying to force gateway-health semantics onto this runtime.

Revised V1 decision summary

V1 target: nemoclaw onboard --agent langchain-deepagents-code creates a NemoClaw/OpenShell sandbox with a pinned Deep Agents Code install, generated non-secret config for https://inference.local/v1, interactive dcode, headless dcode -n, disabled self-updates, optional Tavily, no remote Deep Agents sandbox providers, no messaging-channel support, and experimental docs.

Implementation update: PR #5197

PR #5197 now carries the first LangChain Deep Agents Code V1 harness slice for langchain-deepagents-code.

What is implemented in this PR:

Canonical agent ID: langchain-deepagents-code.
Runtime shape: terminal agent, not gateway agent. Interactive command is dcode; headless command is dcode -n.
Image strategy: dedicated managed image under agents/langchain-deepagents-code/, with deepagents-code[nvidia]==0.1.12 and uv==0.11.8 pinned in the image build.
Managed config: generated /sandbox/.deepagents/config.toml uses the OpenAI-compatible route at https://inference.local/v1, writes only non-secret model/provider metadata, and uses the placeholder DEEPAGENTS_CODE_OPENAI_API_KEY=nemoclaw-managed-inference for the managed route.
Compatibility setting: use_responses_api = false is emitted for the managed OpenAI-compatible provider because the current inference.local path is Chat Completions-compatible; removal condition is a future route capability check for Responses API support.
State contract: preserves .deepagents/.state, skills, config.toml, hooks.json, and .mcp.json; intentionally excludes .env.
Secret posture: provider/Tavily/LangSmith API keys are not written into generated config or image state; runtime env export is mode 0400 and no longer persists raw DEEPAGENTS_CODE_SHELL_ALLOW_LIST.
Managed execution posture: wrapper and image patch force sandbox mode to none, disable MCP loading, reject remote-sandbox/MCP/shell-allow-list CLI overrides, wrap dcode, dcode.real, and deepagents-code, remove the old exposed upstream dcode executable path, and patch direct python3 -m deepagents_code in the managed image back to the same NemoClaw posture.
Web search scope: Tavily remains follow-up. This PR removed the generic NEMOCLAW_WEB_SEARCH_ENABLED support signal for Deep Agents Code so onboarding does not advertise unsupported web-search wiring.
Docs: adds the experimental quickstart and README/index entry. Generated user skills are intentionally not regenerated outside release prep.

Amendments made after PR feedback:

Smoke checks now use an explicit exit-code marker instead of brittle output text matching.
Manifest parsing rejects malformed runtime.smoke_commands entries instead of silently filtering them.
Binary diagnostics distinguish not_executable from not_found for explicit binary_path failures.
Added terminal-runtime/onboard acceptance tests around fresh setup, resume behavior, smoke failures, real manifest command shape, and Deep Agents manifest contracts.
Closed the original dcode.real bypass, then closed the follow-up direct-module/shell-allow-list bypass with the managed image patch.
Scoped V1 web search to “not wired yet” by removing the generic web-search support marker.

Current validation state:

Local focused checks and hook-managed pre-commit/pre-push checks passed for the pushed commits.
PR status checks are running against head eda9780c300799fbb0c3992ec10dc4bb41224415.
Required Vitest E2E fan-out was dispatched for the same head: https://github.com/NVIDIA/NemoClaw/actions/runs/27325898678
E2E Advisor will auto-dispatch the required nightly set for the same head once the fresh advisor pass completes.

Scope that should remain open or be tracked as follow-up rather than using this PR to close the full epic:

Live built-sandbox proof for full runtime acceptance: fresh onboard, real dcode --version, interactive startup, headless dcode -n, managed inference request through https://inference.local/v1, and rebuild/upgrade state preservation.
Release notes plus web/marketing/demo material.
Broader human nemoclaw status diagnostics for terminal agents: binary/version, config sync, provider/model, web-search state, shell allow-list posture, and last smoke results.
Agent-specific E2E additions for secret boundary, wrapper hardening, and terminal-agent backup/rebuild.
Longer-term source-of-truth cleanup: replace the managed package patch with an upstream/config-level managed-mode contract if Deep Agents Code exposes one.

Follow-up after the latest PR feedback pass on #5197:

The PR now references this issue without closing it: Refs #4861. This issue should remain open for live built-sandbox Deep Agents acceptance, release/launch material, and fuller terminal-agent diagnostics.
The latest head (a0a1f12813fdf2e76ee2c37f45c076c6ee284315) adds the post-review amendments: no unsupported generic web-search support signal, direct-module/managed-wrapper hardening, raw shell allow-list env scoping, credential-bearing proxy URL omission from the persisted Deep Agents shell env, a focused regression test for that proxy handling, and a trusted-manifest note for shell-form terminal smoke commands.
PR-required checks are green. The E2E Advisor produced low-confidence empty output and skipped nightly dispatch, so I manually ran the Vitest E2E scenario workflow for this head. In that run, the quick jobs and both live scenario jobs passed; the only failure was the existing OpenClaw TUI correlation live test missing final OpenClaw chat replies after accepted sends, which does not exercise the new LangChain Deep Agents Code harness.

Tracked follow-ups for this issue remain the same: real Deep Agents built-sandbox onboard/start/headless inference evidence, release/launch material, broader terminal status diagnostics, built-image negative tests for managed posture, and a cleaner upstream/config contract for managed mode.

Update from PR #5197 at current head d327dd3720087b25551347e422e0b3c1f2846d2d:

The PR now carries the experimental LangChain Deep Agents Code harness end to end: agent manifest/image wrapper/config generation, terminal-agent runtime plumbing, CLI status/logs/connect/process-recovery handling, docs, and typed E2E metadata.
Review amendments landed: no generic web-search support signal, credential-bearing proxy env values are skipped including scheme-less user:pass@host forms, terminal agents without declared forwards do not get dashboard setup, dashboard runtime planning is defensive around malformed CHAT_UI_URL, and current main onboard extraction was merged to resolve the monolith-growth advisor blocker.
PR Review Advisor is clear of needs-attention items; CodeRabbit’s latest requested fixes are addressed; required PR checks are green.
E2E evidence on the current head: nightly sandbox-operations-e2e, inference-routing-e2e, and network-policy-e2e passed in run 27329688947; full Vitest scenario fan-out passed in run 27329760323.
Remaining open item: the explicit ubuntu-repo-cloud-langchain-deepagents-code typed scenario currently records a not-wired skip in run 27329760310, because the live Vitest fixture still assumes OpenClaw-style dashboard onboarding while this agent is terminal-only. Keeping epic: Support LangChain Deep Agents Code as a NemoClaw agent harness #4861 open for live built-sandbox acceptance, launch/release material, and deeper terminal-agent diagnostics.

Created follow-up parent #5617 for the remaining Deep Agents Code acceptance work after #5197, with these sub-issues:

Validate live Deep Agents Code sandbox acceptance #5618 — Live Deep Agents Code sandbox acceptance
Validate Deep Agents Code headless dcode inference #5619 — Headless dcode -n inference acceptance
Validate interactive Deep Agents Code TUI startup #5620 — Interactive dcode TUI acceptance
Define Deep Agents Code optional web search and tracing support #5621 — Optional Tavily/LangSmith integration policy and config
Prepare Deep Agents Code launch and release material #5622 — Launch, release, and demo material

Recommendation: merge #5197 as the supported harness foundation, then use #5617 and its sub-issues to close out the remaining live acceptance and launch work before closing this epic.

feat(agents): add Deep Agents Code harness (#5197)

fix(platform): add LangChain Deep Agents Code to the agents matrix

Closing this Epic. We've shipped the implementation, now hardening.

Navigation Menu

Repository navigation

epic: Support LangChain Deep Agents Code as a NemoClaw agent harness #4861

Summary

Context

Problem

Proposed Scope

Open Questions

Acceptance Criteria

References

14 remaining items

Stacked PR plan: LangChain Deep Agents Code harness

Summary

Stacked PRs

Public interfaces

Test plan

Assumptions

Design answers after Deep Agents Code review

Open questions

Amendments to the stacked plan

Revised V1 decision summary

Implementation update: PR #5197

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

epic: Support LangChain Deep Agents Code as a NemoClaw agent harness #4861

Description

Summary

Context

Problem

Proposed Scope

Open Questions

Acceptance Criteria

References

Activity

14 remaining items

cv commented on Jun 8, 2026

Stacked PR plan: LangChain Deep Agents Code harness

Summary

Stacked PRs

Public interfaces

Test plan

Assumptions

wscurran commented on Jun 8, 2026

cv commented on Jun 11, 2026

Design answers after Deep Agents Code review

Open questions

Amendments to the stacked plan

Revised V1 decision summary

cv commented on Jun 11, 2026

Implementation update: PR #5197

cv commented on Jun 11, 2026

cv commented on Jun 11, 2026

cv commented on Jun 23, 2026

wscurran commented on Jul 2, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions