Guide · Open source
How to use deepagents: install, build an agent and tips
Updated · written with AI from the project's own documentation and checked against our catalogue data
Deep Agents is an open-source, MIT-licensed agent harness for Python that comes with planning, file access, sub-agents and context management already built in. This guide shows you how to add it to a uv project, create a basic agent, and decide where it fits. It is aimed at developers who want a working agent they can customize rather than building one from scratch.
Deep Agentslangchain-ai/deepagents · ★ 30.9k · MIT Install options & downloads Quick start
- 1Check prerequisites. Confirm you have Python and uv installed, and an API key or local model for the LLM you plan to use.
- 2Add deepagents to your project. Run uv add deepagents inside your uv project folder.
- 3Import create_deep_agent. Import create_deep_agent from the deepagents package in your Python file.
- 4Choose and configure a model. Pass a tool-calling model string to the model argument and set a system_prompt for the agent's role.
- 5Invoke the agent. Call agent.invoke with a messages input describing the task, then read the result.
- 6Customize as needed. Add your own tools, change prompts, or configure sub-agents to fit your task.
- 7Plan access controls. Enforce tool and sandbox boundaries, since the agent follows a trust-the-LLM model.
What Deep Agents includes
Deep Agents is described as an opinionated agent that runs out of the box and can be extended, overridden or replaced piece by piece. Its built-in features include sub-agents with isolated context windows, a filesystem for reading, writing, editing and searching, context management that summarizes long threads and offloads tool outputs to disk, and shell access in a sandbox of your choice.
It also supports persistent memory across sessions, human-in-the-loop approval of tool calls, reusable skills, and tools you supply yourself or from any MCP server. It is built on LangGraph.
- Sub-agents with isolated context windows
- Filesystem access over local, sandboxed or remote backends
- Context summarization and tool output offloading
- Human-in-the-loop approval, editing or rejection of tool calls
- Skills the agent loads on demand
- Bring your own tools or MCP servers
Install deepagents with uv
The README installs the library into a uv project. You need Python, which the README does not give a specific version for, and uv, the package manager used in its install command. Run the command from inside your project folder.
You also need an API key for the model provider you choose, or a local model. The README does not detail provider setup, so check the linked LangChain model documentation for that.
- Python (the README does not state a version)
- uv package manager
- An API key or a local model for your chosen LLM
uv add deepagentsCreate your first agent
The quickstart imports create_deep_agent and builds an agent with a model string and a system prompt. The model shown in the example is openai:gpt-6-astra; you can replace it with any tool-calling model. The agent is then called with invoke and a messages input.
The agent can plan, read and write files, and manage its own context. You can add your own tools, change models, customize prompts and configure sub-agents.
from deepagents import create_deep_agent
agent = create_deep_agent(
model="openai:gpt-6-astra",
system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})Choose a model: hosted or local
Deep Agents is model-agnostic. The README says it works with any LLM that supports tool calling, whether frontier, open-weight or local. The FAQ names OpenAI, Anthropic and Google APIs, open-weight models on providers such as Baseten or Fireworks, and self-hosted models through Ollama, vLLM or llama.cpp.
Any LangChain chat model can be used, so the same agent code can target hosted or self-hosted models.
- Hosted APIs: OpenAI, Anthropic, Google
- Open-weight hosts: Baseten, Fireworks
- Self-hosted: Ollama, vLLM, llama.cpp
Decide whether Deep Agents fits your project
Deep Agents sits on top of LangChain's create_agent, which sits on LangGraph. Use Deep Agents when you want planning, context management and delegation out of the box. Use create_agent for a lighter harness, or LangGraph directly when you need a custom graph.
Any LangGraph CompiledStateGraph can be passed in as a sub-agent, so custom orchestration can run alongside the defaults.
- Use Deep Agents for a full harness out of the box
- Use LangChain create_agent for a lighter harness
- Use LangGraph when the agent loop needs a custom graph
Keep tool access under control
The README describes a "trust the LLM" model: the agent can do anything its tools allow. It says boundaries should be enforced at the tool or sandbox level, not by expecting the model to police itself. Plan your tool permissions and sandbox setup before giving the agent real access.
Human-in-the-loop approval is one built-in option for reviewing tool calls before they run.
- Limit each tool to what the agent should be able to do
- Run shell access in a sandbox
- Use human-in-the-loop approval for sensitive calls
What people use it for
- Multi-step research tasks, such as researching a topic and writing a summary
- Long-running agents that delegate subtasks to sub-agents with separate context
- Agents that read, write and edit files as part of a workflow
- Running the same agent code against hosted or self-hosted models
Frequently asked questions
How do I install deepagents?
The README installs it into a uv project with uv add deepagents. You also need Python and an API key or local model for the LLM you pick.
Is deepagents free and open source?
Yes. The project is licensed under MIT, according to the README and its licence badge.
Does deepagents work with local models?
Yes, if the model supports tool calling. The FAQ names self-hosted options such as Ollama, vLLM and llama.cpp.
Is deepagents a finished app I can use without coding?
No. The README centers on writing Python code. The terminal coding agent called Deep Agents Code is a separate feature with its own install command.
How is deepagents different from LangGraph or LangChain?
LangGraph is the graph runtime and LangChain's create_agent is a minimal harness on top of it. Deep Agents is a more opinionated harness built on create_agent, with filesystem, sub-agents, context management and skills included.
Can I use deepagents in production?
The README says it is built on LangGraph and designed for production deployments, and recommends LangSmith for tracing, evaluation and monitoring. Read the linked going-to-production guide before you deploy.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Deep Agents suits Python developers building multi-step agents who want a customizable harness with planning, files and sub-agents already included. If you need a finished app, a simple single LLM call, or strict guarantees about tool misuse, pick a lighter option such as LangChain's create_agent, or build on LangGraph directly.
Install options & downloads