DeepAgents — Multi-Step Agent Framework by LangChain

What it is

DeepAgents is an agent harness built on LangGraph by the LangChain team. It provides planning tools, a filesystem backend, and sub-agent spawning for complex multi-step tasks like codebase refactoring, research, and document generation. The framework handles the orchestration layer so you can focus on defining what each agent does rather than how agents coordinate.

DeepAgents is designed for developers building AI applications that require multi-step reasoning, tool use, and coordination between specialized sub-agents.

How it saves time or tokens

Building multi-step agent workflows from scratch requires implementing planning logic, state management, error recovery, and sub-agent coordination. DeepAgents provides these as built-in primitives. The planning tool breaks complex tasks into steps automatically, the filesystem backend persists intermediate results, and sub-agent spawning lets you delegate subtasks without manual orchestration. This reduces both development time and the token cost of re-implementing orchestration patterns.

How to use

1. Install DeepAgents:

pip install deepagents

1. Create and run a simple agent:

from deepagents import Agent

agent = Agent(model='claude-sonnet-4-20250514')
result = agent.run('Refactor the authentication module to use JWT tokens')
print(result)

1. For more complex workflows, use the CLI:

deepagents run 'Add comprehensive tests for the payment module'

The agent will plan the task, create sub-agents as needed, and produce the final output.

Example

A multi-step refactoring workflow:

from deepagents import Agent, PlanningTool, FilesystemBackend

agent = Agent(
    model='claude-sonnet-4-20250514',
    tools=[PlanningTool(), FilesystemBackend(root='./src')],
    max_steps=20,
)

# The agent will:
# 1. Analyze the current auth module
# 2. Plan the refactoring steps
# 3. Spawn sub-agents for each file change
# 4. Validate the changes compile
# 5. Return a summary of changes made
result = agent.run(
    'Migrate src/auth/ from session-based to JWT authentication. '
    'Update all route handlers that check req.session.'
)

Related on TokRepo

• Multi-agent frameworks — Compare multi-agent orchestration frameworks
• LangGraph agents — Deep dive into the LangGraph framework

Common pitfalls

• Setting max_steps too low for complex tasks. The agent may abandon a task mid-way if it runs out of steps. Start with a generous limit and tune down based on observed behavior.
• Not providing filesystem access when the task involves code changes. Without a FilesystemBackend, the agent can only suggest changes but cannot apply them directly.
• Expecting deterministic outputs. Multi-step agent workflows involve multiple LLM calls, each with some variability. Run important tasks multiple times and validate results.