Deep Agents (deepagents)

0.4.12 verified Tue May 12 auth: no python install: reviewed quickstart: stale

Agent harness by LangChain built on LangGraph. Implements planning (write_todos tool), filesystem backends, and subagent delegation — the architecture behind Claude Code, Manus, and Deep Research. Returns a compiled LangGraph StateGraph. Released mid-2025. Current version: 0.4.12 (Mar 2026). Default model is Claude Sonnet (not GPT-4o). Requires LangChain core libraries.

pip install deepagents

Common errors

error AttributeError: 'RunnableWithFallbacks' object has no attribute 'startswith' ↓

cause The `create_deep_agent` function, in version 0.4.12, expects the `model` parameter to be either a string identifier or an instance of `BaseChatModel`, but `RunnableWithFallbacks` (used for model fallbacks in LangChain) does not directly inherit from `BaseChatModel`, causing a string-specific check to fail.

fix

Ensure the model passed to create_deep_agent is a BaseChatModel or a string. If using fallbacks, you may need to wrap RunnableWithFallbacks in a custom BaseChatModel implementation or pass a string identifier for the primary model and handle fallbacks externally, or extend the resolve_model logic to explicitly handle RunnableWithFallbacks.

error ModuleNotFoundError: No module named 'deepagents_cli.execution' ↓

cause This error typically occurs when running older example scripts that rely on an internal or deprecated module path within the `deepagents-cli` package, which has likely been refactored or removed in newer versions.

fix

Update your deepagents-cli installation to the latest version. If the error persists with example code, check the official deepagents GitHub repository for the most current examples and their corresponding execution methods, as the deepagents_cli.execution module might no longer exist or be exposed directly.

error channel name 'file' already exists ↓

cause This error indicates that a communication channel, specifically named 'file', is being registered more than once with differing types, often due to duplicate tool or subagent initializations or registrations without proper namespacing.

fix

Review your tool and subagent registration code to ensure that each communication channel has a unique name. Implement checks to prevent re-registering channels or utilize namespacing for tools and subagents to avoid conflicts, especially when sharing tools between subagents.

error AttributeError: 'list' object has no attribute 'split' ↓

cause This error occurs within the `_parse_skill_metadata` function when the `allowed-tools` field in a `SKILL.md` file is provided as a list instead of an expected space-separated string.

fix

Ensure that the allowed-tools entry in your SKILL.md files is a single string with tool names separated by spaces, rather than a YAML list. For example, use allowed-tools: tool1 tool2 instead of allowed-tools: [tool1, tool2].

error ImportError: cannot import name 'CompiledSubAgents' from 'deepagents' ↓

cause This error suggests that the `CompiledSubAgents` class, or a similar component, is either no longer exported directly from the top-level `deepagents` package, has been renamed, or its import path has changed in a later version of the library.

fix

Consult the official deepagents documentation or API reference for the correct import path and name of the subagent compilation utility. If CompiledSubAgents has been removed or replaced, adapt your code to use the recommended alternative for compiling subagents, which might involve a different class or function from a more specific submodule.

Warnings

gotcha Default model is Claude Sonnet (anthropic), not GPT-4o. Requires ANTHROPIC_API_KEY if no custom model passed. Fails with AuthenticationError if key not set. ↓

fix Pass model= explicitly: create_deep_agent(model=init_chat_model('openai:gpt-4o')) to use OpenAI.

gotcha create_deep_agent returns a compiled LangGraph StateGraph — not a plain callable. Must invoke with {'messages': [...]} dict, not a plain string. ↓

fix agent.invoke({'messages': [{'role': 'user', 'content': 'your prompt'}]})

gotcha Result is a dict, not a string. Final answer is at result['messages'][-1].content. Agent may also create files accessible at result['files']. ↓

fix result['messages'][-1].content for text output. result.get('files', {}) for any files created.

gotcha Because it returns a LangGraph graph, it supports streaming, checkpointers, human-in-the-loop, and LangSmith tracing natively — but requires LangGraph-style usage patterns. ↓

fix Use agent.stream() for streaming. Pass checkpointer= for persistence. Set LANGSMITH_TRACING=true for tracing.

gotcha LLMs trained before mid-2025 have no knowledge of deepagents. Will hallucinate LangChain agent patterns or generic ReAct agents instead. ↓

fix Always use create_deep_agent() from deepagents — not langchain's create_react_agent or create_tool_calling_agent.

breaking The `deepagents` library requires Python 3.11 or higher. Installation will fail with a 'No matching distribution found' error on older Python versions. ↓

fix Upgrade your Python environment to 3.11 or newer to install `deepagents`.

breaking When using OpenAI models (e.g., 'openai:gpt-4o'), the OPENAI_API_KEY environment variable or `api_key` parameter must be set. Fails with openai.OpenAIError if not provided. ↓

fix Set the OPENAI_API_KEY environment variable or pass `api_key` to `init_chat_model` (e.g., `init_chat_model('openai:gpt-4o', api_key='your_key')`).

Install

pip install deepagents langchain-openai

Install compatibility reviewed last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - - -

3.10 slim (glibc) - - - -

3.11 alpine (musl) - - 5.39s 117.3M

3.11 alpine (musl) - - 5.39s 139.5M

3.11 slim (glibc) - - 4.55s 125M

3.11 slim (glibc) - - 4.59s 147M

3.12 alpine (musl) - - 4.89s 107.3M

3.12 alpine (musl) - - 4.89s 129.2M

3.12 slim (glibc) - - 4.91s 115M

3.12 slim (glibc) - - 4.89s 137M

3.13 alpine (musl) - - 4.47s 107.0M

3.13 alpine (musl) - - 4.48s 128.9M

3.13 slim (glibc) - - 4.56s 114M

3.13 slim (glibc) - - 4.67s 137M

3.9 alpine (musl) - - - -

3.9 slim (glibc) - - - -

Imports

create_deep_agent

wrong

from deepagents import create_deep_agent

agent = create_deep_agent()
result = agent.invoke('Research LangGraph')  # wrong — not a plain string

correct

from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

# Custom model
model = init_chat_model('openai:gpt-4o')
agent = create_deep_agent(
    model=model,
    tools=[],
    system_prompt='You are a research assistant.'
)

# invoke with messages dict — not plain string
result = agent.invoke({
    'messages': [{'role': 'user', 'content': 'Research LangGraph'}]
})
print(result['messages'][-1].content)

create_deep_agent returns a compiled LangGraph graph. invoke() takes a dict with 'messages' key, not a plain string. Response is also a dict — access result['messages'][-1].content for final answer.

Quickstart stale last tested: 2026-04-23

Minimal deepagents agent with OpenAI model.

# pip install deepagents langchain-openai
from deepagents import create_deep_agent
from langchain.chat_models import init_chat_model

model = init_chat_model('openai:gpt-4o')

agent = create_deep_agent(
    model=model,
    system_prompt='You are a helpful research assistant.'
)

result = agent.invoke({
    'messages': [{
        'role': 'user',
        'content': 'Write a short summary of what LangGraph is'
    }]
})

print(result['messages'][-1].content)