DeepAgents — Multi-Step Agent Framework by LangChain

What it is

DeepAgents — Multi-Step Agent Framework by LangChain is a public TokRepo workflow curated around the upstream project at langchain-ai/deepagents.

It is best for developers who want a repeatable, copy-pasteable setup that starts from the workflow steps (not marketing claims) and links back to the canonical upstream docs.

Quick facts (verified sources):

• GitHub stars: 23152
• Last pushed: 2026-05-21T18:34:38Z
• License (SPDX): MIT
• TokRepo view_count: 269

From upstream README (for context):

<div align="center">

<a href="https://docs.langchain.com/oss/python/deepagents/overview#deep-agents-overview">

<picture>

<source media="(prefers-color-scheme: dark)" srcset=".github/images/logo-dark.svg">

<source media="(prefers-color-scheme: light)" srcset=".github/images/logo-light.svg">

<img alt="Deep Agents Logo" src=".github/images/logo-dark.svg" width="50%">

</picture>

</a>

How it saves time or tokens

This workflow saves time by packaging a “known-good starting path” into a single, reusable page: you get the upstream repo link, the workflow’s step-by-step instructions, and a short set of pitfalls to avoid.

If you run agents or CLI tools repeatedly, the biggest cost is usually re-discovering the same setup details and re-checking prerequisites. A curated workflow reduces that repeated context-building and keeps your prompts shorter because you can point your agent back to a stable set of steps and citations.

How to use

1. DeepAgents — Multi-Step Agent Framework by LangChain

Example

Quick Use\n\n``bash\npip install deepagents\n`\n\n`python\nfrom deepagents import Agent\n\nagent = Agent(model="claude-sonnet-4-20250514")\nresult = agent.run("Refactor the authentication module to use JWT tokens")\nprint(result)\n`\n\nOr use the CLI:\n`bash\ndeepagents run "Add comprehensive tests for the API layer"\n`\n\n---\n\n## Intro\n\nDeepAgents is a multi-step agent framework built on LangGraph by the LangChain team with 16,500+ GitHub stars. It provides a planning tool, filesystem backend, and the ability to spawn sub-agents for complex tasks like codebase refactoring, research, and multi-file editing. Unlike simple chat-based agents, DeepAgents creates execution plans, tracks progress, and can delegate subtasks to specialized sub-agents. Best for developers building production AI agent systems that handle multi-step workflows. Works with: Claude, GPT-4, Gemini, any LangChain-supported model. Setup time: under 2 minutes.\n\n---\n\n## Core Architecture\n\n### Planning Tool\nBefore executing, DeepAgents creates a structured plan:\n\n`python\nagent = Agent(model="claude-sonnet-4-20250514", planning=True)\nresult = agent.run("Migrate the codebase from Express to Fastify")\n\n# Agent creates a plan:\n# 1. Analyze current Express routes and middleware\n# 2. Create Fastify equivalents\n# 3. Migrate route handlers\n# 4. Update tests\n# 5. Verify all endpoints work\n`\n\n### Sub-Agent Spawning\nComplex tasks get broken into subtasks, each handled by a specialized sub-agent:\n\n`python\nfrom deepagents import Agent, SubAgent\n\nresearcher = SubAgent(role="researcher", model="claude-sonnet-4-20250514")\ncoder = SubAgent(role="coder", model="claude-sonnet-4-20250514")\nreviewer = SubAgent(role="reviewer", model="gpt-4o")\n\nagent = Agent(\n sub_agents=[researcher, coder, reviewer],\n workflow="research -> code -> review"\n)\nresult = agent.run("Build a rate limiting middleware")\n`\n\n### Filesystem Backend\nPersistent state across runs — agents remember previous work:\n\n`python\nagent = Agent(\n model="claude-sonnet-4-20250514",\n backend="filesystem",\n workspace="./agent-workspace"\n)\n`\n\n### NVIDIA OpenShell Integration\nSecure code execution in sandboxed containers for untrusted operations.\n\n### Key Stats\n- 16,500+ GitHub stars\n- Built on LangGraph by LangChain team\n- Sub-agent spawning for complex tasks\n- Filesystem persistence across runs\n- TypeScript version available (deepagentsjs)\n\n### FAQ\n\nQ: What is DeepAgents?\nA: DeepAgents is a multi-step agent framework by the LangChain team that uses planning, sub-agent delegation, and persistent state to handle complex development tasks beyond simple chat-based interactions.\n\nQ: Is DeepAgents free?\nA: Yes, open-source under MIT license.\n\nQ: How is DeepAgents different from LangChain?\nA: LangChain is a general LLM framework. DeepAgents is specifically designed for multi-step agentic tasks with built-in planning, sub-agent orchestration, and filesystem persistence.\n\n---\n\n## Source & Thanks\n\n> Created by LangChain AI. Licensed under MIT.\n>\n> deepagents — ⭐ 16,500+\n\nThanks to the LangChain team for advancing the state of multi-step AI agents.\n\n---\n\n<!-- ZH -->\n\n\n## Quick Use\n\n`bash\npip install deepagents\n`\n\n`python\nfrom deepagents import Agent\n\nagent = Agent(model="claude-sonnet-4-20250514")\nresult = agent.run("Refactor the auth module to use JWT")\nprint(result)\n``\n\n---\n\n## Intro\n\nDeepAgents is a multi-step agent framework built on LangGraph by the LangChain team, with 16,500+ GitHub stars. It provides planning tools, a filesystem backend, and sub-agent spawning for complex tasks like code refactoring, research, and multi-file edits. Unlike simple chat agents, DeepAgents creates execution plans, tracks progress, and delegates subtasks to specialized sub-agents.\n\n---\n\n## Source & Thanks\n\n> Created by LangChain AI. Licensed under MIT.\n>\n> deepagents — ⭐ 16,500+\n

Related on TokRepo

• Multi-agent tools — Related agent frameworks and orchestration patterns.
• Automation tools — Build repeatable workflows around this asset.

Common pitfalls

• Skipping the upstream README and relying on a copied snippet without checking prerequisites (OS, runtime, permissions).
• Treating example configs as production-ready without reviewing secrets handling and access control.
• Not pinning versions (CLI/tools) and then debugging breakages after automatic upgrades.

Operational checklist (generic, verify against upstream docs)

• Confirm prerequisites (runtime version, OS support, system packages).
• Keep secrets out of the repo (env vars or a secret manager).
• Start with the smallest end-to-end action and expand only after it works.
• Add timeouts, retries, and clear logs before you run this in CI.
• Record the exact versions you tested (tool, runtime, dependencies).

How to adapt this workflow for a team

If more than one person will run this, treat the workflow like a small runbook. Write down: (1) the baseline command that proves it works, (2) where credentials live, and (3) what “good output” looks like. Then make changes one at a time: pin versions, add a wrapper script, and only then integrate into automation. This keeps troubleshooting simple because you always have a known-good reference path to compare against.

Security and reliability notes (generic)

Before you automate, do a quick threat-model pass: what data flows into the tool, what leaves it, and what gets stored. Avoid pasting secrets into prompts or config committed to git. If the workflow calls remote services, document rate limits and error handling; transient failures are normal, so your automation should degrade gracefully. If you store artifacts (logs, caches, indexes), decide retention and access control up front.

When to stop and read upstream docs

If you hit any ambiguity—unsupported platforms, unclear flags, auth failures, or unexpected output—pause and consult the upstream README and release notes. TokRepo pages are curated entrypoints, but upstream docs define the real contracts: configuration formats, supported versions, and breaking changes. A useful habit is to keep a single “source of truth” link (the repo URL and README) in your internal notes and always validate against it before debugging.

Troubleshooting checklist (generic)

• If a command fails: rerun with verbose logging and capture the full stderr/stdout.
• If an auth step fails: verify which environment variables are required and where they are read from.
• If a tool cannot be found: confirm PATH, the install location, and the runtime version match the README.
• If output is empty or partial: confirm you are calling the correct entrypoint and that network access is allowed.
• If a workflow step is outdated: prefer upstream docs over copied snippets and update your local notes first.

Reproducibility tips (generic)

For long-lived workflows, reproducibility matters more than cleverness. Prefer a small set of pinned versions, a short “bootstrap” script, and a documented smoke test. If you run this across machines, consider using containers or a dev environment manager so differences in OS packages and shell config do not become hidden variables. Finally, keep a changelog: when the workflow breaks, you can correlate the break with an upstream release or an environment change instead of guessing.