Agent Harness Anatomy #16: Deep Agents — the harness that is a middleware stack, not a loop

by David P. S. Marques

Series: Agent Harness Anatomy — top-down dissections of real agent harnesses, grounded in verifiable source code. Every behavioral claim below carries a footnote to a pinned GitHub permalink; the full evidence lives in the endnotes.

Version block

A note on the pin, and on what kind of object this is. Every previous teardown in this series dissected a program: a loop you could point at. Deep Agents is a library, and its defining decision is that it does not contain the loop at all. create_deep_agent() assembles configuration — middleware, backends, subagents, a prompt — and hands it to LangChain's create_agent(), which builds the loop on LangGraph. So this teardown reads two things at once: the code in this repo, and the boundary between that code and its two dependencies. And because the loop is the one mechanism a reader cannot understand from this repo alone, it also reads the dependency source itself — LangChain and LangGraph, each pinned separately (langchain 1.4.5 and langgraph 1.2.15, the versions this pin resolves against; see the endnotes preamble). Where a mechanism belongs to LangChain or LangGraph, the article says so and the endnote names the repo it points into; nothing below attributes dependency code to this repo.

The repo is a release-please monorepo in which each package versions independently. The pin is the core package's release: libs/deepagents/pyproject.toml declares version 0.7.25, and the tag names exactly that package. The sibling packages sit at the same commit and are covered as interfaces, not as the pinned artifact.

Deep Agents architecture

Explore the interactive architecture diagram 16 nodes, 19 edges — pan, zoom, and follow every subsystem link

The mental model

Hold one sentence and the rest follows: Deep Agents is an ordered stack of middleware around someone else's loop, plus a pluggable backend that decides where files and shell commands live.

The project's own architecture document draws the three layers plainly: LangGraph is the runtime (state, checkpoints, streaming, interrupts); LangChain's create_agent() is the agent abstraction that builds the loop; Deep Agents "is an opinionated harness on top of create_agent(). It does not introduce a new runtime."1 Reading create_deep_agent() bears this out completely — it is 700 lines of assembly that end in a create_agent(...) call.2 There is no turn loop anywhere in the package to summarize, because there is no turn loop in the package.

What the package contributes instead is a default stack. In order: a filesystem middleware that provides the file and shell tools; a subagent middleware that provides delegation; a summarization middleware that manages context; a repair middleware for interrupted runs; optionally skills, memory, and human-in-the-loop middleware; and per-model "harness profiles" that adjust the stack for a specific provider's model. Every entry is a LangChain AgentMiddleware — the hook machinery (before_agent, wrap_model_call, wrap_tool_call) is LangChain's — but the middleware classes themselves, and the order they're assembled in, are this repo's design.3

The second load-bearing decision is the backend. One protocol object decides where the agent's files live (in graph state, in a LangGraph store, on real disk), whether shell execution exists at all, and where evicted context is offloaded. Swap the backend and the same agent goes from an ephemeral in-memory workspace to a real directory to a remote sandbox — the security story of the whole system is, in the end, a statement about which backend the application wired in (T3).

And the third: subagents by state subtraction. A delegated agent is a fresh graph whose initial state is the parent's state minus a curated set of keys, with the message history replaced by a single task description. Isolation is not a sandbox or a separate process; it is a filter applied to a dictionary (T5).

How the stack is put together

Assembly. create_deep_agent() (in graph.py) resolves the model — a "provider:model" string goes through LangChain's init_chat_model, with provider-profile adjustments4 — resolves the harness profile for that model, takes the caller's backend or defaults to StateBackend(), processes subagent specs, builds the middleware stack, composes the system prompt (caller text plus the profile's suffix; the authored base prompt earlier versions shipped is now deprecated legacy), and returns LangChain's graph with two pieces of configuration stamped on: a recursion limit of 9,999 and run metadata tagging the integration as deepagents for tracing.5

The stack, concretely. The main-agent stack is built in one list and a series of appends:6

  1. FilesystemMiddleware — tools, permissions, eviction
  2. SubAgentMiddleware — the task tool (present whenever subagents exist; a default general-purpose subagent is auto-added, so in practice always)
  3. Summarization middleware (Deep Agents' own, §Memory)
  4. PatchToolCallsMiddleware — dangling-call repair
  5. Harness-profile extra middleware for the model, then SkillsMiddleware if skills= was passed
  6. Prompt-caching middleware (LangChain's Anthropic caching middleware, plus Bedrock/Fireworks variants when those packages are installed)7
  7. MemoryMiddleware if memory= was passed, then LangChain's HumanInTheLoopMiddleware if any interrupt configuration exists, then UnsupportedContentMiddleware

Customization is stack surgery, by name. A caller-supplied middleware whose .name matches a default replaces it in place, preserving order; a new one is inserted after the core scaffolding, ahead of the profile/memory tail.8 Harness profiles can go further — adding middleware, overriding tool descriptions, appending prompt text, and excluding tools or middleware — with two guardrails. First, FilesystemMiddleware and SubAgentMiddleware are protected scaffolding: a profile that tries to exclude either fails construction with a ValueError, because removing them "silently breaks core features" — the filesystem middleware also carries the permission enforcement, which the code names a security guarantee.9 Second, every exclusion entry must match something in the assembled stacks, or construction fails — a typo'd exclusion is an error, not a no-op. Tool exclusion runs dead last, in a dedicated middleware appended after all caller middleware, so an excluded tool cannot be restored by a caller's request wrapper.10

Subagents get a smaller stack — filesystem, summarization, patch, profile extras, skills, prompt caching; memory only for forks — and, notably, no SubAgentMiddleware: a subagent does not receive a task tool of its own (T5).11

Package map

The core package concentrates in three directories, exactly as the project's architecture doc says.

Path Role
libs/deepagents/deepagents/graph.py create_deep_agent() — assembly only; DeepAgentState
libs/deepagents/deepagents/middleware/ The stack: filesystem, subagents, summarization, skills, memory, patch-tool-calls, plus helpers (eviction, blob offload, prompt caching, tool exclusion, fs-interrupt glue) and opt-ins (rubric, async subagents)
libs/deepagents/deepagents/backends/ BackendProtocol + State / Store / Filesystem / LocalShell / Composite / ContextHub backends and the BaseSandbox base class
libs/deepagents/deepagents/profiles/ Per-model harness profiles (Anthropic Sonnet/Opus/Haiku, OpenAI Codex, NVIDIA Nemotron built in) and provider profiles; public registration functions
libs/code/ Deep Agents Code (dcode) — the terminal coding-agent product built on the SDK
libs/acp/ deepagents-acp — an Agent Client Protocol server
libs/talon/ Experimental host for long-running agents (messaging channels, cron)
libs/partners/ Sandbox backend packages: Daytona, Modal, Runloop, Vercel, QuickJS

The core loop

There is no loop in this repo to write up — the loop is LangChain's create_agent graph executing on LangGraph, and this repo's docs describe it in one sentence: the runtime drives turns in which the model receives the history, the prompt, and the tools, and the loop continues until the model produces a final response.1 But a teardown that stopped there would leave the harness's most important behavior undescribed, so this section reads the loop where it actually lives: in the two dependencies, pinned at langchain 1.4.5 and langgraph 1.2.15 (notes 50+). What this repo contributes around that loop follows after.

The graph LangChain builds. create_agent is a factory that compiles a LangGraph StateGraph with two working nodes. The model node builds a ModelRequest from state, passes it through the chained wrap_model_call handlers — which is where Deep Agents' request-time middleware (capability filtering, summarization's history reconstruction) actually runs — and invokes the model with the request's tools bound. The tools node is LangGraph's prebuilt ToolNode, constructed with the caller and middleware tools and the chained wrap_tool_call wrappers.50 Every middleware hook of the state kind — before_agent, before_model, after_model, after_agent — becomes a graph node of its own, chained around the two: the run enters through the first before_agent node, each turn enters through the first before_model node and leaves through the first after_model node, and the run exits through the last after_agent node.52 The loop is closed by two routing functions. After the model: a response with no tool calls routes to END — the code comments this "the classic exit condition for an agent loop" — while pending tool calls fan out as one Send per call into the tools node, so a batch of independent calls becomes parallel tasks. After the tools: unless every executed tool said return_direct or a structured-output tool ran, control returns to the loop entry and the model sees the results.51

One question this series asks every harness — what runs beneath the stack you can see? — has a clean answer here: create_agent adds no middleware of its own. The stack Deep Agents assembles is the whole stack; the factory's only additions are inside its nodes (the model node first repairs tool calls whose arguments are invalid JSON, a small per-call pass; structured-output parsing wraps the response) and in the config it stamps — which is where the step ceiling comes from.55

The runtime underneath: super-steps and checkpoints. LangGraph executes the graph in Pregel super-steps. Each iteration prepares the tasks whose input channels the previous step updated, runs them concurrently, then merges their writes into the state channels through each channel's reducer — and saves a checkpoint. A checkpoint is written when the run's input is applied, and again after every super-step: the model call, the tool batch, and each middleware hook node each land in their own checkpoint when a checkpointer is configured. Persistence timing is a per-run durability setting (asynchronous by default; a synchronous mode waits for each checkpoint write before proceeding).53 Two consequences are worth holding onto. First, "resume" in this stack is not a feature layered on top — it is the runtime's normal state after any step, which is why interrupted runs and HITL pauses (below) are cheap here. Second, with no checkpointer configured — the default assembly — none of this is written anywhere: the same loop runs purely in memory, and the checkpoints exist only as the loop's internal bookkeeping.

A step ceiling, set very high — counted in super-steps. The one run budget in the assembly is recursion_limit: 9_999, and the dependency read shows it has two authors: LangChain's factory stamps 9_999 onto every graph it compiles, and Deep Agents' .with_config stamps the same value again while replacing the tracing metadata with its own.55 Nothing in either package counts turns, tokens, or cost as a stop condition. What the number counts is super-steps: at run start the runtime sets a stop line at the current checkpoint step plus the limit, and each super-step consumes one. A single conversational turn consumes several — the model node is one step, a parallel batch of tool calls shares one step, each before_model / after_model hook node on the path is a step of its own — so 9,999 steps buys on the order of thousands of model calls. Enforcement is equally specific: when the step count passes the stop line, the loop stops scheduling work, and the driver raises GraphRecursionError — but only if no stop condition was reached; a run that routes to END on its final allowed step completes normally. A resumed thread keeps counting from its checkpoint's step rather than restarting at zero.54 Read precisely, then: 9,999 is a ceiling on graph execution measured in runtime steps, best understood as a guardrail against pathological graphs rather than a budget — for scale, the sibling Talon host defaults its per-invocation limit to 500.12

A state shape tuned for long threads. DeepAgentState moves the messages channel onto a LangGraph DeltaChannel with a locally written reducer (adapted, per its header comment, from a LangGraph PR), so checkpoint growth across a long thread is linear rather than quadratic; the files channel gets the same treatment.13 The channel type is LangGraph's; the reducer and the decision to use it are this repo's.

Repair of interrupted runs. When a run is cancelled or interrupted mid-tool-call, the history it leaves behind contains an assistant message whose tool calls have no results — a shape model APIs reject. PatchToolCallsMiddleware runs before the agent starts and repairs exactly that: each dangling call gets a synthetic error result ("did not complete - no result was recorded. It may have been cancelled or interrupted."), and the history is rewritten in one pass.14 Abandonment — a run simply never resumed — is otherwise the checkpointer's concern: with a LangGraph checkpointer configured, the thread's state waits; without one, nothing persists to resume (T4).

One turn, end to end

The default assembly — create_deep_agent(model=..., checkpointer=...), default StateBackend, no skills or memory configured. The task: "Survey the Markdown files in /docs and write a combined summary to /summary.md."

  1. Invoke. The caller invokes the graph with the user's message and a thread_id. LangGraph loads the thread's checkpoint (empty on a fresh thread), applies the input, and writes an input checkpoint.53 The graph's entry path runs the before_agent hook nodes first:52 PatchToolCallsMiddleware scans the history for dangling tool calls — none on a fresh thread — and returns without changes. (Skills and memory middleware are absent entirely: they are only installed when the caller passes skills= / memory=.)
  2. The first request is assembled by the stack. The wrap_model_call chain runs in stack order. The summarization middleware reconstructs the effective history (no summarization events exist yet) and prices the request — far below its trigger. The filesystem middleware filters the tool list against the backend's capabilities: StateBackend cannot execute commands, so the execute tool is dropped from this request and the shell guidance goes with it.15 The subagent middleware appends its guidance, and the task tool's description lists the one available agent type: general-purpose.
  3. The model delegates. Its first response carries two task calls in a single message — one for /docs/api, one for /docs/guides. The routing edge after the model emits one Send per pending call,51 so the two calls execute as parallel tasks inside a single super-step of the tools node — the parallel batching the tool description instructs the model to use for independent work.1658
  4. Inside a subagent. Each invocation builds the subagent's starting state by subtraction: the parent's state minus the excluded keys (messages, todos, structured response, skill state, private middleware fields), with messages replaced by a single human message — the task text.17 The subagent runs its own smaller stack (no task tool of its own) and works the problem with ls and read_file. It never sees the parent's conversation, the other subagent, or the user's original wording beyond what the task text carried.
  5. One message comes back. Each subagent's final assistant message becomes a single ToolMessage on the parent, delivered as a state update; any other state the subagent produced merges back under the same exclusion rules, with unchanged values dropped so parallel calls can't conflict.18 The parent now holds two survey reports — and none of the subagents' intermediate reads.
  6. The parent writes. The model calls write_file for /summary.md. The filesystem middleware checks its permission rules (none configured → allow) and the StateBackend writes the content into the files state channel through LangGraph's internal read/send mechanism;19 when the super-step ends, the writes merge into the channels and a checkpoint recording them is saved.53
  7. A verification read, and an eviction. Checking one claim, the model reads a large generated index file under /docs itself. The result crosses the eviction threshold (20,000 tokens by default), so the filesystem middleware's wrap_tool_call writes the full text to /large_tool_results/ in the backend and the model receives a truncated preview with the path — retrievable with read_file, but no longer riding in every subsequent request.20 At the next model call the summarization middleware prices the history again: still below its trigger, so no summarization event is recorded.
  8. Finish. The model replies with the summary and no tool calls; the routing edge sends a tool-call-free response to END,51 the after_agent hook nodes run on the exit path,52 and the final super-step's checkpoint — messages and files channels together — is the thread's resting state.53 /summary.md now exists inside that thread's state: a second thread, or the same process tomorrow without the checkpointer, starts with an empty filesystem. That ephemerality is the default assembly's honest nature, and §Memory returns to it.

One turn through the dependency loop

Play the 8-step trace One turn through Deep Agents — the input checkpoint, the armed wrappers, two delegations across the subtraction boundary, and the exit with no tool calls

Tools

The built-in surface comes from two middleware. FilesystemMiddleware constructs eight tools — ls, read_file, write_file, edit_file, delete, glob, grep, execute — and SubAgentMiddleware adds task.21 A caller can narrow the filesystem set with an allowlist at construction (with read_file mandatory); allowlisted-out tools are never constructed, not merely hidden. The execute tool is doubly conditional: it is constructed, but each model request filters it out unless the resolved backend implements the execution protocol — and if a call somehow reaches it on a non-execution backend, it returns a descriptive error message rather than raising.15

Caller tools are added verbatim, and harness profiles can hide any tool by name through excluded_tools, enforced per-request by the exclusion middleware that runs last in the stack.10 There is no tool-search or deferred-loading mechanism in the core package: visibility is decided at construction and at request-assembly time, never retrieved at run time. Deep Agents and dsh arrive at the same answer — the surface is an editorial decision — by different machinery: composition YAML there, middleware construction here.

The planning tool that isn't there. The description most associated with this project — a planning tool, a filesystem, and sub-agents, the trio from its original write-ups — is one-third out of date at this pin. A repository-wide search finds write_todos in exactly one place in the core package: the OpenAI Codex harness profile, which adds LangChain's TodoListMiddleware because that model's profile prompt tells it to reconcile TODO items.22 The current README feature list and the package description don't claim a planning tool, and the default stack doesn't contain one. Planning, where it exists, is a per-model profile decision — which is itself a tidy illustration of what harness profiles are for. It is also the kind of drift that propagates: anyone describing the harness from its reputation rather than its stack will describe a create_deep_agent() call that this code does not build.

MCP — by adapter, not by client. The core package contains no MCP client (the string appears once, in a comment about generated tool names in the skills module). The README's "any MCP server" resolves through the ecosystem: MCP tools are produced by the separate langchain-mcp-adapters package and passed in as ordinary tools=. The sibling apps do their own loading — Talon reads ~/.deepagents/.mcp.json, the Code app has its own extension system — but the harness itself is MCP-agnostic.23

Approvals and the sandbox

Permissions fence the file tools. A caller can pass permissions= — a list of FilesystemPermission rules, each pairing operations (read/write) with glob path patterns and a mode: allow, deny, or interrupt. Rules evaluate in declaration order, first match wins, default allow.24 Enforcement lives inside each built-in tool rather than in a wrapper, and it is thorough in two ways worth crediting: with a real-filesystem backend, a rule is matched against both the requested path and its symlink-resolved target, so a link can't walk a call around a deny; and the bulk tools' results are filtered, so ls, glob, and grep never leak the existence of denied paths back to the model.25

Interrupts are generated, then delegated. An interrupt-mode rule doesn't pause anything by itself. At assembly time, glue code converts the rules into an interrupt_on configuration for LangChain's HumanInTheLoopMiddleware, with a per-tool predicate that understands each tool's path scope — exact-path tools fire on a match; the bulk tools fire whenever their search subtree could intersect an interrupt rule, and a pathless bulk call fires unconditionally, because it can touch anything.26 The caller's own interrupt_on= entries merge with (and win over) the generated ones.27 The middleware class, the pause/resume mechanics, and the approve/edit/reject decision vocabulary are LangChain's and LangGraph's — Deep Agents' contribution is the wiring that lets a filesystem policy produce them. In the dependency source, the flow runs through the middleware's after_model hook: it scans the model's pending tool calls against interrupt_on, assembles one review request, and calls LangGraph's interrupt(), which raises a resumable exception that pauses the graph between the model and tools nodes — with the post-model checkpoint already written, so the pending calls wait in durable state.57 Resuming is a fresh invocation carrying the decisions; the paused node re-executes from its start and interrupt() returns the decisions in place of raising, matched by order.56 A checkpointer is required for any of it to work, and the requirement is documented on the fields that need it.

A filesystem permission interrupt

The sandbox is a backend choice, and the default has no shell. Execution capability is a protocol refinement: SandboxBackendProtocol extends the file protocol with execute. The core package ships no sandbox implementation. Its local execution backend, LocalShellBackend, runs commands with subprocess.run(..., shell=True) directly on the host, and its class docstring is an extended, explicit warning — no sandboxing, no process isolation, no resource limits, with human-in-the-loop named as the recommended safeguard.28 Real isolation lives one layer out: the abstract BaseSandbox in this repo is implemented by the partner packages (Daytona, Modal, Runloop, Vercel) and by a LangSmith-hosted sandbox backend.29 The path-jail on the plain FilesystemBackend is similarly honest: virtual_mode blocks traversal outside the root and the docs state it "does not provide sandboxing or process isolation."30

And the permission system's stated limit. The file-tool rules stop at the shell. Combining permissions= with an execution-capable backend raises NotImplementedError at construction: "Tool-level permissions for the execute tool are not implemented."31 So in an assembly with shell access, the most powerful tool in the surface is governed by exactly two things — the choice of backend, and a HITL interrupt on execute if the caller configured one. The refusal to combine the two silently is the creditable behavior; the gap it names is structural.

Two ways to run a shell command

What leaves the machine

Very little, by default. langsmith is a hard dependency, and assembly stamps each run's metadata (ls_integration: deepagents, plus the package version) so that if LangSmith tracing is enabled — an environment-level, dependency-side switch — runs and subagent runs attribute correctly.32 A search of the core package finds no other telemetry or analytics calls. Hosted backends (ContextHubBackend, the LangSmith sandbox, the partner sandboxes) move file contents and commands to their services, but only in assemblies a caller explicitly wires that way.

Memory and sessions

Sessions are LangGraph's; this repo tunes the channels. Conversation state, checkpoints, and streaming belong to the runtime; create_deep_agent passes checkpointer and store straight through to create_agent.2 The repo's own state contributions are the two DeltaChannel wirings (messages and files) that keep checkpoint growth linear on long threads.13

Summarization is an event, not a rewrite. The default stack's summarization middleware is Deep Agents' own class, and its relationship to LangChain's is precise: it composes LangChain's SummarizationMiddleware as an internal helper for partitioning and summary generation — reusing LangChain's summary prompt with one addendum spliced in — and builds the file-aware behavior around it.33 When the trigger fires, the middleware does not delete anything. It first appends the evicted span, as markdown, to /conversation_history/{session_id}.md on the configured backend; it generates the summary; and it records a private _summarization_event — cutoff index, summary message, file path — in state.34 Every later model call reconstructs the effective history by applying the recorded events to the intact message log. The summary message carries the offload path, so the agent can read_file its own evicted history if a detail matters. The factory that builds it documents the contrast itself: LangChain's middleware rewrites state and drops evicted messages with no recovery path; this one preserves the raw log for replay, evals, and sharing with the on-demand compaction tool.35

Defaults are model-aware: if the model's profile exposes max_input_tokens, summarization triggers at 85% of the window and keeps the most recent 10%; otherwise it triggers at 170,000 tokens and keeps 6 messages.36 Two cheaper mechanisms run ahead of it. Large tool-call arguments in older messages (the classic case: a huge write_file body) are truncated at a lower threshold, which often reclaims enough to skip summarizing entirely. And if a provider rejects a request as over-budget anyway, the middleware summarizes and retries once smaller; a request that cannot be reduced raises a ContextOverflowError rather than looping. A model-callable compact_conversation tool exists for on-demand compaction, but it is not in the default stack — callers compose it themselves.37

Summarization: compaction as an event

Large results are evicted to the backend, not truncated away. Independently of summarization, the filesystem middleware intercepts every tool result on its way into state: anything over 20,000 tokens (the default tool_token_limit_before_evict) is written to /large_tool_results/ and replaced by a preview plus pointer. Oversized human messages get the same treatment at 50,000 tokens, into /conversation_history/.20 A small guard rides along: two file mutations to the same path inside one model response are rejected, since parallel writes to one path have no coherent order.38

Long-term memory is files, loaded into the prompt. When memory= is passed, MemoryMiddleware loads the listed AGENTS.md-style files from the backend once, at the start of a run, and injects their contents into the system prompt inside an <agent_memory> block on every model call.39 There is no separate memory database and no dedicated write path — the files live in the same backend as everything else, and the agent updates them with the ordinary write_file / edit_file tools. Whether those updates outlive the thread is, again, the backend's decision.

Persistence, stated plainly. The default assembly persists nothing across threads: files live in graph state (thread-scoped by construction), and no checkpointer is configured unless the caller passes one.40 Cross-session recall is available — a LangGraph store behind StoreBackend, an on-disk FilesystemBackend, prefix routing via CompositeBackend — but every durable variant is caller-supplied plumbing. "Persistent memory" in the feature list describes the ceiling of the assembly, not its floor. For a library, that is a coherent place to draw the line; it is also the single most likely place for a reader of the feature list to overestimate what create_deep_agent() alone gives them.

Extensions

Middleware is the extension API. Everything in T2 applies to authors: write a LangChain AgentMiddleware, pass it in middleware=, and it replaces a same-named default in place or slots in after the core scaffolding. Middleware can add tools, state fields (with PrivateStateAttr keeping them out of subagent state), prompt fragments, and request/response rewriting — the same machinery the built-ins use, with no second-class plugin tier.8

Harness profiles tune per model. A HarnessProfile bundles prompt suffixes, tool-description overrides, extra middleware, and tool/middleware exclusions for a model family; profiles for several Anthropic models, OpenAI's Codex models, and NVIDIA's Nemotron ship in the repo, and registration functions for harness and provider profiles are public API.41 The Codex profile is the one carrying write_todos (T2) — a behavior that makes sense for one model's prompting style, delivered as profile data rather than a harness-wide default.

Skills follow the Agent Skills pattern. With skills= passed, SkillsMiddleware loads skill directories from backend sources: each is a SKILL.md whose YAML frontmatter (name, description, optional allowed tools) is parsed into metadata that goes into the system prompt, while the body is read on demand with read_file — progressive disclosure. Reading a skill can disclose skill-scoped tools for the rest of the run, and a caller can force the issue with pinned_skills in state, which appends named skills' full bodies to the conversation before the next model call.42

Subagents come in three forms. Declarative specs (name, description, and optional model, tools, middleware, prompt, permissions, skills, response format) are compiled through the same create_agent path with the smaller stack. A CompiledSubAgent hands the middleware any pre-built LangGraph runnable, used as-is. An AsyncSubAgent points at an agent deployed on LangGraph Platform and is driven through start/check/update/cancel/list tools rather than the blocking task call — delegation to a remote, long-running agent.43 One more opt-in deserves a line: RubricMiddleware runs a separate grader sub-agent against the transcript and resumes the loop until the grader reports the rubric satisfied or an iteration cap is hit — self-evaluation as middleware, not in the default stack.44

A task delegation into a subagent

Backends are the deepest extension point. Implementing BackendProtocol (files) or SandboxBackendProtocol (files + execute) reroutes the agent's entire material world — every tool, offload path, skill source, and memory file resolves through it — without touching the stack. The partner packages are exactly this: five small adapters over one protocol.29

Interfaces

Observations

The reuse rule, and its one deliberate exception. Almost everything LangChain provides, Deep Agents uses as-is: the loop, the HITL middleware, the prompt-caching middleware, the todo middleware (in a profile). Exactly one LangChain component is re-implemented instead — summarization — and the factory's docstring enumerates why: backend offload of evicted history, argument truncation, overflow recovery, and a non-mutating event model where LangChain's version rewrites state and discards what it evicts.35 The exception clarifies the rule: the project's authors re-implement when the behavior they need is about files, because files are the thing LangChain's abstractions don't know about and theirs do.

Isolation by subtraction is elegant, and its seams show in the bookkeeping. The subagent state filter is one set of excluded keys; around it sits a small apparatus of correctness rules — private-field stripping, unchanged-value dropping so parallel calls don't collide on reducer-less keys, fork-specific exclusions, a preamble teaching the fork not to re-delegate, a refusal returned at call time. None of it is incidental; each rule reads like the scar of a specific failure mode. The design's simplicity is real, and so is the care required to keep shared mutable state honest when "isolation" means "the same dictionary, filtered."

The task tool validates like a product, not a library. Its schema rejects unknown argument keys with an error naming the key — because, the code explains, models were observed putting the real instructions under an invented key such as prompt, having them silently ignored, and reporting success on an under-specified run.48 A validation error goes back to the model as a tool error it can correct. Small, opinionated, and exactly the kind of detail a harness accumulates from watching models fail.

Fork mode is the honest way to ship an experiment. Conversation-inheriting subagents cut against the feature the README advertises (isolated context), and the code treats them accordingly: an experimental flag in the spec, a beta warning at construction, inheritance rules spelled out in the type's docstring, skills forbidden under fork because they would diverge from the parent's, and recursion refused at runtime rather than by hiding the tool — the refusal text tells the fork to complete the task itself.49

Tradeoffs

Building the harness as a stack on a borrowed loop buys leverage and gives up custody. The leverage is visible everywhere in this teardown: LangGraph's checkpointing, interrupts, and streaming; LangChain's middleware ecosystem, model coverage, and HITL semantics — all inherited, none re-implemented, and the package's own code stays focused on the pieces that are actually its opinion (filesystem, delegation, context, profiles). The test suite being twice the size of the source suggests the team spends the saved effort on behavior rather than plumbing.

The custody cost is that the harness's most important behaviors are not in the harness. Turn semantics, tool-call execution, interrupt mechanics, and the middleware hook contract are all dependency decisions, versioned on LangChain's release train (the package pins langchain>=1.4.5,<2.0.0), and a reader who wants to know exactly what happens on the tenth turn of a run must leave this repo — this teardown's loop section does exactly that, against separately pinned dependency source, and the boundary it draws is the honest summary of the design: everything about the tenth turn is LangGraph super-steps and LangChain routing; everything about why the tenth turn looks the way it does is the stack Deep Agents assembled. The assembly also hides in the other direction: features that read as defaults in the feature list — skills, memory, approvals — are conditional appends to the stack, present only when the caller asked, and the durable configurations are all opt-in. What create_deep_agent() builds out of the box is deliberately lighter than its own brochure: an ephemeral, shell-less agent with excellent context hygiene. Whether that is the right default is a judgment about libraries — they should be safe and small by default, and composable up to the brochure. By that standard the assembly is well judged; the brochure could say "assembly required" a little louder.

The through-line, set against the rest of this series: most harnesses own their loop and rent their runtime services; Deep Agents inverts it, renting the loop and owning the opinions. The inversion is the design.

Comparison matrix row

# Dimension Deep Agents (deepagents==0.7.25)
1 Agent loop LangChain create_agent graph on LangGraph — no loop in this repo; model/tools nodes with per-hook middleware nodes; turns until the model stops calling tools (routing edge → END); execution in Pregel super-steps with a checkpoint after every step; only budget is recursion_limit: 9_999 super-steps (stamped by LangChain's factory, re-stamped by Deep Agents; enforced as GraphRecursionError only when no stop condition is reached); DeepAgentState puts messages on a DeltaChannel (linear checkpoint growth); PatchToolCallsMiddleware repairs dangling tool calls left by interrupted runs
2 Tool system Middleware-provided: fs tools (ls/read_file/write_file/edit_file/delete/glob/grep) + execute (execution-capable backends only, filtered per request) + task delegation; caller tools verbatim; no tool search — visibility by construction allowlists, capability filtering, and profile excluded_tools; MCP via external adapters as ordinary tools
3 Model providers Any LangChain chat model via init_chat_model (provider:model strings); per-model harness profiles (Anthropic, OpenAI Codex, NVIDIA built in) and provider profiles; default model claude-sonnet-4-6 is a deprecated fallback
4 Prompt construction Caller prompt + harness-profile suffix (the authored base prompt is deprecated); middleware fragments appended per request — subagent roster in the task description, skills metadata, memory contents under <agent_memory>; LangChain prompt-caching middleware preserves the prefix
5 Memory/session LangGraph checkpoints (caller-supplied checkpointer; none by default); files in a DeltaChannel state channel (StateBackend, thread-scoped) or Store/Filesystem/Composite backends; non-mutating summarization events with evicted history offloaded to /conversation_history/*.md; tool results evicted at 20k tokens; AGENTS.md-style memory files injected when memory= is passed
6 Reasoning/planning No planner and no todo tool in the default stack — write_todos exists only in the Codex model profile (LangChain TodoListMiddleware); decomposition is by subagent delegation; optional RubricMiddleware grades the transcript with a grader sub-agent until satisfied or capped
7 Extensibility LangChain middleware API: replace-by-name stack surgery, profile exclusions with protected scaffolding, custom backends via BackendProtocol, declarative / compiled / remote (LangGraph Platform) subagents, Agent Skills with progressive disclosure, public profile registration
8 Interfaces Library first (a LangGraph compiled graph; invoke/stream are the runtime's); sibling packages: Deep Agents Code terminal app (dcode, client/server, TUI + headless), deepagents-acp server, Talon long-running host (messaging channels + cron), evals
9 Failure handling Dangling-tool-call repair on resume; summarization fallback on provider context-overflow (one smaller retry, then ContextOverflowError); construction-time failures for invalid assemblies (protected-middleware exclusion, permissions+execution NotImplementedError, duplicate subagent names, task-argument validation); history-offload failure degrades to an unrecoverable summary with a warning
10 Security model The backend is the boundary: default StateBackend cannot execute; LocalShellBackend runs host commands via shell=True, unsandboxed, under extensive docstring warnings; real isolation via BaseSandbox partner backends; first-match glob permission rules (allow/deny/interrupt) fence the built-in fs tools incl. symlink-resolved paths and filtered listings — and do not cover execute; HITL is LangChain's middleware, wired from interrupt_on + permission rules

Endnotes

All notes are VERIFIED against the pin they name. Deep Agents notes use GH = https://github.com/langchain-ai/deepagents/blob/c6c340d47d2013a2e7b7230698f73977b7de6756/ (tag deepagents==0.7.25). Dependency-loop notes (50 and up) name their repo in the note text and permalink into it at its own pin: langchain tag langchain==1.4.5 → f2bf626ccee0a0e88d560706d4fdad35e43116e5 (the release current when deepagents 0.7.25 was published; deepagents requires langchain>=1.4.5,<2.0.0), and langgraph tag 1.2.15 → 08a345637fb2bd499f69c90056a22c478a468817 (the latest core release inside langchain 1.4.5's langgraph>=1.2.11,<1.3.0 requirement).


  1. The three-layer framing, in the project's words: GH…/libs/ARCHITECTURE.md — "Deep Agents is an opinionated harness on top of create_agent(). It does not introduce a new runtime"; LangGraph "runs the agent as a graph," LangChain "builds the loop that calls the model, executes tools, and repeats until the model finishes." The repo's AGENTS.md agrees: "Deep Agents delegates graph assembly to LangChain's create_agent." ↩↩

  2. create_deep_agent ends in LangChain's factory: GH…/libs/deepagents/deepagents/graph.py#L989-L1010 — return create_agent(model, system_prompt=..., tools=..., middleware=deepagent_middleware, ..., checkpointer=checkpointer, store=store, state_schema=...).with_config({...}). The function itself starts at graph.py#L277; checkpointer and store pass straight through. ↩↩

  3. The middleware base types are LangChain's: graph.py imports AgentMiddleware, HumanInTheLoopMiddleware, and InterruptOnConfig from langchain.agents.middleware (GH…/libs/deepagents/deepagents/graph.py#L16-L36). The stack's classes are defined under libs/deepagents/deepagents/middleware/. ↩

  4. Model resolution: GH…/libs/deepagents/deepagents/graph.py#L630-L631 (resolve_model then _harness_profile_for_model); resolve_model composes LangChain's init_chat_model with provider-profile kwargs at GH…/libs/deepagents/deepagents/_models.py#L35-L57. ↩

  5. The stamped configuration: GH…/libs/deepagents/deepagents/graph.py#L1004-L1010 — "recursion_limit": 9_999 and metadata {"ls_integration": "deepagents", "lc_versions": {...}, "lc_agent_name": name}. ↩↩↩

  6. Main stack assembly: GH…/libs/deepagents/deepagents/graph.py#L889-L972 — the base list (FilesystemMiddleware at L890, SubAgentMiddleware at L898-L909, summarization + PatchToolCallsMiddleware at L912-L913), AsyncSubAgentMiddleware at L920, profile extras, SkillsMiddleware at L934, prompt caching at L935, MemoryMiddleware at L940, HumanInTheLoopMiddleware appended at L951 only when the merged interrupt_on is non-empty, UnsupportedContentMiddleware at L952. ↩

  7. Prompt caching is appended by this repo's helper but the classes are LangChain's: GH…/libs/deepagents/deepagents/middleware/_prompt_caching.py#L41-L50 appends AnthropicPromptCachingMiddleware (from langchain_anthropic.middleware) unconditionally and Bedrock/Fireworks variants when importable, all with unsupported_model_behavior="ignore". ↩

  8. Name-based merge: GH…/libs/deepagents/deepagents/graph.py#L210-L240 (_apply_custom_middleware: same name → replace in place; new → inserted after the last core-stack member, ahead of the tail). ↩↩

  9. Protected scaffolding: GH…/libs/deepagents/deepagents/graph.py#L247-L260 — _REQUIRED_MIDDLEWARE pairs FilesystemMiddleware and SubAgentMiddleware; the comment states removing either "silently breaks core features" and calls the filesystem middleware's permission enforcement "a security guarantee." Excluding one raises ValueError (_excluded_middleware.py, applied at graph.py L633 and after stack assembly). ↩

  10. Tool exclusion last: GH…/libs/deepagents/deepagents/graph.py#L969 appends _ToolExclusionMiddleware after caller middleware, with the comment that excluded names "cannot be restored by a custom wrap_model_call." ↩↩

  11. Subagent stacks: declarative specs at GH…/libs/deepagents/deepagents/graph.py#L719-L738 (FilesystemMiddleware, summarization, PatchToolCallsMiddleware, profile extras, optional skills, prompt caching, memory for forks at L738); the general-purpose subagent's at graph.py#L825-L860. Neither includes SubAgentMiddleware. ↩

  12. Talon's defaults: GH…/libs/talon/README.md — "The per-invocation graph recursion limit defaults to 500"; checkpoints persist in checkpoints.sqlite; the same README states Talon "does not yet implement production-grade security controls such as complete human-in-the-loop (HITL) approval policy... or multi-tenant boundaries" and is experimental/alpha. ↩↩

  13. DeepAgentState: GH…/libs/deepagents/deepagents/graph.py#L74-L77 — docstring "AgentState with DeltaChannel on messages to reduce checkpoint growth from O(N²) to O(N)", snapshot_frequency=50. The reducer: GH…/libs/deepagents/deepagents/_messages_reducer.py#L31, header noting it is adapted from LangGraph's _messages_delta_reducer (PR #7729). The files channel: GH…/libs/deepagents/deepagents/middleware/filesystem.py#L1297-L1302. ↩↩

  14. Dangling-call repair: GH…/libs/deepagents/deepagents/middleware/patch_tool_calls.py#L15-L60 — before_agent collects answered tool-call ids, appends synthetic error ToolMessages for unanswered ones ("did not complete - no result was recorded. It may have been cancelled or interrupted."), and returns the history rewritten via RemoveMessage(id=REMOVE_ALL_MESSAGES). ↩

  15. Capability filtering per request: GH…/libs/deepagents/deepagents/middleware/filesystem.py#L3027-L3052 computes unsupported tools from the resolved backend (supports_execution), applied in _filter_unsupported_tools_and_apply_prompt at filesystem.py#L3333. The execute tool's own graceful error for non-execution backends is in _create_execute_tool (same file, sync wrapper). ↩↩

  16. The task tool and its guidance: GH…/libs/deepagents/deepagents/middleware/subagents.py#L471-L498 (TASK_TOOL_DESCRIPTION: "Launch multiple agents concurrently when their tasks are independent, using a single message with multiple tool calls"). Parallel execution of multiple tool calls in one response is LangChain/LangGraph tool-node behavior (dependency). ↩

  17. State subtraction: GH…/libs/deepagents/deepagents/middleware/subagents.py#L782-L843 (_validate_and_prepare_state); the excluded set is _EXCLUDED_STATE_KEYS at subagents.py#L382-L408 — messages, todos, structured_response, skills_metadata, pinned_skills, skill-disclosure and rubric keys — plus caller PrivateStateAttr keys (collected at graph.py L972). Invocation is the nested subagent.invoke(...) inside the tool handler at subagents.py#L816-L875. ↩

  18. Result extraction and merge-back: GH…/libs/deepagents/deepagents/middleware/subagents.py#L725-L778 (_return_command_with_state_update: structured_response JSON, else last non-empty AIMessage text, wrapped as a ToolMessage in a Command update; other keys filtered by the exclusion sets). The unchanged-value rule is _is_unchanged at subagents.py#L416. ↩

  19. StateBackend mechanics: GH…/libs/deepagents/deepagents/backends/state.py#L38-L48 — "Backend that stores files in agent state (ephemeral)... Files persist within a conversation thread but not across threads"; reads/writes go through LangGraph's CONFIG_KEY_READ / CONFIG_KEY_SEND (same file, helpers at L54-L120). ↩

  20. Eviction: defaults tool_token_limit_before_evict=20000 and human_message_token_limit_before_evict=50000 at GH…/libs/deepagents/deepagents/middleware/filesystem.py#L1897-L1898; interception in wrap_tool_call at filesystem.py#L3821 delegating to _intercept_large_tool_result at filesystem.py#L3730; offload prefixes /large_tool_results and /conversation_history are set from the backend's artifacts root in the same class's __init__. ↩↩

  21. The built-in tool set: FsToolName at GH…/libs/deepagents/deepagents/middleware/filesystem.py#L1607 and the factory tuple at filesystem.py#L2020-L2029; construction-time exclusion comment at L2030-L2034 ("omitted here entirely, not just hidden from the model's schema"). ↩

  22. write_todos only in the Codex profile: GH…/libs/deepagents/deepagents/profiles/harness/_openai_codex.py#L19 (import from langchain.agents.middleware) and same file #L72-L77 ("Includes TodoListMiddleware (the write_todos tool) since the Codex system prompt references reconciling TODO/plan items via write_todos"). A search of the core package finds no other TodoListMiddleware reference. ↩

  23. MCP: no client code in libs/deepagents/deepagents/ — the only mcp matches are a skills-module comment about generated tool names (GH…/libs/deepagents/deepagents/middleware/skills.py#L180-L194). Talon's MCP loading from ~/.deepagents/.mcp.json is described in GH…/libs/talon/README.md. ↩

  24. Permission rules: FilesystemPermission at GH…/libs/deepagents/deepagents/middleware/filesystem.py#L367-L406 (operations × paths × allow/deny/interrupt, patterns must be absolute, no ..); first-match evaluation in _check_fs_permission at filesystem.py#L408-L418. ↩

  25. Symlink-aware matching and result filtering: _resolve_real_path at GH…/libs/deepagents/deepagents/middleware/filesystem.py#L421-L433 (the class docstring at L367-L373 states rules match "both the requested path and its symlink-resolved target; a deny on either blocks the call"); listing/glob/grep filtering helpers at filesystem.py#L697-L790. ↩

  26. Permission→interrupt glue: GH…/libs/deepagents/deepagents/middleware/_fs_interrupt.py#L1-L40 — module docstring ("FilesystemMiddleware itself doesn't know about HITL — it only enforces deny rules...") and the exact/bulk scope table _FS_TOOL_PATH_ARGS; the bulk-scope comment states a pathless bulk call fires "unconditionally for any interrupt-mode rule, because a pathless bulk call can touch anything." ↩

  27. Merge semantics: GH…/libs/deepagents/deepagents/graph.py#L186-L202 (_merge_fs_interrupt_on: "User-defined interrupt_on entries take precedence over generated filesystem-permission entries"; returns None when empty, "allowing HumanInTheLoopMiddleware to be omitted"). The middleware class is imported from LangChain at graph.py L17. ↩

  28. LocalShellBackend: GH…/libs/deepagents/deepagents/backends/local_shell.py#L27-L107 (class docstring warnings: "unrestricted shell execution on your local machine", "No process isolation", "No resource limits", HITL "STRONGLY RECOMMENDED as your primary safeguard"); execution is subprocess.run(...) with shell=True at local_shell.py#L304-L309. ↩

  29. Sandbox protocol and base: SandboxBackendProtocol at GH…/libs/deepagents/deepagents/backends/protocol.py#L886; BaseSandbox at GH…/libs/deepagents/deepagents/backends/sandbox.py#L1587. Partner implementations live in libs/partners/{daytona,modal,runloop,vercel,quickjs}; LangSmithSandbox in libs/deepagents/deepagents/backends/langsmith.py. ↩↩

  30. FilesystemBackend honesty clause: GH…/libs/deepagents/deepagents/backends/filesystem.py#L132-L135 — virtual_mode=True "blocks path traversal (.., ~) and absolute paths outside root_dir, but it does not provide sandboxing or process isolation." ↩

  31. Permissions × execution refusal: GH…/libs/deepagents/deepagents/middleware/filesystem.py#L1974-L1983 — construction raises NotImplementedError: "FilesystemMiddleware does not yet support permissions with backends that provide command execution (SandboxBackendProtocol). Tool-level permissions for the execute tool are not implemented." ↩

  32. Tracing attribution: run metadata at GH…/libs/deepagents/deepagents/graph.py#L1004-L1010 (see 5); subagent tracing context at GH…/libs/deepagents/deepagents/middleware/subagents.py#L524-L546 tags ls_agent_type="subagent" in LangSmith metadata. langsmith>=0.14.8 is a direct dependency in libs/deepagents/pyproject.toml. Whether tracing is on is controlled by LangSmith's environment configuration (dependency). ↩

  33. Summarization composition: GH…/libs/deepagents/deepagents/middleware/summarization.py#L627 — self._lc_helper = LCSummarizationMiddleware(...) inside _DeepAgentsSummarizationMiddleware (class at L523); the prompt is LangChain's DEFAULT_SUMMARY_PROMPT with the media-reference addendum spliced before its <messages> marker at summarization.py#L110-L118. ↩

  34. The event model: SUMMARIZATION_EVENT_KEY = "_summarization_event" at GH…/libs/deepagents/deepagents/middleware/summarization.py#L135, the SummarizationEvent shape at L142-L153, private state fields at L198-L211; effective-history reconstruction in _get_effective_messages at summarization.py#L805; offload in _offload_to_backend at summarization.py#L1227, writing markdown under /conversation_history/{session_id}.md (module docstring, L34-L42); the summary message embeds the path via _build_new_messages_with_path at L772. ↩

  35. The factory's own delta list: GH…/libs/deepagents/deepagents/middleware/summarization.py#L1786-L1822 — "Backend offload of evicted history... LangChain drops evicted messages with no recovery path"; "Non-mutating message state. Summarization is tracked in a private _summarization_event field... LangChain rewrites it with RemoveMessage(id=REMOVE_ALL_MESSAGES)." The factory is create_summarization_middleware at L1772. ↩↩

  36. Model-aware defaults: GH…/libs/deepagents/deepagents/middleware/summarization.py#L262-L307 (compute_summarization_defaults: profile → trigger=("fraction", 0.85), keep=("fraction", 0.10); fallback → trigger=("tokens", 170000), keep=("messages", 6); truncate-args defaults alongside). ↩

  37. The on-demand tool: SummarizationToolMiddleware at GH…/libs/deepagents/deepagents/middleware/summarization.py#L1950 exposes compact_conversation (schema at L131) and composes with the summarization middleware; create_deep_agent's stack (graph.py L889-L972) adds only the automatic middleware. Overflow fallback and budget enforcement are in wrap_model_call at summarization.py#L1487-L1623. ↩

  38. Parallel-mutation guard: GH…/libs/deepagents/deepagents/middleware/filesystem.py#L199-L225 — _parallel_file_mutation_error: "Error: parallel file mutations to the same path are not allowed." ↩

  39. Memory middleware: class at GH…/libs/deepagents/deepagents/middleware/memory.py#L180 ("Middleware for loading agent memory from AGENTS.md files"); loading in before_agent at memory.py#L279; the prompt template opens with <agent_memory> at memory.py#L105. Installed only when memory= is passed (graph.py L940). ↩

  40. Default backend and pass-through persistence: default StateBackend() at GH…/libs/deepagents/deepagents/graph.py#L653; checkpointer/store forwarded at graph.py#L989-L1003. Durable backends: StoreBackend (GH…/libs/deepagents/deepagents/backends/store.py#L90), FilesystemBackend, CompositeBackend (GH…/libs/deepagents/deepagents/backends/composite.py#L228); the protocol itself is BackendProtocol at GH…/libs/deepagents/deepagents/backends/protocol.py#L404. ↩

  41. Profiles: HarnessProfile / registration API exported from the package root (GH…/libs/deepagents/deepagents/init.py exports HarnessProfile, register_harness_profile, ProviderProfile, register_provider_profile, GeneralPurposeSubagentProfile); built-in model profiles live in libs/deepagents/deepagents/profiles/harness/ (_anthropic_sonnet_4_6.py, _anthropic_opus_4_7.py, _anthropic_haiku_4_5.py, _openai_codex.py, _nvidia_nemotron_3_ultra.py). Resolution per model at graph.py L631. ↩

  42. Skills: module docstring at GH…/libs/deepagents/deepagents/middleware/skills.py#L1-L50 ("implements Anthropic's agent skills pattern with progressive disclosure"; SKILL.md + YAML frontmatter; later sources override earlier); SkillsMiddleware at skills.py#L916, whose docstring documents pinned_skills (named skills' bodies appended as HumanMessages with lc_source="pinned_skill"). Skill-scoped tool disclosure is implemented in middleware/_skill_tools.py. Installed only when skills= is passed (graph.py L934). ↩

  43. Subagent forms: declarative SubAgent and CompiledSubAgent TypedDicts at GH…/libs/deepagents/deepagents/middleware/subagents.py#L56-L276; raw specs compiled by create_sub_agent at subagents.py#L553; the general-purpose default at subagents.py#L501-L513, auto-added at graph.py L824-L886. Remote form: AsyncSubAgent at GH…/libs/deepagents/deepagents/middleware/async_subagents.py#L39-L71 ("Compatible with LangGraph Platform / LangSmith Deployment"), middleware class at L919. ↩

  44. Rubric grading: GH…/libs/deepagents/deepagents/middleware/rubric.py#L1-L9 — a "separate grader sub-agent against the transcript... Grading repeats until the grader returns satisfied" or a cap; verdict vocabulary at L67-L94. RubricMiddleware is exported from the package root but is not referenced by graph.py's default stack. ↩

  45. Public surface: GH…/libs/deepagents/deepagents/init.py — create_deep_agent, DeepAgentState, the middleware classes (FilesystemMiddleware, MemoryMiddleware, RubricMiddleware, SubAgentMiddleware, AsyncSubAgentMiddleware), spec types, and profile registration. The return type is LangGraph's CompiledStateGraph (graph.py L296 return annotation). ↩

  46. Deep Agents Code: GH…/libs/code/ARCHITECTURE.md — "a prebuilt terminal coding agent built on top of the deepagents SDK... a reference implementation"; client/server split, "Headless mode uses the same agent runtime as the interactive UI." SDK wiring at GH…/libs/code/deepagents_code/agent.py#L14-L15 (create_deep_agent, CompositeBackend, LocalShellBackend imports) with the backend constructed at L3127-L3133 of the same file. ↩

  47. ACP server: GH…/libs/acp/deepagents_acp/server.py#L10-L31 imports the acp SDK (run_agent as run_acp_agent, schema types) to serve a deep agent over the Agent Client Protocol. ↩

  48. task argument validation: TaskToolSchema at GH…/libs/deepagents/deepagents/middleware/subagents.py#L433-L471 — the validator's docstring: "Models sometimes put the real instructions under an invented key (e.g. prompt) and leave a short label in description. Ignoring the extra key dispatched the subagent with the label alone and reported success; a validation error goes back to the model as a tool error naming the key." ↩

  49. Fork fences: _FORK_TASK_PREAMBLE at GH…/libs/deepagents/deepagents/middleware/subagents.py#L345-L356; fork history construction _fork_messages at L358; the refusal string _FORK_RECURSION_REFUSAL at subagents.py#L79-L81 returned by the task handler when the forked-context key is set; the beta warning at subagents.py#L974. SubAgent's docstring marks mode="fork" "Experimental" and forbids skills under it (L56-L179). ↩

  50. langchain (1.4.5) — the two working nodes: the graph is a StateGraph created at langchain…/libs/langchain_v1/langchain/agents/factory.py#L1237-L1246 (state schemas resolved middleware-first, caller's last, L1227-L1235); the model node is registered at factory.py#L1611 and its handler model_node (L1549-L1585) runs the request through the chained wrap_model_call handler (handlers chained at L1181-L1202) into _execute_model_sync, which binds tools and invokes the model (L1518). The tools node (L1615) is LangGraph's prebuilt ToolNode (imported L35), constructed with the chained wrap_tool_call wrappers at factory.py#L1140-L1148. ↩

  51. langchain (1.4.5) — the routing edges: _make_model_to_tools_edge at langchain…/libs/langchain_v1/langchain/agents/factory.py#L1991-L2043 — "3. If the model hasn't called any tools, exit the loop / this is the classic exit condition for an agent loop" (L2020-L2022); pending calls fan out as [Send("tools", [tool_call]) for tool_call in pending_tool_calls] (L2034). _make_tools_to_model_edge at factory.py#L2072-L2113 — return_direct/structured-output exits, otherwise back to the loop entry. Both are wired as conditional edges at L1755-L1800. ↩↩↩

  52. langchain (1.4.5) — hooks become nodes: for each middleware overriding a state hook, the factory adds a {name}.before_agent / .before_model / .after_model / .after_agent node (langchain…/libs/langchain_v1/langchain/agents/factory.py#L1620-L1733); entry/loop-entry/loop-exit/exit resolution and the START edge are at factory.py#L1736-L1743. ↩↩↩

  53. langgraph (1.2.15) — Pregel super-steps and checkpoint cadence: PregelLoop.tick() at langgraph…/libs/langgraph/langgraph/pregel/_loop.py#L633-L720 prepares the next tasks from updated channels; tasks execute concurrently via PregelRunner (langgraph…/libs/langgraph/langgraph/pregel/_runner.py#L136-L137); after_tick() at _loop.py#L720-L786 applies the tasks' writes to the channels and saves a checkpoint — self._put_checkpoint({"source": "loop"}) at L786. The input checkpoint ({"source": "input"}) is at _loop.py#L1157. Durability defaults to "async" (langgraph…/libs/langgraph/langgraph/pregel/main.py#L2695-L2696); "sync" waits on the checkpoint future after each tick (main.py L3078-L3079). ↩↩↩↩

  54. langgraph (1.2.15) — recursion-limit mechanics: at loop start, self.step = checkpoint_metadata["step"] + 1 and self.stop = self.step + config["recursion_limit"] + 1 (langgraph…/libs/langgraph/langgraph/pregel/_loop.py#L1858-L1859; async twin at L2116-L2117); tick() checks if self.step > self.stop and sets status "out_of_steps" (_loop.py L640-L643); the driver converts that status into GraphRecursionError — "Recursion limit of {recursion_limit} reached without hitting a stop condition" — at langgraph…/libs/langgraph/langgraph/pregel/main.py#L3093-L3101 (async twin L3571-L3579; the exception class is at libs/langgraph/langgraph/errors.py#L68). ↩

  55. langchain (1.4.5) — what the factory adds itself: the middleware parameter defaults to () (langchain…/libs/langchain_v1/langchain/agents/factory.py#L897) and is used as passed (middleware tools collected at L1090; only duplicate names are rejected, L1156-L1159) — no default middleware is inserted. The model node's per-call repair is _patch_invalid_tool_calls (factory.py#L692, called at L1551). The stamped config and compile: factory.py#L1896-L1926 — comment "Set recursion limit to 9_999" (citing a LangGraph issue), config = {"recursion_limit": 9_999}, metadata ls_integration: "langchain_create_agent", then graph.compile(checkpointer=..., store=...).with_config(config). Deep Agents' own .with_config (5) then re-stamps the same limit and replaces the integration metadata. ↩↩

  56. langgraph (1.2.15) — interrupt(): langgraph…/libs/langgraph/langgraph/types.py#L903. Its docstring states the contract: the first invocation raises GraphInterrupt and surfaces the value; resume uses Command(resume=...); "The graph resumes from the start of the node, re-executing all logic"; multiple interrupts are matched to resume values by order; "To use an interrupt, you must enable a checkpointer, as the feature relies on persisting the graph state" (L909-L923). The implementation returns the matched resume value from the task scratchpad (L1023-L1041) and otherwise raises GraphInterrupt carrying the Interrupt (L1043-L1051). ↩

  57. langchain (1.4.5) — the HITL flow on that primitive: decision vocabulary Literal["approve", "edit", "reject", "respond"] at langchain…/libs/langchain_v1/langchain/agents/middleware/human_in_the_loop.py#L65; the class at L240. Its after_model hook scans the last AIMessage's tool calls against interrupt_on (with when predicates), builds one HITLRequest, and calls decisions = interrupt(hitl_request)["decisions"] (human_in_the_loop.py#L458-L481); decisions are validated for count (L483-L490) and applied — approved kept, edited rewritten and recorded for wrap_tool_call to substitute at execution (L492-L538; wrap_tool_call at L644), rejected replaced with artificial ToolMessages. ↩

  58. langgraph (1.2.15) — the tools node: ToolNode at langgraph…/libs/prebuilt/langgraph/prebuilt/tool_node.py#L630; per-call execution in _run_one (L1031) → _execute_tool_sync (L930), which runs the (factory-chained) wrap_tool_call wrappers around the tool. Tool exceptions become error ToolMessages by default (_default_handle_tool_errors, L391; default parameter at L761). ↩