langchain deep agents py

Framework for building complex multi-step AI agent systems

$ npx docs2skills add deep-agents-langchain-py

SKILL.md

LangChain Deep Agents

Complex multi-step AI agent framework with built-in planning and context management

What this skill does

Deep Agents is an "agent harness" built on LangChain that provides sophisticated capabilities for complex, multi-step tasks. Unlike basic agent frameworks that just handle tool calling loops, Deep Agents includes built-in tools for task planning (write_todos), file system operations (read_file, write_file, edit_file, ls), and subagent spawning (task tool) that enable context isolation and delegation.

The framework addresses key limitations in agent development: context window overflow when handling large amounts of data, lack of persistent planning across conversation turns, and inability to break down complex tasks into manageable subtasks. Deep Agents uses the file system as external memory, allowing agents to offload context and work with variable-length tool results while maintaining state.

Built on LangGraph runtime, it provides durable execution, streaming, human-in-the-loop capabilities, and long-term memory through LangGraph's Memory Store. This makes it ideal for applications requiring persistent context, complex reasoning chains, and robust execution patterns that can recover from failures.

Prerequisites

Python 3.8+
LangChain core libraries (automatically installed)
LangGraph runtime (automatically installed)
Model provider API key (OpenAI, Anthropic, etc.)
File system access for context storage
Optional: Sandbox environment for code execution

Quick start

pip install -qU deepagents

from deepagents import create_deep_agent

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_deep_agent(
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

# Run the agent
result = agent.invoke(
    {"messages": [{"role": "user", "content": "what is the weather in sf"}]}
)

Core concepts

Agent Harness Architecture: Deep Agents wraps the standard tool-calling loop with pre-built capabilities. The core loop remains the same (plan → act → observe → repeat) but includes sophisticated built-in tools that most complex agents need.

Context Management Strategy: Uses file system as external memory to prevent context window overflow. Agents can write intermediate results, large data sets, or analysis to files, then reference them in subsequent steps. This enables handling of arbitrarily large contexts and complex multi-step workflows.

Subagent Delegation: The built-in task tool spawns specialized subagents for context isolation. The main agent maintains high-level coordination while subagents dive deep into specific subtasks without polluting the main conversation context.

Planning and Decomposition: The write_todos tool enables agents to create, track, and adapt plans dynamically. Plans persist across conversation turns and can be modified as new information emerges or requirements change.

Durable Execution: Built on LangGraph runtime, providing checkpointing, streaming responses, human approval gates, and error recovery. Agents can be interrupted, resumed, and scaled across distributed environments.

Key API surface

Function	Purpose
`create_deep_agent(tools, system_prompt, **kwargs)`	Main factory function for creating agents
`agent.invoke(input)`	Synchronous execution with input messages
`agent.stream(input)`	Streaming execution for real-time responses
`agent.ainvoke(input)`	Async execution for concurrent operations
`write_todos(todos: list)`	Built-in planning tool for task decomposition
`read_file(path: str)`	Built-in file reading for context management
`write_file(path: str, content: str)`	Built-in file writing for context storage
`edit_file(path: str, changes: str)`	Built-in file editing for incremental updates
`ls(path: str)`	Built-in directory listing for file exploration
`task(description: str, **kwargs)`	Built-in subagent spawning tool

Common patterns

Multi-step Analysis with Context Storage:

agent = create_deep_agent(
    tools=[analyze_data, fetch_report],
    system_prompt="Break complex analysis into steps, save intermediate results"
)

# Agent automatically uses write_file to store large datasets
# and read_file to reference them in subsequent steps

Delegated Subtask Execution:

def research_tool(query: str) -> str:
    # Custom research logic
    return research_results

agent = create_deep_agent(
    tools=[research_tool],
    system_prompt="Use the task tool to delegate specialized work to subagents"
)

# Agent uses built-in task() tool to spawn subagents for focused work

Planning-Driven Execution:

agent = create_deep_agent(
    tools=[code_analysis, documentation],
    system_prompt="Use write_todos to plan multi-step code reviews"
)

# Agent creates todo lists, tracks completion, adapts plans

Long-term Memory Integration:

from langgraph.store import MemoryStore

store = MemoryStore()
agent = create_deep_agent(
    tools=[custom_tools],
    store=store,  # Enables persistent memory across conversations
    system_prompt="Remember user preferences and project context"
)

Configuration

Option	Default	Purpose
`model`	`"gpt-4"`	LLM model for agent reasoning
`tools`	`[]`	Custom tools beyond built-ins
`system_prompt`	Basic assistant	Agent behavior and role definition
`store`	`None`	Memory store for long-term persistence
`checkpointer`	`None`	State persistence for durable execution
`recursion_limit`	`25`	Max steps before termination
`enable_file_tools`	`True`	Include file system tools
`enable_subagents`	`True`	Include task delegation tool
`sandbox_config`	`None`	Code execution environment settings

Best practices

Leverage Built-in Tools: Don't reimplement file operations or planning tools. The built-in write_todos, file tools, and task delegation are optimized for agent workflows and context management.

Design for Context Offloading: Structure prompts to encourage agents to save large results, intermediate data, and analysis to files rather than keeping everything in conversation context.

Use Subagents for Focus: Spawn subagents for specialized work (code analysis, data processing, research) to keep main agent context clean while enabling deep dives.

Plan Before Acting: Include instructions for agents to use write_todos for complex tasks. Plans help with step tracking and error recovery.

Configure Memory Appropriately: Use MemoryStore for user preferences and project context, but avoid storing sensitive data without proper security measures.

Set Reasonable Limits: Configure recursion_limit based on task complexity. Too low prevents complex work; too high risks infinite loops.

Handle File Paths Carefully: Agents will create files in the working directory. Consider sandboxing or path restrictions for production use.

Gotchas and common mistakes

File System Access: Agents have full file system access by default. In production, use sandboxes or restrict file operations to specific directories to prevent security issues.

Context Window Still Applies: While file tools help manage context, the agent still processes file contents within context limits. Very large files may still cause issues.

Subagent Recursion: Subagents can spawn their own subagents. Set recursion limits and monitor nesting depth to prevent runaway delegation.

Memory Store Persistence: Memory persists across sessions. Clear or manage memory appropriately to prevent stale context from affecting new conversations.

Tool Naming Conflicts: Built-in tools (read_file, write_file, etc.) will conflict with custom tools of the same name. Rename custom tools to avoid collisions.

Async Context Issues: When using ainvoke, ensure proper async context management, especially with file operations and subagent spawning.

Planning Tool Format: write_todos expects specific list format. Improper formatting may cause planning failures.

Checkpointer Configuration: Without proper checkpointer setup, agents lose state between invocations. Configure persistence for production use.

Model Capability Requirements: Complex planning and file management require capable models. Smaller or older models may struggle with built-in tools.

Streaming Interruptions: When streaming responses, file operations and subagent spawning may cause response delays or interruptions.

Path Resolution: File paths are resolved relative to execution context. Ensure consistent working directory for predictable file operations.