Deep Agents (deepagents)

0.4.12 · active · verified Tue Mar 24

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.

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.

Install

pip install deepagents Python (SDK)
pip install deepagents langchain-openai Python (SDK + OpenAI)

Imports

create_deep_agent

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

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)

view raw JSON →