Sign in Subscribe
news

LangChain Deep Agents

Sebastien Dubois

Sebastien Dubois

— 6 min read

Canonical version: LangChain Deep Agents.

LangChain Deep Agents is an open-source "batteries-included" agent harness built on top of LangGraph. It provides a pre-configured, opinionated agent system for complex, long-horizon tasks. Ships as a Python SDK (deepagents), a TypeScript port (deepagents.js) and a terminal coding agent now called Deep Agents Code (deepagents-code). MIT license, Python >= 3.11.

Where it sits in the stack: LangGraph is the runtime, LangChain's create_agent is a minimal harness on top of it, and Deep Agents is the opinionated harness on top of create_agent. A hosted version, Managed Deep Agents, runs on LangSmith (see below).

The four pillars

The core algorithm remains unchanged from simple agents (LLM in a loop calling tools). The sophistication comes from four architectural components:

  1. Detailed system prompt: comprehensive instructions guiding tool usage with few-shot examples, inspired by Claude Code's long system prompts
  2. Planning tool (write_todos): a built-in todo list mechanism that functions as context engineering rather than genuine task management. Breaks down complex tasks, tracks progress, adapts plans
  3. Sub-agents (via task tool): spawns specialized child agents for subtasks with isolated context windows. Supports routing simpler tasks to cheaper models for cost optimization. Customizable via AGENTS.md files
  4. File system access: persistent workspace allowing agents to store notes, maintain state, and collaborate. Pluggable backends (in-memory, local disk, LangGraph store, sandboxes like Modal/Daytona/Deno)

Key insight

The distinction between shallow and deep agents is not algorithmic. It is context engineering: carefully designed prompts, structured planning, task decomposition, and state persistence working together.

CLI features

The CLI is now branded Deep Agents Code, a pre-built coding agent in the terminal (similar to Claude Code) that works with any LLM. Built-in tools for file operations, shell execution, HTTP requests, web search, sub-agent delegation, and context management. Supports persistent memory as markdown files, automatic context compaction, session resumption, and a skills system. Human-in-the-loop approval for sensitive operations.

Skills revamp (October 2026)

On 2026-10-07, LangChain published "Revamping Skills in Deep Agents" (Sydney Runkle). The reason given: enterprise skill registries are growing to thousands of skills shared across teams and agents. Their own GTM agent runs on more than 50 skills (meeting-prep, call-transcripts, competitive-intel-card, etc.).

The format didn't change. Deep Agents skills follow the AI Agent Skills specification: a folder with a SKILL.md (YAML frontmatter with name and description, then the instructions), plus optional scripts/, references/ and assets/ folders. Skills written for Claude Code or installed from Skills.sh work here too, as long as they don't rely on harness-specific extras.

Loading is Progressive Disclosure in three levels, handled by SkillsMiddleware:

  1. Discovery: at startup, the name and description of every configured skill go into the system prompt
  2. Read: when a task matches a skill, the agent reads the full SKILL.md with read_file
  3. Execute: the agent reads scripts and reference files only when the instructions call for them

What's new:

  • Tools bound to skills (deepagents>=0.7.22): list the tool names under metadata.include_tools in the frontmatter, as a space-separated string (a YAML list does NOT match anything). Then pass those tools to SkillsMiddleware(tools=[...]) instead of the agent. A bound tool stays out of context until the agent reads its skill, and calling it before that fails as an unknown tool. If summarization drops the read from the conversation, the tool goes away again until the skill is re-read. A skill can also list a label instead of tool names; a resolver function then maps the label to tools at runtime (e.g., every tool of an MCP server, or only the tools the current user is allowed to call)
  • Pinned skills (>=0.7.23): pass pinned_skills: ["meeting-prep"] with the run input, and the middleware appends that skill's SKILL.md (without frontmatter) to the conversation as a tagged message before the next model call. The agent starts working on model call 1 instead of 2, and the right skill is guaranteed to be loaded, along with its bound tools. Deep Agents doesn't parse messages itself, so your app picks the syntax (e.g., /meeting-prep)
  • Reloading mid-thread (>=0.7.16): skills load once per thread and stay in agent state when a checkpointer is configured (LangSmith deployments configure one automatically). Set skills_metadata to None in the run input, through update_state, or from middleware (in after_agent), and the next run rescans every source. Use None, not []: an empty list means "no skills" for the rest of the thread

Effect on the prompt cache: on newer Anthropic and OpenAI models that accept tools mid-conversation, bound tools arrive in a new system message, so the cached prefix stays valid. On other models they're appended to the request's tool list, which invalidates the cache. Pinned skill messages are added once and never edited, so they don't break it either. A reload that finds a different set of skills changes the system prompt and DOES invalidate the cache; one that finds the same set costs nothing.

Scoping: the SDK loads only the sources you pass in skills. It doesn't scan ~/.deepagents/ or ~/.agents/ on its own. Deep Agents Code layers four sources, from lowest to highest precedence: ~/.deepagents/{agent}/skills/, ~/.agents/skills/, <project>/.deepagents/skills/ and <project>/.agents/skills/. Skill files can sit on a FilesystemBackend (disk), a StateBackend (current thread) or a StoreBackend (durable, and namespaceable per user, tenant or org to isolate skill libraries).

Migration: nothing breaks. Passing skills=[...] to create_deep_agent still creates the middleware for you. You only build SkillsMiddleware yourself, and pass it in middleware=[...], when you want bound tools.

My take: tool binding is the most useful of the three. The agent can't call a tool before it has read how to use it, and tool schemas stay out of the Context Window until a task needs them. Keep in mind that include_tools is a Deep Agents extension stored in the spec's free-form metadata field (it has nothing to do with allowed-tools). Other harnesses won't know about the binding, so a skill meant to be portable shouldn't depend on it.

Managed Deep Agents (October 2026)

Managed Deep Agents (MDA) is the hosted version, part of LangSmith. You write the agent as a project folder (instructions, tools, skills, and the model, declared with define_deep_agent), and LangSmith runs the Deep Agents harness on LangSmith Agent Server (threads, runs, streaming, an MCP endpoint), with sandboxes and schedules on top. Same category as Claude Managed Agents and Codex Cloud.

The 2026-10-07 release, a public beta, added:

  • Schedules SDK: the agent creates reminders and recurring tasks from inside a conversation (schedules.create(...) with a cron expression and a timezone, or at for a one-time run). Each schedule runs as the person who asked, with their permissions and connections, and posts results back to the channel it was created in. One-time schedules reply in the original thread. LangChain suggests wrapping it in a tool so users can create, list, update and delete schedules by chatting
  • Per-run configuration: the agent can be a function that receives the runtime at the start of each run and returns a define_deep_agent definition, choosing the model, instructions, skills, MCP servers and sandbox for that run. One deployment can then serve several teams or repositories (the caller passes e.g. context={"repository": "payments-service"}). Since the configuration is set before the model runs, the agent never sees skills or MCP tools outside of it, which also works as access control
  • Slack reactions: the agent reacts to a message (👀 by default) to show it picked it up before it replies. The reactions option on channels.slack turns this off, changes the emoji, or picks one per message through a function, which can call a decision model like Jev

To get started: uvx --from managed-deepagents mda init my-agent, then uv run mda deploy. The previous release added per-user memory, custom HTTP channels for triggering runs from any service, and built-in web search powered by Parallel.

Per-run configuration is the hosted equivalent of what the SDK docs call "select skills by context": the skill set is decided in code before the run, not by the model during it.

Provider agnostic

Works with any LLM supporting tool calling (OpenAI, Anthropic, Google, Ollama, Groq, xAI). Built on LangGraph for streaming, persistence, checkpointing, and production-ready runtime.

References

About Sébastien

Ready to get to the next level?

Found this valuable? Share it with someone who needs it.

Join 6,000+ readers. Get practical systems for knowledge & AI. Free.

Subscribe ✨

Free: Knowledge System Checklist

A clear roadmap to building your own knowledge system. Subscribe and get it straight to your inbox.

6,000+ readers. No spam. Unsubscribe anytime.

Subscribe