deep-agents-core

Deep Agents 是基于 LangChain/LangGraph 构建的、带有鲜明设计理念的 Agent 框架，内置了以下中间件：

• 任务规划：通过 TodoListMiddleware 拆解复杂任务
• 上下文管理：使用可插拔后端的文件系统工具
• 任务委派：通过 SubAgent 中间件创建专用 Agent
• 长期记忆：通过 Store 在多个线程间持久化存储
• 人在回路：针对敏感操作的审批工作流
• 技能：按需加载专用能力

Agent 执行框架会自动提供这些能力，你只需配置，无需实现。

使用 Deep Agents 的场景	使用 LangChain 的 create_agent 的场景
需要规划的多步骤任务	简单、单一用途的任务
需要通过文件管理大型上下文	上下文可放入单个提示词
需要专用子 Agent	单个 Agent 即可胜任
需要跨会话持久化记忆	临时的单会话工作

如果你需要……	中间件	说明
跟踪复杂任务	TodoListMiddleware	默认启用
管理文件上下文	FilesystemMiddleware	配置后端
委派工作	SubAgentMiddleware	添加自定义子 Agent
添加人工审批	HumanInTheLoopMiddleware	需要 checkpointer
加载技能	SkillsMiddleware	提供技能目录
访问记忆	MemoryMiddleware	需要 Store 实例

创建一个带自定义工具的基础 Deep Agent，并通过用户消息调用它。 ```python from deepagents import create_deep_agent from langchain.tools import tool

@tool def get_weather(city: str) -> str: """Get the weather for a given city.""" return f"It is always sunny in {city}"

agent = create_deep_agent( model="claude-sonnet-4-5-20250929", tools=[get_weather], system_prompt="You are a helpful assistant" )

config = {"configurable": {"thread_id": "user-123"}} result = agent.invoke({ "messages": [{"role": "user", "content": "What's the weather in Tokyo?"}] }, config=config)

</python>
<typescript>
创建一个带自定义工具的基础 Deep Agent，并通过用户消息调用它。
```typescript
import { createDeepAgent } from "deepagents";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async ({ city }) => `It is always sunny in ${city}`,
  { name: "get_weather", description: "Get weather for a city", schema: z.object({ city: z.string() }) }
);

const agent = await createDeepAgent({
  model: "claude-sonnet-4-5-20250929",
  tools: [getWeather],
  systemPrompt: "You are a helpful assistant"
});

const config = { configurable: { thread_id: "user-123" } };
const result = await agent.invoke({
  messages: [{ role: "user", content: "What's the weather in Tokyo?" }]
}, config);

配置一个 Deep Agent，并使用所有可用选项，包括子 Agent、技能和持久化。 ```python from deepagents import create_deep_agent from deepagents.backends import FilesystemBackend from langgraph.checkpoint.memory import MemorySaver from langgraph.store.memory import InMemoryStore

agent = create_deep_agent( name="my-assistant", model="claude-sonnet-4-5-20250929", tools=[custom_tool1, custom_tool2], system_prompt="Custom instructions", subagents=[research_agent, code_agent], backend=FilesystemBackend(root_dir=".", virtual_mode=True), interrupt_on={"write_file": True}, skills=["./skills/"], checkpointer=MemorySaver(), store=InMemoryStore() )

</python>
<typescript>
配置一个 Deep Agent，并使用所有可用选项，包括子 Agent、技能和持久化。
```typescript
import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver, InMemoryStore } from "@langchain/langgraph";

const agent = await createDeepAgent({
  name: "my-assistant",
  model: "claude-sonnet-4-5-20250929",
  tools: [customTool1, customTool2],
  systemPrompt: "Custom instructions",
  subagents: [researchAgent, codeAgent],
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  interruptOn: { write_file: true },
  skills: ["./skills/"],
  checkpointer: new MemorySaver(),
  store: new InMemoryStore()
});

每个 Deep Agent 均可使用以下工具：

1. 规划：write_todos - 跟踪多步骤任务
2. 文件系统：ls、read_file、write_file、edit_file、glob、grep
3. 委派：task - 创建专用子 Agent

---

SKILL.md 格式

技能采用**渐进式披露**机制——Agent 只会在内容相关时加载内容。

目录结构

skills/
└── my-skill/
    ├── SKILL.md        # Required: main skill file
    ├── examples.py     # Optional: supporting files
    └── templates/      # Optional: templates

SKILL.md 格式

---
name: my-skill
description: Clear, specific description of what this skill does
---

# Skill Name

## Overview
Brief explanation of the skill's purpose.

## When to Use
Conditions when this skill applies.

## Instructions
Step-by-step guidance for the agent.

技能	记忆（AGENTS.md）
按需加载	启动时始终加载
特定任务的指令	通用偏好
大型文档	精简上下文
各目录中的 SKILL.md	单个 AGENTS.md 文件

配置一个包含技能目录和文件系统后端的 Agent，以便按需加载技能。 ```python from deepagents import create_deep_agent from deepagents.backends import FilesystemBackend from langgraph.checkpoint.memory import MemorySaver

agent = create_deep_agent( backend=FilesystemBackend(root_dir=".", virtual_mode=True), skills=["./skills/"], checkpointer=MemorySaver() )

result = agent.invoke({ "messages": [{"role": "user", "content": "Use the python-testing skill"}] }, config={"configurable": {"thread_id": "session-1"}})

</python>
<typescript>
配置一个包含技能目录和文件系统后端的 Agent，以便按需加载技能。
```typescript
import { createDeepAgent, FilesystemBackend } from "deepagents";
import { MemorySaver } from "@langchain/langgraph";

const agent = await createDeepAgent({
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  skills: ["./skills/"],
  checkpointer: new MemorySaver()
});

const result = await agent.invoke({
  messages: [{ role: "user", content: "Use the python-testing skill" }]
}, { configurable: { thread_id: "session-1" } });

将技能内容加载到 Store 后端，以便在无法访问文件系统的环境中使用。 ```python from deepagents import create_deep_agent from deepagents.backends import StoreBackend from deepagents.backends.utils import create_file_data from langgraph.store.memory import InMemoryStore

store = InMemoryStore()

Load skill content into store

skill_content = """--- name: python-testing description: Best practices for Python testing with pytest

Python Testing Skill

..."""

store.put( namespace=("filesystem",), key="/skills/python-testing/SKILL.md", value=create_file_data(skill_content) )

agent = create_deep_agent( backend=lambda rt: StoreBackend(rt), store=store, skills=["/skills/"] )

</python>
</ex-skills-with-store-backend>

<boundaries>
### Agent 可以配置的内容

- 模型选择和参数
- 其他自定义工具
- 系统提示词自定义
- 后端存储策略
- 需要审批的工具
- 配备专用工具的自定义子 Agent

</source>
### Agent 无法配置的内容

- 移除核心中间件（TodoList、Filesystem、SubAgent 始终存在）
- write_todos、task 或 filesystem 工具名称
- SKILL.md 前置元数据格式
</boundaries>

<fix-checkpointer-for-interrupts>
<python>
中断需要检查点保存器。
```python
# WRONG
agent = create_deep_agent(interrupt_on={"write_file": True})

# CORRECT
agent = create_deep_agent(interrupt_on={"write_file": True}, checkpointer=MemorySaver())

中断需要检查点保存器。 ```typescript // WRONG const agent = await createDeepAgent({ interruptOn: { write_file: true } });

// CORRECT const agent = await createDeepAgent({ interruptOn: { write_file: true }, checkpointer: new MemorySaver() });

</typescript>
</fix-checkpointer-for-interrupts>

<fix-store-for-memory>
<python>
StoreBackend 需要 Store 实例，才能在多个线程间持久保存记忆。
```python
# WRONG
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))

# CORRECT
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt), store=InMemoryStore())

StoreBackend 需要 Store 实例，才能在多个线程间持久保存记忆。 ```typescript // WRONG const agent = await createDeepAgent({ backend: (config) => new StoreBackend(config) });

// CORRECT const agent = await createDeepAgent({ backend: (config) => new StoreBackend(config), store: new InMemoryStore() });

</typescript>
</fix-store-for-memory>

<fix-thread-id-for-conversations>
<python>
使用一致的 thread_id，在多次调用间保留对话上下文。
```python
# WRONG: Each invocation is isolated
agent.invoke({"messages": [{"role": "user", "content": "Hi"}]})
agent.invoke({"messages": [{"role": "user", "content": "What did I say?"}]})

# CORRECT
config = {"configurable": {"thread_id": "user-123"}}
agent.invoke({"messages": [...]}, config=config)
agent.invoke({"messages": [...]}, config=config)

使用一致的 thread_id，在多次调用间保留对话上下文。 ```typescript // WRONG: Each invocation is isolated await agent.invoke({ messages: [{ role: "user", content: "Hi" }] }); await agent.invoke({ messages: [{ role: "user", content: "What did I say?" }] });

// CORRECT const config = { configurable: { thread_id: "user-123" } }; await agent.invoke({ messages: [...] }, config); await agent.invoke({ messages: [...] }, config);

</typescript>
</fix-thread-id-for-conversations>

<fix-frontmatter-required>
```markdown
# WRONG: Missing frontmatter in SKILL.md
# My Skill
This is my skill...

# CORRECT: Include YAML frontmatter
---
name: my-skill
description: Python testing best practices with pytest fixtures and mocking
---
# My Skill
This is my skill...

Skills 需要合适的后端，才能从文件系统加载。 ```python # WRONG: Skills won't load without proper backend agent = create_deep_agent(skills=["./skills/"])

CORRECT: Use FilesystemBackend for local skills

agent = create_deep_agent( backend=FilesystemBackend(root_dir=".", virtual_mode=True), skills=["./skills/"] )

</python>
</fix-backend-for-skills>

<fix-specific-skill-descriptions>
使用具体的描述，帮助 Agent 判断何时使用某项 skill。
```markdown
# WRONG: Vague description
---
name: helper
description: Helpful skill
---

# CORRECT: Specific description
---
name: python-testing
description: Python testing best practices with pytest fixtures, mocking, and async patterns
---

子 Agent 不会继承 Skills，请明确提供。 ```python # WRONG: Custom subagents don't inherit skills agent = create_deep_agent( skills=["/main-skills/"], subagents=[{"name": "helper", ...}] # No skills )

CORRECT: Provide skills explicitly

agent = create_deep_agent( skills=["/main-skills/"], subagents=[{"name": "helper", "skills": ["/helper-skills/"], ...}] )

</python>
</fix-subagent-skills>