deepagents Documentation

1. Project Overview & Quickstart (langchain-ai/deepagents) Copy Chapter

File: README.md Copy Chapter

Deep Agents is an open source agent harness — an opinionated agent that runs out of the box. Extend, override, or replace any piece.

Principles:

• Opinionated — defaults tuned for long-horizon, multi-step work
• Extensible — override or replace any piece without forking
• Model-agnostic — works with any LLM that supports tool calling: frontier, open-weight, or local
• Production-ready — built on LangGraph (streaming, persistence, checkpointing) with first-class tracing, evaluation, and deployment via LangSmith

Features include:

• Sub-agents — delegate tasks to agents with isolated context windows
• Filesystem — read, write, edit, or search over pluggable local, sandboxed, or remote backends
• Context management — summarize long threads and offload tool outputs to disk
• Shell access — run commands in your sandbox of choice
• Persistent memory — pluggable state and store backends for cross-session recall
• Human-in-the-loop — approve, edit, or reject tool calls before they run
• Skills — reusable behaviors the agent can load on demand
• Tools — bring your own functions or any MCP server

Deep Agents is available as a JavaScript/TypeScript library — see deepagents.js.

[!NOTE]
Deep Agents Code — a pre-built coding agent in your terminal, similar to Claude Code or Cursor, powered by any LLM. Install with curl -LsSf https://langch.in/dcode | bash. See the documentation for the full feature set.

Quickstart Copy Chapter

uv add deepagents

from deepagents import create_deep_agent

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[my_custom_tool],
    system_prompt="You are a research assistant.",
)
result = agent.invoke({"messages": "Research LangGraph and write a summary"})

The agent can plan, read/write files, and manage its own context. Add your own tools, swap models, customize prompts, configure sub-agents, and more. See the documentation for full details.

[!TIP]
For developing, debugging, and deploying AI agents and LLM applications, see LangSmith.

FAQ Copy Chapter

How is this different from LangGraph or LangChain? Copy Section

LangGraph is the graph runtime. LangChain's create_agent is a minimal agent harness on top of it. Deep Agents is a more opinionated harness on top of create_agent — same building blocks, but with filesystem, sub-agents, context management, and skills bundled in. For how the three relate, see the LangChain ecosystem overview.

Does this work with open-weight or local models? Copy Section

Yes. Any model that supports tool calling works — frontier APIs (OpenAI, Anthropic, Google), open-weight models hosted on providers like Baseten or Fireworks, and self-hosted models via Ollama, vLLM, or llama.cpp. Use any LangChain chat model.

Can I use this in production? Copy Section

Yes! Deep Agents is built on LangGraph, designed for production agent deployments. Pair it with LangSmith for tracing, evaluation, and monitoring. See Going to production for the full guide.

When should I use Deep Agents vs. LangChain or LangGraph directly? Copy Section

All three are layers in the same stack — see the LangChain ecosystem overview for how they relate. Use Deep Agents when you want the full harness — planning, context management, delegation — out of the box. Use LangChain's create_agent when you want a lighter harness without the bundled middleware. Drop to LangGraph when the agent loop itself isn't the right shape and you need a custom graph.

The layers compose: any LangGraph CompiledStateGraph can be passed in as a sub-agent to a Deep Agent, so custom orchestration plugs in alongside the harness's defaults.

Resources Copy Chapter

• Examples — working agents and patterns
• Documentation — conceptual overviews and guides
• LangChain ecosystem overview — how Deep Agents, LangChain, LangGraph, and LangSmith fit together
• API reference — complete reference for all public classes, functions, and types
• Discussions — community forum for technical questions, ideas, and feedback
• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Contributing Guide — how to contribute and find good first issues
• Code of Conduct — community guidelines and standards

Acknowledgements Copy Chapter

Inspired by Claude Code: an attempt to identify what makes it general-purpose, and push that further.

Security Copy Chapter

Deep Agents follows a "trust the LLM" model. The agent can do anything its tools allow. Enforce boundaries at the tool/sandbox level, not by expecting the model to self-police. See the security policy for more information.

File: examples/content-builder-agent/README.md Copy Chapter

Content Builder Agent

A content writing agent for writing blog posts, LinkedIn posts, and tweets with cover images included.

This example demonstrates how to define an agent through three filesystem primitives:

• Memory (AGENTS.md) – persistent context like brand voice and style guidelines
• Skills (skills/*/SKILL.md) – workflows for specific tasks, loaded on demand
• Subagents (subagents.yaml) – specialized agents for delegated tasks like research

The content_writer.py script shows how to combine these into a working agent.

Quick Start Copy Chapter

# Set API keys
export ANTHROPIC_API_KEY="..."
export GOOGLE_API_KEY="..."      # For image generation
export TAVILY_API_KEY="..."      # For web search (optional)

# Run (uv automatically installs dependencies on first run)
cd examples/content-builder-agent
uv run python content_writer.py "Write a blog post about prompt engineering"

More examples:

uv run python content_writer.py "Create a LinkedIn post about AI agents"
uv run python content_writer.py "Write a Twitter thread about the future of coding"

How It Works Copy Chapter

The agent is configured by files on disk, not code:

content-builder-agent/
├── AGENTS.md                    # Brand voice & style guide
├── subagents.yaml               # Subagent definitions
├── skills/
│   ├── blog-post/
│   │   └── SKILL.md             # Blog writing workflow
│   └── social-media/
│       └── SKILL.md             # Social media workflow
└── content_writer.py            # Wires it together (includes tools)

What's in the skills? Each skill teaches the agent a specific workflow:

• Blog posts: Structure (hook → context → main content → CTA), SEO best practices, research-first approach
• Social media: Platform-specific formats (LinkedIn character limits, Twitter thread structure), hashtag usage
• Image generation: Detailed prompt engineering guides with examples for different content types (technical posts, announcements, thought leadership)

Architecture Copy Chapter

agent = create_deep_agent(
    memory=["./AGENTS.md"],                        # ← Middleware loads into system prompt
    skills=["./skills/"],                          # ← Middleware loads on demand
    tools=[generate_cover, generate_social_image], # ← Image generation tools
    subagents=load_subagents("./subagents.yaml"),  # ← See note below
    backend=FilesystemBackend(root_dir="./"),
)

The memory and skills parameters are handled natively by deepagents middleware. Tools are defined in the script and passed directly.

Note on subagents: Unlike memory and skills, subagents must be defined in code. We use a small load_subagents() helper to externalize config to YAML. You can also define them inline:

subagents=[
    {
        "name": "researcher",
        "description": "Research topics before writing...",
        "model": "anthropic:claude-haiku-4-5-20251001",
        "system_prompt": "You are a research assistant...",
        "tools": [web_search],
    }
],

Flow:

1. Agent receives task → loads relevant skill (blog-post or social-media)
2. Delegates research to researcher subagent → saves to research/
3. Writes content following skill workflow → saves to blogs/ or linkedin/
4. Generates cover image with Gemini → saves alongside content

Output Copy Chapter

blogs/
└── prompt-engineering/
    ├── post.md       # Blog content
    └── hero.png      # Generated cover image

linkedin/
└── ai-agents/
    ├── post.md       # Post content
    └── image.png     # Generated image

research/
└── prompt-engineering.md   # Research notes

Customizing Copy Chapter

Change the voice: Edit AGENTS.md to modify brand tone and style.

Add a content type: Create skills/<name>/SKILL.md with YAML frontmatter:

---
name: newsletter
---
# Newsletter Skill
...

Add a subagent: Add to subagents.yaml:

editor:
  model: anthropic:claude-haiku-4-5-20251001
  system_prompt: |
    You are an editor. Review the content and suggest improvements...
  tools: []

Add a tool: Define it in content_writer.py with the @tool decorator and add to tools=[].

Security Note Copy Chapter

This agent has filesystem access and can read, write, and delete files on your machine. Review generated content before publishing and avoid running in directories with sensitive data.

Requirements Copy Chapter

• Python 3.11+
• ANTHROPIC_API_KEY - For the main agent
• GOOGLE_API_KEY - For image generation (uses Gemini's Imagen / "nano banana" via gemini-2.5-flash-image)
• TAVILY_API_KEY - For web search (optional, research still works without it)

Resources Copy Chapter

• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Code of Conduct — community guidelines and standards

File: examples/deep_research/README.md Copy Chapter

🚀 Deep Research

🚀 Quickstart Copy Chapter

Prerequisites: Install uv package manager:

curl -LsSf https://astral.sh/uv/install.sh | sh

Ensure you are in the deep_research directory:

cd examples/deep_research

Install packages:

uv sync

Set your API keys in your environment:

export ANTHROPIC_API_KEY=your_anthropic_api_key_here  # Required for Claude model
export GOOGLE_API_KEY=your_google_api_key_here        # Required for Gemini model ([get one here](https://ai.google.dev/gemini-api/docs))
export TAVILY_API_KEY=your_tavily_api_key_here        # Required for web search ([get one here](https://www.tavily.com/)) with a generous free tier
export LANGSMITH_API_KEY=your_langsmith_api_key_here  # [LangSmith API key](https://smith.langchain.com/settings) (free to sign up)

Usage Options Copy Chapter

You can run this example in two ways:

Option 1: Jupyter Notebook Copy Section

Run the interactive notebook to step through the research agent:

uv run jupyter notebook research_agent.ipynb

Option 2: LangGraph Server Copy Section

Run a local LangGraph server with a web interface:

langgraph dev

LangGraph server will open a new browser window with the Studio interface, which you can submit your search query to:

You can also connect the LangGraph server to a UI specifically designed for deepagents:

git clone https://github.com/langchain-ai/deep-agents-ui.git
cd deep-agents-ui
yarn install
yarn dev

Then follow the instructions in the deep-agents-ui README to connect the UI to the running LangGraph server.

This provides a user-friendly chat interface and visualization of files in state.

📚 Resources Copy Chapter

• Deep Research Course - Full course on deep research with LangGraph
• Code of Conduct — community guidelines and standards

Custom Model Copy Section

By default, deepagents uses "claude-sonnet-4-5-20250929". You can customize this by passing any LangChain model object. See the Deep Agents package README for more details.

from langchain.chat_models import init_chat_model
from deepagents import create_deep_agent

# Using Claude
model = init_chat_model(model="anthropic:claude-sonnet-4-5-20250929", temperature=0.0)

# Using Gemini
from langchain_google_genai import ChatGoogleGenerativeAI
model = ChatGoogleGenerativeAI(model="gemini-3-pro-preview")

agent = create_deep_agent(
    model=model,
)

Custom Instructions Copy Section

The deep research agent uses custom instructions defined in research_agent/prompts.py that complement (rather than duplicate) the default middleware instructions. You can modify these in any way you want.

Custom Tools Copy Section

The deep research agent adds the following custom tools beyond the built-in deepagent tools. You can also use your own tools, including via MCP servers. See the Deep Agents package README for more details.

File: examples/downloading_agents/README.md Copy Chapter

Downloading Agents

Agents are just folders. This means you can share, download, and run them instantly.

Why This Works Copy Chapter

• Agents are folders — An agent is just an AGENTS.md file (memory/instructions) plus a skills/ directory. No code required.
• Single artifact — Package skills and memory together in one zip. Everything the agent needs to run.
• Run in seconds — Download, unzip, and run with deepagents-cli. No setup, no configuration.

Prerequisites Copy Chapter

uv tool install deepagents-cli==0.0.13

Quick Start Copy Chapter

# Create a project folder
mkdir my-project && cd my-project && git init

# Download the agent
curl -L https://raw.githubusercontent.com/langchain-ai/deepagents/main/examples/downloading_agents/content-writer.zip -o agent.zip

# Unzip to .deepagents
unzip agent.zip -d .deepagents

# Run it
deepagents

What's Inside Copy Chapter

.deepagents/
├── AGENTS.md                    # Agent memory & instructions
└── skills/
    ├── blog-post/SKILL.md       # Blog writing workflow
    └── social-media/SKILL.md    # LinkedIn/Twitter workflow

One-Liner Copy Chapter

git init && curl -L https://raw.githubusercontent.com/langchain-ai/deepagents/main/examples/downloading_agents/content-writer.zip -o agent.zip && unzip agent.zip -d .deepagents && rm agent.zip && deepagents

Resources Copy Chapter

• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Code of Conduct — community guidelines and standards

File: examples/ralph_mode/README.md Copy Chapter

Ralph Mode for Deep Agents

What is Ralph? Copy Chapter

Ralph is an autonomous looping pattern created by Geoff Huntley that went viral in late 2025. The original implementation is literally one line:

while :; do cat PROMPT.md | agent ; done

Each loop starts with fresh context—the simplest pattern for context management. No conversation history to manage, no token limits to worry about. Just start fresh every iteration.

The filesystem and git allow the agent to track progress over time. This serves as its memory and worklog.

Quick Start Copy Chapter

# Install uv (if you don't have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a virtual environment
uv venv
source .venv/bin/activate

# Install the CLI
uv pip install deepagents-cli

# Download the script (or copy from examples/ralph_mode/ if you have the repo)
curl -O https://raw.githubusercontent.com/langchain-ai/deepagents/main/examples/ralph_mode/ralph_mode.py

# Run Ralph
python ralph_mode.py "Build a Python programming course for beginners. Use git."

Usage Copy Chapter

# Unlimited iterations (Ctrl+C to stop)
python ralph_mode.py "Build a Python course"

# With iteration limit
python ralph_mode.py "Build a REST API" --iterations 5

# With specific model
python ralph_mode.py "Create a CLI tool" --model claude-sonnet-4-6

# With a specific working directory
python ralph_mode.py "Build a web app" --work-dir ./my-project

# Run in a remote sandbox (AgentCore, Modal, Daytona, or Runloop)
python ralph_mode.py "Build an app" --sandbox modal
python ralph_mode.py "Build an app" --sandbox daytona --sandbox-setup ./setup.sh

# Reuse an existing sandbox instance
python ralph_mode.py "Build an app" --sandbox modal --sandbox-id my-sandbox

# Auto-approve specific shell commands (or "recommended" for safe defaults)
python ralph_mode.py "Build an app" --shell-allow-list recommended
python ralph_mode.py "Build an app" --shell-allow-list "ls,cat,grep,pwd"

# Pass model parameters
python ralph_mode.py "Build an app" --model-params '{"temperature": 0.5}'

# Disable streaming output
python ralph_mode.py "Build an app" --no-stream

Remote sandboxes Copy Section

Ralph supports running agent code in isolated remote environments via the
--sandbox flag. The agent runs locally but executes all code operations in the
remote sandbox. See the
sandbox documentation
for provider setup (API keys, etc.) and the
sandboxes concept guide
for architecture details.

Supported providers: AgentCore, Modal, Daytona, Runloop.

How It Works Copy Chapter

1. You provide a task — declarative, what you want (not how)
2. Agent runs — creates files, makes progress
3. Loop repeats — same prompt, but files persist
4. You stop it — Ctrl+C when satisfied

Credits Copy Chapter

• Original Ralph concept by Geoff Huntley
• Brief History of Ralph by HumanLayer

Resources Copy Chapter

• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Code of Conduct — community guidelines and standards

File: examples/text-to-sql-agent/README.md Copy Chapter

Text-to-SQL Deep Agent

A natural language to SQL query agent powered by LangChain's Deep Agents framework. This is an advanced version of a text-to-SQL agent with planning, filesystem, and subagent capabilities.

What is Deep Agents? Copy Chapter

Deep Agents is a sophisticated agent framework built on LangGraph that provides:

• Planning capabilities - Break down complex tasks with write_todos tool
• Filesystem backend - Save and retrieve context with file operations
• Subagent spawning - Delegate specialized tasks to focused agents
• Context management - Prevent context window overflow on complex tasks

Demo Database Copy Chapter

Uses the Chinook database - a sample database representing a digital media store.

Quick Start Copy Chapter

Prerequisites Copy Section

• Python 3.11 or higher
• Anthropic API key (get one here)
• (Optional) LangSmith API key for tracing (sign up here)

Installation Copy Section

1. Clone the deepagents repository and navigate to this example:

git clone https://github.com/langchain-ai/deepagents.git
cd deepagents/examples/text-to-sql-agent

1. Download the Chinook database:

# Download the SQLite database file
curl -L -o chinook.db https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite

1. Create a virtual environment and install dependencies:

# Using uv (recommended)
uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

1. Set up your environment variables:

cp .env.example .env
# Edit .env and add your API keys

Required in .env:

ANTHROPIC_API_KEY=your_anthropic_api_key_here

Optional:

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_PROJECT=text2sql-deepagent

Usage Copy Chapter

Command Line Interface Copy Section

Run the agent from the command line with a natural language question:

python agent.py "What are the top 5 best-selling artists?"

python agent.py "Which employee generated the most revenue by country?"

python agent.py "How many customers are from Canada?"

Programmatic Usage Copy Section

You can also use the agent in your Python code:

from agent import create_sql_deep_agent

# Create the agent
agent = create_sql_deep_agent()

# Ask a question
result = agent.invoke({
    "messages": [{"role": "user", "content": "What are the top 5 best-selling artists?"}]
})

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

How the Deep Agent Works Copy Chapter

Architecture Copy Section

User Question
     ↓
Deep Agent (with planning)
     ├─ write_todos (plan the approach)
     ├─ SQL Tools
     │  ├─ list_tables
     │  ├─ get_schema
     │  ├─ query_checker
     │  └─ execute_query
     ├─ Filesystem Tools (optional)
     │  ├─ ls
     │  ├─ read_file
     │  ├─ write_file
     │  └─ edit_file
     └─ Subagent Spawning (optional)
     ↓
SQLite Database (Chinook)
     ↓
Formatted Answer

Configuration Copy Section

Deep Agents uses progressive disclosure with memory files and skills:

AGENTS.md (always loaded) - Contains:

• Agent identity and role
• Core principles and safety rules
• General guidelines
• Communication style

skills/ (loaded on-demand) - Specialized workflows:

• query-writing - How to write and execute SQL queries (simple and complex)
• schema-exploration - How to discover database structure and relationships

The agent sees skill descriptions in its context but only loads the full SKILL.md instructions when it determines which skill is needed for the current task. This progressive disclosure pattern keeps context efficient while providing deep expertise when needed.

Example Queries Copy Chapter

Simple Query Copy Section

"How many customers are from Canada?"

The agent will directly query and return the count.

Complex Query with Planning Copy Section

"Which employee generated the most revenue and from which countries?"

The agent will:

1. Use write_todos to plan the approach
2. Identify required tables (Employee, Invoice, Customer)
3. Plan the JOIN structure
4. Execute the query
5. Format results with analysis

Deep Agent Output Example Copy Chapter

The Deep Agent shows its reasoning process:

Question: Which employee generated the most revenue by country?

[Planning Step]
Using write_todos:
- [ ] List tables in database
- [ ] Examine Employee and Invoice schemas
- [ ] Plan multi-table JOIN query
- [ ] Execute and aggregate by employee and country
- [ ] Format results

[Execution Steps]
1. Listing tables...
2. Getting schema for: Employee, Invoice, InvoiceLine, Customer
3. Generating SQL query...
4. Executing query...
5. Formatting results...

[Final Answer]
Employee Jane Peacock (ID: 3) generated the most revenue...
Top countries: USA ($1000), Canada ($500)...

Project Structure Copy Chapter

text-to-sql-agent/
├── agent.py                      # Core Deep Agent implementation with CLI
├── AGENTS.md                     # Agent identity and general instructions (always loaded)
├── skills/                       # Specialized workflows (loaded on-demand)
│   ├── query-writing/
│   │   └── SKILL.md             # SQL query writing workflow
│   └── schema-exploration/
│       └── SKILL.md             # Database structure discovery workflow
├── chinook.db                    # Sample SQLite database (downloaded, gitignored)
├── pyproject.toml                # Project configuration and dependencies
├── uv.lock                       # Locked dependency versions
├── .env.example                  # Environment variable template
├── .gitignore                    # Git ignore rules
├── text-to-sql-langsmith-trace.png  # LangSmith trace example image
└── README.md                     # This file

LangSmith Integration Copy Chapter

Setup Copy Section

1. Sign up for a free account at LangSmith
2. Create an API key from your account settings
3. Add these variables to your .env file:

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_PROJECT=text2sql-deepagent

What You'll See Copy Section

When configured, every query is automatically traced:

You can view:

• Complete execution trace with all tool calls
• Planning steps (write_todos)
• Filesystem operations
• Token usage and costs
• Generated SQL queries
• Error messages and retry attempts

View your traces at: https://smith.langchain.com/

Resources Copy Chapter

• Deep Agents Documentation
• LangChain
• Claude Sonnet 4.5
• Chinook Database
• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Code of Conduct — community guidelines and standards

License Copy Chapter

MIT

Contributing Copy Chapter

Contributions are welcome! Please feel free to submit a Pull Request.

File: examples/README.md Copy Chapter

Examples

Featured Copy Chapter

| ### Deep Agents Code

A pre-built coding Deep Agent in your terminal — similar to Claude Code or Codex — powered by any LLM. Includes an interactive TUI, web search, remote sandboxes, persistent memory, custom skills, and human-in-the-loop approval.

curl -LsSf https://langch.in/dcode   bash

Source · Docs | ### Open SWE

An open-source, async coding agent for your org's internal workflows. Runs each task in an isolated cloud sandbox, integrates with Slack, Linear, and GitHub, and ships PRs end-to-end.

@open-swe fix this user-reported bug plz!

Repository · Blog post |
| --- | --- |

In the wild Copy Chapter

Production agents powered by the LangChain stack:

All examples Copy Chapter

Research Copy Section

Coding Copy Section

Content Copy Section

Deployable services Copy Section

Advanced patterns Copy Section

Each example has its own README with setup instructions.

Contributing an example

See the Contributing Guide for general contribution guidelines.

When adding a new example:

• Use uv for dependency management with a pyproject.toml and uv.lock (commit the lock file)
• Pin to deepagents version — use a version range (e.g., >=0.3.5,<0.4.0) in dependencies
• Include a README with clear setup and usage instructions
• Add tests for reusable utilities or non-trivial helper logic
• Keep it focused — each example should demonstrate one use-case or workflow
• Follow the structure of existing examples (see deep_research/ or text-to-sql-agent/ as references)

Resources Copy Chapter

• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Code of Conduct — community guidelines and standards

File: libs/partners/runloop/README.md Copy Chapter

langchain-runloop

Looking for the JS/TS version? Check out LangChain.js.

Quick Install Copy Chapter

uv add langchain-runloop

import os

from langchain_runloop import RunloopProvider

api_key = os.environ["RUNLOOP_API_KEY"]
provider = RunloopProvider(api_key=api_key)

sandbox = provider.get_or_create()
try:
    result = sandbox.execute("echo hello")
    print(result.output)
finally:
    provider.delete(sandbox_id=sandbox.id)

Boot from a named blueprint (create-if-missing, same idea as LangSmith snapshots):

sandbox = provider.get_or_create(snapshot="my-blueprint")

Or pin via env: RUNLOOP_SANDBOX_BLUEPRINT_NAME, RUNLOOP_SANDBOX_BLUEPRINT_ID
(ID wins; skips auto-build).

🤔 What is this? Copy Chapter

Runloop sandbox integration for Deep Agents.

📕 Releases & Versioning Copy Chapter

See our Releases and Versioning policies.

💁 Contributing Copy Chapter

As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.

For detailed information on how to contribute, see the Contributing Guide.

Resources Copy Chapter

• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Code of Conduct — community guidelines and standards

File: libs/partners/modal/README.md Copy Chapter

langchain-modal

Looking for the JS/TS version? Check out LangChain.js.

Quick Install Copy Chapter

uv add langchain-modal

import modal

from langchain_modal import ModalSandbox

sandbox = ModalSandbox(modal.Sandbox.create(app=modal.App.lookup("your-app")))
result = sandbox.execute("echo hello")
print(result.output)

🤔 What is this? Copy Chapter

Modal sandbox integration for Deep Agents.

📕 Releases & Versioning Copy Chapter

See our Releases and Versioning policies.

💁 Contributing Copy Chapter

As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.

For detailed information on how to contribute, see the Contributing Guide.

Resources Copy Chapter

• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Code of Conduct — community guidelines and standards

File: libs/partners/daytona/README.md Copy Chapter

langchain-daytona

Looking for the JS/TS version? Check out LangChain.js.

Quick Install Copy Chapter

uv add langchain-daytona

from daytona import Daytona

from langchain_daytona import DaytonaSandbox

sandbox = Daytona().create()
backend = DaytonaSandbox(
    sandbox=sandbox,
    timeout=300,
    sync_polling_interval=0.25,
)
result = backend.execute("echo hello")
print(result.output)

🤔 What is this? Copy Chapter

Daytona sandbox integration for Deep Agents.

📕 Releases & Versioning Copy Chapter

See our Releases and Versioning policies.

💁 Contributing Copy Chapter

As an open-source project in a rapidly developing field, we are extremely open to contributions, whether it be in the form of a new feature, improved infrastructure, or better documentation.

For detailed information on how to contribute, see the Contributing Guide.

Resources Copy Chapter

• LangChain Academy — Comprehensive, free courses on LangChain libraries and products, made by the LangChain team.
• Code of Conduct — community guidelines and standards

2. Official Technical Reference & Guides (langchain-ai/docs) Copy Chapter

LangChain Docs

🦜 Welcome! This repository contains the documentation build pipeline for LangChain projects.

• 🏠 docs.langchain.com is our docs home, centralizing LangChain, LangGraph, LangSmith, and LangChain Labs (Deep Agents, Open SWE, Open Agent Platform). This site is hosted on Mintlify.
• 🛠️ reference.langchain.com hosts generated API reference for LangChain, LangGraph, LangSmith, and integration packages. That site is not built from this repository (no reference build scripts or output live here).
  • Python reference
  • JavaScript/TypeScript reference
• 💬 chat.langchain.com is an AI-powered assistant that can answer questions about LangChain documentation.

Table of contents:

• LangChain Docs
  • Contribute
  • Reference
    • Repository structure
      • docs.langchain.com
      • reference.langchain.com
    • File formats
    • Available commands
  • Linting
    • Codespell
  • Troubleshooting
    • docs dev not working / running
    • Mintlify .venv parsing error
    • Warning: page doesn't exist
    • General Mintlify errors

Contribute Copy Chapter

To run a local preview of the documentation:

git clone https://github.com/langchain-ai/docs.git

cd docs

make install

make dev

For more information on how to contribute to LangChain documentation, follow the steps outlined in the contributing guide. The contributing guide also explains our documentation types and their writing and quality standards.

For detailed information about setting up your development environment and contributing to documentation, see the documentation contributing guide.

To report issues with reference.langchain.com (missing pages, broken links, or generated API content), open a reference documentation issue on this repo so maintainers can route it.

Reference Copy Chapter

Repository structure Copy Section

# --- docs.langchain.com ----------------------------------------------
build/                    # Built docs (DO NOT EDIT)
packages.yml              # Package metadata (indexes, tables, downloads; not the API reference build)
pipeline/                 # Build pipeline source code
scripts/                  # Helper scripts
src/                      # Source documentation files (< EDIT CONTENT HERE)
    langsmith/            # LangSmith docs
    oss/                  # LangChain, LangGraph, Deep Agents, and integrations docs
    docs.json             # Mintlify site configuration and navigation
tests/                    # Test files for the pipeline
Makefile                  # Build targets
pyproject.toml            # Dependencies

`docs.langchain.com`

The Mintlify docs pipeline is structured with .mdx source files in /src and build artifacts in /build. Mintlify deploys from the /build folder, which is generated by preprocessing logic.

[!IMPORTANT]
Never edit /build directly.

The /src/docs.json file is used to configure the Mintlify site navigation and settings. Refer to the Mintlify documentation for detailed syntax and component usage.

Documentation changes follow a PR workflow where all tests must pass before merging. See the contributing guidelines for more details.

`reference.langchain.com`

API reference is generated and deployed outside this repo. Browse Python and JavaScript/TypeScript reference there. If something is wrong with that site, use the reference docs issue template.

File formats Copy Section

• Markdown files (.md, .mdx) - Standard documentation content
• Snippets (src/snippets/) - Reusable MDX content that can be imported into multiple pages. Important: Snippets undergo special link preprocessing. When writing links in snippets, be careful about path segments.
• Jupyter notebooks (.ipynb) - Converted to markdown during build, though these are not recommended for new content! Your PR will likely be rejected if you attempt to add a Jupyter notebook unless asked to by a maintainer.
• Assets - Images and other files are copied to the build directory

Available commands Copy Section

Make commands:

• make dev - Start development mode with file watching and live rebuild
• make build - Build documentation to ./build directory
• make broken-links - Check for broken links in documentation
• make broken-links-with-anchors - Check for broken links + check links with anchors
• make install - Install all dependencies
• make clean - Remove build artifacts
• make test - Run the test suite
• make lint - Check code style and formatting
• make format - Auto-format code
• make lint_md - Lint markdown files
• make lint_md_fix - Lint and fix markdown files
• make help - Show all available commands

docs CLI tool:

The docs command (installed as uv run docs) provides additional functionality:

• docs migrate - Convert MkDocs markdown/notebook files to Mintlify format

  • --dry-run - Preview changes without writing files
  • --output - Specify output location (default: in-place)
  • Supports .md, .markdown, .ipynb files

• docs migrate-docusaurus - Convert Docusaurus markdown/notebook files to Mintlify format

  • --dry-run - Preview changes without writing files
  • --output - Specify output location (default: in-place)
  • Supports .md, .markdown, .mdx, .ipynb files
  • Converts Docusaurus-specific syntax (admonitions, tabs, imports, etc.)

• docs mv <old_path> <new_path> - Move files and update cross-references

  • --dry-run - Preview changes without moving files

These can be used directly using the Makefile or via the docs CLI tool:

• docs dev - Start development mode with file watching and hot reload

  • Automatically rebuilds changed files from src/ to build/
  • Launches Mintlify dev server at http://localhost:3000
  • Provides automatic browser refresh when files change
  • --skip-build - Skip initial build and use existing build directory

• docs build - Build documentation files

  • --watch - Watch for file changes after building

Linting Copy Chapter

After running make install, you can use make lint_prose to ensure your writing meets our style guide rules.

Codespell Copy Section

make lint runs uv run codespell src to check source documentation for common spelling errors.

Codespell is configured in pyproject.toml under [tool.codespell]:

• Add custom accepted words to src/.codespellignore. This file is referenced by ignore-words = "src/.codespellignore".
• Exclude generated files, vendor content, or other paths that should not be spell checked by adding glob patterns to the skip setting.
• Keep skip patterns scoped. Prefer adding accepted words to src/.codespellignore when the word is valid documentation content, and use skip when the file or directory should not be checked at all.

You can also follow these steps to enable vale with VS Code or Cursor:

1. Install the Vale extension (Vale by Chris Chinchilla)
2. Install Vale CLI: brew install vale (macOS) or see Vale installation for other platforms
3. Navigate to the Vale extension settings:
   • Set Vale CLI: Config to the absolute path to .vale.ini (in the root of this repo)
   • Set Vale CLI: Min Alert Level to suggestion (many rules are coded as suggestions)

If you cannot use the VS Code UI to configure Vale, add these settings to your settings.json:

"vale.valeCLI.config": "/path/to/docs/.vale.ini",
    "vale.valeCLI.minAlertLevel": "suggestion"

Note: The extension requires Vale on your PATH. If annotations don't appear (e.g., when Cursor is launched from the Dock), launch Cursor from a terminal so it inherits your PATH, or ensure Homebrew is in your shell profile.

Troubleshooting Copy Chapter

General Mintlify errors Copy Section

In some cases, we use new features that are only available in the latest Mintlify CLI. If you encounter errors, ensure you have the latest version installed:

mint update

# or

npm install mint

`docs dev` not working / running Copy Section

Re-do the steps to set up your dev environment, ensuring you have activated the virtual environment and installed all dependencies.

[!IMPORTANT]
Most of the time, mint update solves any docs dev / make dev issues!

Mintlify `.venv` parsing error Copy Section

Problem: Running mint broken-links or other Mintlify commands from the project root causes parsing errors like:

Unable to parse .venv/lib/python3.13/site-packages/soupsieve-2.7.dist-info/licenses/LICENSE.md
- 3:48: Unexpected character '@' (U+0040) in name

Root Cause: Mintlify tries to parse all files in the directory, including Python virtual environment files that contain invalid MDX syntax.

Solutions (in order of preference):

1. Use the safe Make commands (recommended):

   bash Copy

   make broken-links-with-anchors      # Builds docs first, then checks internal links

2. Run Mintlify commands from the build directory:

   bash Copy

   cd build               # Change to build directory where final docs are
   mint broken-links      # Now safe to run

Why this works: The solution ensures Mintlify commands run from the build/ directory where the final documentation is generated, which is the correct place to check for broken links. This avoids scanning the Python virtual environment in the project root.

Prevention: Always use the provided Make commands instead of running raw mint commands from the project root.

Warning: page doesn't exist Copy Section

If adding a new group, ensure the root index.mdx is included in the pages array like:

{
  "group": "New group",
  "pages": ["new-group/index", "new-group/other-page"]
}

If the trailing /index (no extension included) is omitted, the Mintlify parser will raise a warning even though the site will still build.