LangChain’s own coding-agent CLI carries a confession in its README: “This project was primarily inspired by Claude Code, and initially was largely an attempt to see what made Claude Code general purpose, and make it even more so” [1]. That is not a third party’s guess about Anthropic’s architecture. It is a competing vendor naming its own source of inspiration in its own documentation, for a tool it ships today.
That admission matters because the architecture underneath it is no longer proprietary. pip install deepagents [2] pulls down an open-source, model-agnostic harness that reimplements four structural patterns Claude Code, Manus, and OpenAI’s Deep Research all share: a planning tool that does nothing, a virtual file system, sub-agents that forget on purpose, and a system prompt where most of the real instruction lives inside individual tool descriptions rather than in one long block of text. LangChain’s own name for this class of agent is a “deep agent” [3], and the point of this article is to build one, pillar by pillar, using the exact schemas the open-source package ships, then follow the same architecture into a browser-automation contract that three agent hosts now share and into the production tooling LangChain shipped around it this month.
Figure 1 - The four pillars inside the three-layer stack: The four pillars this article builds are the harness layer specifically, the layer between the business logic you supply and the infrastructure a production deployment needs on top of it. Nothing here is proprietary; it installs with one command.
Three layers, one harness
Before opening the package, it helps to place it. When LangChain walked through their own packaged product, they split a deployed agent into three layers [4]. Business logic, prompts, skills, tools, and sub-agent definitions, is supplied entirely by whoever builds the agent. No framework or model can substitute for it. The harness is deepagents itself, described in that same walkthrough as “an open-source model-agnostic harness” [4] that orchestrates calls to the model and drives the tool-calling loop. Infrastructure is everything a production run needs beyond the loop: durable execution, sandboxes, context storage a non-developer can edit, evals, authorization, and memory.
This article lives almost entirely in the middle layer. The four pillars below are what deepagents gives you the moment you import it. The last two sections cover what changes when that harness meets real infrastructure, including a product that shipped some of layer three into public beta the same week this research was verified.
Pillar 1: a planning tool that does nothing
Every deep agent LangChain has surveyed exposes a to-do or planning tool to the model, and the tool’s defining property is that it does nothing at the code level. It writes to no database, maintains no persistent object, and takes no action outside the conversation. LangChain’s own description is blunt: it is “basically a chance for the model to come up with a to-do list” [3], and the implementation backing it runs fewer than 20 lines [5].
deepagents’ version of this tool is write_todos. Every call takes the entire to-do list as one payload and overwrites whatever list existed a moment before. The model cannot edit a single item; it regenerates the whole thing on every update. That sounds wasteful until you notice where the list actually lives: not in a service the tool queries, but in the sequence of the model’s own messages, sitting in the same context window it is already reading on every turn. The list is the data structure. The context window is the storage.
What makes the tool useful is not the 20 lines of code behind it [5]. It is roughly 180 lines of docstring [5] describing when to call the tool, when not to, how an item moves from pending to in_progress to completed, and worked examples of good and bad task decomposition. LangChain’s walkthrough describes Claude Code’s own to-do tool as the identical shape [5]: state lives entirely in the model’s own context, never in an external store the tool calls out to.
Figure 2 - The noop planning tool: The implementation is trivial. The description is not. write_todos overwrites the entire list on every call, and the list survives only because it sits in the messages the model already reads.
KEY INSIGHT: A planning tool earns its keep almost entirely from its description, not its implementation. If your own agent’s to-do tool is a two-line stub, the 180 lines you are missing are the ones that actually teach the model how to plan.
Pillar 2: the virtual file system, and the one rule that governs it
As an agent runs for many steps, its context window fills up and its performance degrades before it ever hits a hard token limit. The fix deepagents ships is a virtual file system: a named location the agent can write a large observation to, reference with a short pointer in its own context, and read back only when needed. The agent gets tools for it: ls, read_file, write_file, and edit_file.
Two tool schemas copied from Claude Code on purpose
read_file and edit_file are not designed from scratch. read_file reads up to 2,000 lines from the start of a file by default, accepts optional offset and limit parameters, truncates lines over 2,000 characters, and returns content in cat -n format with line numbers prefixed [5]. edit_file uses exact old_string/new_string replacement rather than line-range patching, with a replace_all flag for non-unique strings. Both are Claude Code’s own Read and str_replace schemas, reproduced verbatim rather than redesigned, because the walkthrough’s stated rationale is that Anthropic trained its models on this function [5]. If a model is fine-tuned on a specific tool shape, the practical move is to replicate that shape in a different harness rather than invent a cleaner one the model has never seen at inference time.
Figure 3 - Copied, not redesigned: read_file and edit_file reproduce Claude Code’s own Read and str_replace schemas line for line. The rationale is training distribution, not taste: the model already saw this exact shape during fine-tuning.
Six backends, not one
The dict-based virtual file system was the whole story in mid-2026. It is now one option among several. The current package ships state.py (ephemeral, held in LangGraph’s own state), filesystem.py (real local disk), sandbox.py, langsmith.py, context_hub.py, and store.py: six single-purpose backends, plus a composite.py wrapper that mounts more than one of them at once under different path prefixes [6]. The same middleware stack that ran an in-memory dictionary during a research session can point at a real disk in a local CLI run, or at a LangSmith-hosted store in a managed deployment, with no change to the tool calls the agent makes.
Figure 4 - Six backends, one router: The same ls/read_file/write_file/edit_file tool calls work against an in-memory dictionary, a real disk, a sandbox, or a LangSmith-hosted store. composite.py mounts more than one under different path prefixes without the agent knowing which backend answered.
The tradeoff nobody tells you about until you read the source
Sub-agents can write to this file system concurrently, and the package’s reducer function, _file_data_reducer, handles it with deterministic last-write-wins overwrite: whichever write to a given path lands last in a batch simply replaces every earlier write to that path, with no content-level merge, no error, and nothing surfaced to the agent about the collision [7]. It is tempting to read that as an unfinished edge case. It is not. Nothing in the source tree suggests a merge step is coming. The design choice is cheap and simple, and the cost is silent data loss on a same-file race. The practical rule that follows: never have two sub-agents write the same path concurrently unless you are certain you only need one of the two writes to survive.
Figure 5 - Last write wins, silently: Two concurrent writes to the same path in one batch resolve deterministically to whichever lands last. There is no merge, no error, and no signal back to either sub-agent that its write disappeared.
The rule the harness actually enforces
An engineer at Harmonic, describing why the company moved its Scout product off a bespoke multi-node pipeline and onto deepagents, stated the underlying contract plainly: “anything that the harness kind of pulls out of the messages list, it has to make available to the model through tools” [8]. Restated as a hard boundary: the model only ever sees the messages list. Anything the harness offloads out of that list must be reachable through a discoverable pointer, a file path, a tool call, a status check, or it is invisible to the model, full stop. Pillar 2’s virtual file system is one concrete instance of that rule, not a separate feature.
Harmonic’s own first attempt at exposing search results broke this rule: a “render this data” tool returned a bare success signal while the front end silently rendered a result list the model never saw, and the model could not answer a user’s follow-up question about why a specific company appeared on screen. The fix ran in two steps: a tool that returns an identifier plus separate inspection tools so the model can pull status and fetch results on demand, and, for result sets too large even for that, a shared virtual file system that the main agent, a parallel search sub-agent, and the front end all read and write concurrently, streaming results in while the agent inspects the same files to answer follow-up questions [8]. Harmonic reports four times the retention from week one to week four since making that switch, a self-reported figure with no cohort definition or methodology given, so treat it as Harmonic’s own account rather than an audited result [8].
KEY INSIGHT: “If you find yourself saying, ‘trust that this is being rendered, believe me, don’t include this in your response,’ that’s a sign something is invisible to the model” [8]. That single sentence is a working diagnostic for any agent-plus-UI design: if you have to tell the model to trust a result it cannot inspect, the harness contract is already broken.
Pillar 3: sub-agents that forget on purpose
Sub-agents solve two separate problems: context pollution, where a long subtask’s accumulated tool calls degrade the main agent’s own focus, and specialization, where a subtask genuinely benefits from a different system prompt or a restricted tool set.
The mechanism for both is a deliberate history wipe. When the main agent calls the task tool, the sub-agent inherits the shared virtual file system from the parent state, so it can read and write files the parent already wrote, but its message history starts clean: a single task description, nothing else. When the sub-agent finishes its own tool-calling loop, only the content of its final message returns to the parent. Every intermediate tool call, partial result, and stray piece of reasoning stays inside the sub-agent and is discarded. That is why sub-agent prompts have to instruct the sub-agent explicitly to pack everything relevant into its own last response. There is no second chance to ask a follow-up.
Figure 6 - The sub-agent context wipe: The sub-agent shares the file system with its parent but starts with a blank message history and returns exactly one message back. Everything else it did along the way stays quarantined inside it.
Sub-agents can also run concurrently, which is exactly the scenario that triggers Pillar 2’s last-write-wins reducer. A parallel search sub-agent writing ranked results to a shared file, while the main agent and a front end both read from the same path, is the coordination-bus pattern in practice: a shared virtual file system standing in for a message-passing broker, with a third, non-agent reader (the UI layer) added to the usual parent-and-sub-agent pair [8].
Pillar 4: the prompt lives in the tool descriptions
Deep agents run long system prompts, hundreds to thousands of lines, but the counterintuitive part is where that length actually sits. The base prompt string in deepagents is short. The detail lives in the write_todos docstring covered above, in the file-tool descriptions, and in the task tool’s own multi-paragraph description covering when to spawn a sub-agent, how to invoke it, and what to trust about its return value. A short base prompt with rich, individually-scoped tool descriptions is not under-engineered; the descriptions are where the behavioral guidance actually lives.
The clearest production instance of this pattern currently shipping is a browser-automation integration that puts the entire agent instruction set inside a single tool contract, in under 120 words.
Figure 7 - Where the length actually lives: The base system prompt is short. Nearly all of the harness’s real behavioral guidance sits inside individually-scoped tool descriptions instead, led by the write_todos docstring covered in Pillar 1.
The tool-contract lesson: three tools, two schemas, one missing oneOf
Browserbase’s Stagehand v4 exposes browser control to any MCP-speaking agent host through exactly three tools, defined once and shared verbatim across every host that integrates it [9]. The tools are run, snapshot, and screenshot, and the file that defines them, contract.ts, is worth reading closely, because it is a worked example of nearly everything Pillar 4 claims in the abstract.
snapshot captures the active page’s accessibility tree and hydrates bracketed element IDs. Every call replaces the prior ID map. run executes either JavaScript against a Playwright-shaped page facade or a batch of ID-referenced actions (click, hover, fill, type, press, select), requiring exactly one of code or actions. screenshot inspects the rendered page visually [10]. The canonical agent instructions are hard-coded in the same file so every host ships identical guidance: “You control one persistent browser through exactly three tools… Pass run exactly one of code or actions; every action uses ‘op’ and ‘id’, never ‘kind’ or ‘ref’. Snapshot IDs are valid only for the latest snapshot of the active page; snapshot again after navigation or stale IDs. Do not launch another browser” [10]. That is the entire tool-description-heavy prompt Pillar 4 describes, doing real work in a single paragraph.
Figure 8 - The three-tool facade, exactly: run, snapshot, and screenshot. No fourth tool. The instructions telling the model how to use all three live in the same short instruction block, shipped once and shared by every host that adopts the contract.
The file’s own header comment explains a second, more transferable lesson: the schema is written twice on purpose. Hand-written JSON Schema literals are the wire contract advertised to MCP clients, because “const-typed op discriminators and per-property descriptions do not survive zod-to-JSON-schema conversion, and .refine() emits nothing at all” [10]. Zod schemas at the bottom of the same file are the runtime validators that actually parse incoming calls and enforce the code-or-actions exclusivity. A dedicated contract test exists specifically to catch drift between the two halves whenever one changes without the other [10].
A related decision goes further still. A reference implementation would enforce “code XOR actions” with a top-level oneOf in the JSON Schema. This one deliberately omits it, because “AI-SDK-based MCP clients (Eve, Vercel AI SDK) reject tool input schemas with a top-level oneOf, failing every run call client-side” [10]. That rejection happens before the request ever reaches the server, so the exclusivity is stated in prose in the tool description instead and enforced only at runtime. That same comment names Vercel’s own agent product, Eve, directly, alongside the Vercel AI SDK, as one of three host integrations, the third being deepagents itself, sharing this exact contract file rather than each writing its own tool descriptions [10]. Eve and the deepagents ecosystem are not two vendors who happened to converge on a similar boundary. They share literal source code for how a browser tool talks to an agent.
Figure 9 - One contract file, three clients, no oneOf: The wire schema and the runtime validator are two separate, hand-maintained versions of the same rule, kept in sync by a dedicated test. The top-level oneOf a cleaner design would add is missing on purpose, because Eve and the Vercel AI SDK both reject it.
KEY INSIGHT: Do not assume your validation library’s schema export is what an MCP client actually receives. Stagehand’s own contract file carries two versions of the same schema on purpose, a hand-written wire contract for
tools/listand a Zod validator for runtime, specifically because the automatic conversion between them silently drops constraints a client needs to see.
Where this ships
Eight months past “alpha”
LangChain’s own June 2026 walkthrough of the v1 middleware refactor described it as an “upcoming alpha release” [11]. LangChain and LangGraph reached general availability on October 22, 2025 [12], eight months before that framing was recorded. By August 2026 the ecosystem sits well past the milestone. There is no live alpha-versus-GA question to hedge here.
A second version number sits right next to that one and should not be confused with it. deepagents itself, a separate package from LangChain core, defaults to ChatAnthropic(model_name="claude-sonnet-4-6") when no model is specified, but relying on that default has been deprecated since deepagents==0.5.3 and will be removed entirely in deepagents==1.0.0, the package’s own upcoming milestone [13]. The current release is deepagents==0.7.5, published August 6, 2026 [14]. “LangChain 1.0” and “deepagents 1.0” are two different products reaching two different milestones on two different clocks.
Two CLIs with almost the same name
The harness ships with two command-line tools that share a family name and almost nothing else. dcode (package deepagents-code, installed with curl -LsSf https://langch.in/dcode | bash) is a local, Claude-Code-style coding agent that runs on your own machine [1]. mda (package deepagents-cli) is “deployment tooling for Deep Agents: bundle, run, and ship agents to LangGraph Platform” [15], with mda init, mda dev, and mda deploy [16] as its own three commands. Conflating the two produces a materially wrong how-to: one is where you write and test an agent, the other is how you ship it.
Figure 10 - Two CLIs, two jobs: dcode runs a deep agent locally, Claude-Code-style. mda bundles and deploys that same harness to LangGraph Platform. The similar names are the only thing they share.
A production deployment, in public beta
LangChain’s own packaged answer to layer three, Managed Deep Agents, bundles the open-source harness with LangSmith deployments for the runtime, a Context Hub for context storage, integrated sandboxes, and Harbor for evals [17]. It reached public beta on August 7, 2026, upgraded from an earlier private beta [18], and requires a LangSmith Plus plan at $39 per seat per month or above; the free Developer tier does not include it [19]. Read the deployment story accordingly: this is where the ecosystem is heading, demonstrated with a working browser-automation example the same week it shipped [20], not an established pattern with years of production track record behind it.
Context Hub itself deserves a more precise claim than “a paid UI feature.” It ships as ContextHubBackend directly inside the open-source deepagents package, storing files in a LangSmith Hub agent repository addressed as owner/name or -/name, with typed AgentEntry, FileEntry, and SkillEntry schemas [21]. It is also documented as a managed UI on LangChain’s own blog [22]. Instructions and skills, in this design, are treated as data in a hub rather than code shipped with a deployment, which means a non-developer can change agent behavior without a redeploy, a stronger claim than “a UI layered on top of the harness.”
Two more production details close out the harness layer. LangGraph’s default recursion limit, the hard ceiling on how many graph steps a run can take before it terminates, is 25, defined as DEFAULT_RECURSION_LIMIT in langchain_core’s own configuration module [23][24]. Anything approaching a genuine multi-sub-agent research workload needs that raised well before it becomes useful. Sandbox support for isolated code execution also spans at least five partner packages, langchain-daytona, langchain-modal, langchain-quickjs, langchain-runloop, and langchain-vercel-sandbox [25], with two more, LangSmith and AWS Bedrock AgentCore, surfaced only through the dcode CLI’s own remote-sandbox list [1].
What the harness still leaves out
Everything above is what deepagents gives an agent’s mind: how it plans, remembers, delegates, and describes itself. None of it says how a human reaches the agent, where a credential lives, or what wakes the agent up on a Tuesday morning with no user present. Vercel’s own agent product, Eve, scaffolds those three concerns as literal project folders: channels for the I/O surface, connections for credentials and OAuth, and schedules for triggers including cron, alongside skills for on-demand context and tools for sandboxed execution [26]. Eve is open source and publicly available on GitHub under an Apache 2.0 license [26], though neither its repository nor its product page states a maturity tier as of this writing.
Only two of Eve’s five folders map onto anything in the four pillars: skills is Pillar 4’s tool-description surface under a different name, and tools is straightforward execution. channels, connections, and schedules have no counterpart anywhere in the architecture this article just built. That gap is the honest summary of what a deep agent is and is not: it is an architecture for how an agent thinks through a task, and a deployed agent is that architecture plus three concerns the architecture itself never mentions.
Figure 11 - Two folders map, three do not: Eve’s skills and tools folders line up with Pillar 4 and the execution surface. channels, connections, and schedules describe how an agent is reached, authenticated, and triggered, a set of concerns the four-pillar architecture never addresses on its own.
Conclusion
The four pillars are not a proposal. They are a released package, a documented default model, a named reducer function, and a tool contract three separate MCP clients ship against today. That changes what a team building its own agent should do with this material: pip install deepagents, read the actual write_todos docstring rather than write a shorter one from scratch, and decide up front which of the six file-system backends matches where the agent will actually run before the last-write-wins reducer surprises anyone with a same-file race in production.
The Stagehand facade contract is the sharpest piece of transferable engineering in the whole architecture, and it generalizes past browser automation. Any team shipping a tool schema to more than one MCP client should expect the same failure mode Stagehand’s own comments name explicitly: a validation library’s automatic JSON Schema export drops constraints a client needs, and at least one client in the wild rejects a JSON Schema feature a different client tolerates fine. Carrying the contract twice, with a test that catches drift, costs a file and a CI step. Discovering the mismatch in production costs a debugging session with no error message pointing at the cause.
None of this requires betting on a single vendor’s roadmap. The harness is open source, the schemas are published, and the production layer sitting on top of it, Managed Deep Agents included, is explicitly a public beta rather than a settled standard. A team building a domain-specific agent today can adopt the four pillars, the file-tool schemas, and the sub-agent isolation rule without touching any of that beta surface at all, and add the production tooling later, on its own timeline, once the beta label comes off.
References
[1] LangChain AI, “libs/code/README.md,” deepagents repository, accessed Aug. 11, 2026. https://github.com/langchain-ai/deepagents/blob/main/libs/code/README.md
[2] LangChain AI, “deepagents: The batteries-included agent harness,” GitHub repository, accessed Aug. 11, 2026. https://github.com/langchain-ai/deepagents
[3] LangChain, “What are Deep Agents?,” YouTube, Jun. 18, 2026. https://www.youtube.com/watch?v=433SmtTc0TA
[4] LangChain, “Managed Deep Agents explained in 20 minutes,” YouTube, Aug. 7, 2026. https://www.youtube.com/watch?v=yi-XZnAVFJg
[5] LangChain, “Implementing DeepAgents: A Technical Walkthrough,” YouTube, Jun. 18, 2026. https://www.youtube.com/watch?v=TTMYJAw5tiA
[6] LangChain AI, “backends/,” deepagents repository, accessed Aug. 11, 2026. https://github.com/langchain-ai/deepagents/tree/main/libs/deepagents/deepagents/backends
[7] LangChain AI, “middleware/filesystem.py,” deepagents repository, accessed Aug. 11, 2026. https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/middleware/filesystem.py
[8] LangChain, “How Harmonic 4x’d User Retention by Building on Deep Agents,” YouTube, Aug. 7, 2026. https://www.youtube.com/watch?v=pGdZBK___jM
[9] Browserbase, “stagehand: The SDK For Browser Agents,” GitHub repository, accessed Aug. 11, 2026. https://github.com/browserbase/stagehand
[10] Browserbase, “contract.ts,” stagehand repository, accessed Aug. 11, 2026. https://github.com/browserbase/stagehand/blob/main/packages/integrations/core/src/facade/contract.ts
[11] LangChain, “Rewriting Deep Agents on top of LangChain 1.0,” YouTube, Jun. 18, 2026. https://www.youtube.com/watch?v=AZ6257Ya_70
[12] LangChain, “LangChain and LangGraph Agent Frameworks Reach v1.0 Milestones,” LangChain Blog, Oct. 22, 2025. https://www.langchain.com/blog/langchain-langgraph-1dot0
[13] LangChain AI, “graph.py,” deepagents repository (default-model deprecation warning), accessed Aug. 11, 2026. https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/graph.py
[14] Python Package Index, “deepagents 0.7.5,” accessed Aug. 11, 2026. https://pypi.org/project/deepagents/
[15] Python Package Index, “deepagents-cli,” accessed Aug. 11, 2026. https://pypi.org/project/deepagents-cli/
[16] Browserbase, “packages/integrations/deepagents/README.md,” stagehand repository, accessed Aug. 11, 2026. https://github.com/browserbase/stagehand/blob/main/packages/integrations/deepagents/README.md
[17] LangChain, “Managed Deep Agents: the fastest way to ship a production deep agent,” LangChain Blog, Aug. 7, 2026. https://www.langchain.com/blog/introducing-managed-deep-agents
[18] LangChain, “Managed Deep Agents is now in public beta,” LangChain Blog, Aug. 7, 2026. https://www.langchain.com/blog/managed-deep-agents-is-now-in-public-beta
[19] LangChain, “LangSmith Plans and Pricing,” LangChain, accessed Aug. 11, 2026. https://www.langchain.com/pricing
[20] LangChain, “Create an agent that can browse the web with Managed Deep Agents and Browserbase’s Stagehand,” YouTube, Aug. 10, 2026. https://www.youtube.com/watch?v=O0hkpChFBkM
[21] LangChain AI, “context_hub.py,” deepagents repository, accessed Aug. 11, 2026. https://github.com/langchain-ai/deepagents/blob/main/libs/deepagents/deepagents/backends/context_hub.py
[22] LangChain, “Introducing LangSmith Context Hub,” LangChain Blog, May 13, 2026. https://www.langchain.com/blog/introducing-context-hub
[23] LangChain AI, “config.py,” langchain repository, accessed Aug. 11, 2026. https://github.com/langchain-ai/langchain/blob/master/libs/core/langchain_core/runnables/config.py
[24] LangChain, “GRAPH_RECURSION_LIMIT,” Docs by LangChain, accessed Aug. 11, 2026. https://docs.langchain.com/oss/python/langgraph/errors/GRAPH_RECURSION_LIMIT
[25] LangChain AI, “libs/partners/,” deepagents repository, accessed Aug. 11, 2026. https://github.com/langchain-ai/deepagents/tree/main/libs/partners
[26] Vercel, “eve: The Open Framework for Building Agents,” GitHub repository, accessed Aug. 11, 2026. https://github.com/vercel/eve
Building production AI, or modernizing a legacy system?
That is the kind of work we do at Dotzlaw Consulting. Book a free 20-minute intro call and tell us what you are trying to build, or what is slowing you down.