Skip to content

feat: add deep agents to labs #137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 10 commits into from
Aug 12, 2025
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 19 additions & 0 deletions src/docs.json
Original file line number Diff line number Diff line change
Expand Up @@ -327,6 +327,25 @@
"labs/index"
]
},
{
"tab": "Deep Agents",
"pages": [
{
"group": "Get started",
"pages": [
"labs/deep-agents/overview",
"labs/deep-agents/quickstart"
]
},
{
"group": "Configuration",
"pages": [
"labs/deep-agents/configuration-options",
"labs/deep-agents/built-in-components"
]
}
]
},
{
"tab": "Open SWE",
"pages": [
Expand Down
60 changes: 60 additions & 0 deletions src/labs/deep-agents/built-in-components.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,60 @@
---
title: Built-in components
---

Deep Agents comes with a number of built-in components that help agents perform complex tasks.

## System prompt

Deep Agents comes with a detailed system prompt heavily inspired by Claude Code's architecture. This prompt provides instructions for using the planning tool, file system tools, and sub agents effectively.

## Planning tool

A simple planning tool based on Claude Code's TodoWrite functionality that helps agents create and track plans in their context, keeping them on track for complex tasks.

## File system tools

Four built-in tools that mock a file system using LangGraph's state:

- `ls` - List files and directories
- `read_file` - Read file contents
- `write_file` - Write to files
- `edit_file` - Edit existing files

Files can be passed in and retrieved via the files key:

<CodeGroup>

```python Python
# Pass files to the agent
result = agent.invoke({
"messages": [...],
"files": {"foo.txt": "file content", ...}
})

# Access files after execution
updated_files = result["files"]
```

```typescript JavaScript
const result = await agent.invoke({
messages: [...],
// Pass in files to the agent using this key
files: {"foo.txt": "foo", ...}
});

// Access any files afterwards like this
result.files;
```

</CodeGroup>

## Sub-agents

Built-in support for calling specialized sub-agents with the following:

- **Context quarantine**: Prevents polluting the main agent's context
- **Custom instructions**: Tailored prompts for specific tasks
- **Tool access control**: Subagents can have different tool sets

A general-purpose sub-agent with the same instructions and tools as the main agent is always available.
92 changes: 92 additions & 0 deletions src/labs/deep-agents/configuration-options.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,92 @@
---
title: Configuration options
---

Deep Agents provides a number of configuration options to customize the agent's behavior and capabilities:

- **Tools** (required): The tools that the agent and any subagents will have access to.
- **Instructions** (required): Custom instructions that serve as part of the agent's prompt. This supplements the built-in system prompt.
- **Sub-agents**: Specialized subagents for specific tasks.
- **Model**: The model to use for the agent.

## Tools

Required. A list of tools that the agent and any subagents will have access to.

## Instructions

Required. Custom instructions that serve as part of the agent's prompt. This supplements the built-in system prompt.

## Sub-agents

Define specialized subagents for specific tasks:

<CodeGroup>

```python Python
subagents = [{
"name": "research-agent",
"description": "Used to research more in depth questions",
"prompt": sub_research_prompt,
"tools": ["internet_search"] # Optional: defaults to all tools
}]

agent = create_deep_agent(
tools=tools,
instructions=prompt,
subagents=subagents
)
```

```typescript JavaScript
interface SubAgent {
name: string;
description: string;
prompt: string;
tools?: string[];
}

const researchSubAgent: SubAgent = {
name: "research-agent",
description: "Used to research more in depth questions",
prompt: subResearchPrompt,
};

const agent = createDeepAgent({
tools,
instructions: prompt,
subagents: [researchSubAgent]
});
```

</CodeGroup>

## Model

Both the Python and JavaScript implementations default to `"claude-sonnet-4-20250514"` but support custom models:

<CodeGroup>

```python Python
from langchain_openai import ChatOpenAI

custom_model = ChatOpenAI(model="gpt-4")
agent = create_deep_agent(
tools=tools,
instructions=instructions,
model=custom_model
)
```

```typescript JavaScript
import { ChatOpenAI } from "@langchain/openai";

const customModel = new ChatOpenAI({ model: "gpt-4" });
const agent = createDeepAgent({
tools,
instructions,
model: customModel
});
```

</CodeGroup>
44 changes: 44 additions & 0 deletions src/labs/deep-agents/overview.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
---
title: Deep Agents
sidebarTitle: Overview
---

Using an LLM to call tools in a loop is the simplest form of an agent. This architecture, however, can yield agents that are "shallow" and fail to plan and act over longer, more complex tasks. Applications like "Deep Research", "Manus", and "Claude Code" have gotten around this limitation by implementing a combination of four things: a **planning tool**, **sub agents**, access to a **file system**, and a **detailed prompt**.

Deep Agents implements these components in a general purpose way so that you can easily create sophisticated agents for your application, available in both **Python** and **JavaScript/TypeScript**.

## Key features

- **Planning Tool**: Built-in planning capabilities to break down complex tasks and enable long-term planning.
- **Persistent state**: Memory between tool calls beyond conversation history.
- **Sub-agents**: Specialized agents for specific tasks with context quarantine.
- **Virtual File System**: Mock file system for persistent state without conflicts.
- **Detailed System Prompt**: Prompts, heavily inspired by Claude Code, leverage proven patterns.

Deep Agents implements the architectural patterns that make sophisticated agents like Claude Code effective.

## Installation

<CodeGroup>

```bash pip
pip install deepagents
```

```bash yarn
yarn add deepagents
```

```bash npm
npm install deepagents
```

</CodeGroup>

## Implementations

Deep Agents is available in both [**Python**](https://github.com/hwchase17/deepagents) and [**JavaScript**](https://www.npmjs.com/package/deepagents).

## Acknowledgements

This project was primarily inspired by Claude Code and is an attempt to better understand Claude Code and extend it.
68 changes: 68 additions & 0 deletions src/labs/deep-agents/quickstart.mdx
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
---
title: Quickstart
---

To create a research agent that can conduct thorough investigations:

<CodeGroup>

```python Python
from tavily import TavilyClient
from deepagents import create_deep_agent
import os

def internet_search(query):
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
return tavily_client.search(query)

research_instructions = """You are an expert researcher.
Your job is to conduct thorough research, and then write a polished report.

You have access to tools for internet search and file operations.
"""

agent = create_deep_agent(
tools=[internet_search],
instructions=research_instructions
)

result = agent.invoke({
"messages": [{"role": "user", "content": "what is langgraph?"}]
})
```

```typescript JavaScript
import { TavilySearch } from "@langchain/tavily";
import { createDeepAgent } from "deepagents";

// Search tool to use to do research
const internetSearch = new TavilySearch({
maxResults: 5,
tavilyApiKey: process.env.TAVILY_API_KEY,
});

// Prompt prefix to steer the agent to be an expert researcher
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research, and then write a polished report.

You have access to a few tools.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the number of results, the topic, and whether raw content should be included.
`;

// Create the agent
const agent = createDeepAgent({
tools: [internetSearch],
instructions: researchInstructions,
});

// Invoke the agent
const result = await agent.invoke({
messages: [{ role: "user", content: "what is langgraph?" }]
});
```

</CodeGroup>

The agent created with `createDeepAgent` is a LangGraph graph, so you can interact with it (streaming, human-in-the-loop, memory, studio) the same way you would any LangGraph agent.
21 changes: 16 additions & 5 deletions src/labs/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -8,15 +8,15 @@ description: LangChain Labs is a collection of agents and experimental AI produc

<Columns cols={2}>
<Card
title="Open Agent Platform"
icon="layer-group"
href="https://docs.oap.langchain.com/"
title="Deep Agents"
icon="brain"
href="/labs/deep-agents/overview"
arrow="true"
cta="Learn more"
>
Open Agent Platform is a citizen developer platform, allowing non-technical users to build, prototype, and use agents.
Create sophisticated AI agents that can plan, use subagents, and work with files for complex tasks.
</Card>

<Card
title="Open SWE"
icon="code"
Expand All @@ -27,4 +27,15 @@ description: LangChain Labs is a collection of agents and experimental AI produc
Open SWE is an open source cloud based coding agent.
</Card>

<Card
title="Open Agent Platform"
icon="layer-group"
href="https://docs.oap.langchain.com/"
arrow="true"
cta="Learn more"
>
Open Agent Platform is a citizen developer platform, allowing non-technical users to build, prototype, and use agents.
</Card>


</Columns>