deep-agents-core

Deep Agents 是基于 LangChain/LangGraph 构建的 Agent 框架，内置了多种中间件：

• 任务规划：TodoListMiddleware，用于拆解复杂任务
• 上下文管理：支持可插拔后端的文件系统工具
• 任务委派：SubAgent middleware，用于创建专用 Agent
• 长期记忆：通过 Store 在不同会话线程间持久存储
• 人工参与：针对敏感操作的审批工作流
• 技能：按需加载专用能力

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

适用场景：使用 Deep Agents	适用场景：使用 LangChain 的 create_agent
需要规划的多步骤任务	简单、用途单一的任务
上下文较大，需要管理文件	上下文可容纳在单个提示词中
需要专用子 Agent	单个 Agent 即可满足需求
需要跨会话持久记忆	临时的单会话任务

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

创建一个包含自定义工具的基础 deep agent，并通过用户消息调用它。

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)

创建一个包含自定义工具的基础 deep agent，并通过用户消息调用它。

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、技能和持久化。

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()
)

配置一个 deep agent，包含所有可用选项，包括子 Agent、技能和持久化。

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，以便按需加载技能。

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"}})

设置一个包含技能目录和文件系统后端的 Agent，以便按需加载技能。

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 后端，以供无法访问文件系统的环境使用。

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/"]
)

Agent 可以配置的内容

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

Agent 无法配置的内容

• 移除核心中间件（TodoList、Filesystem、SubAgent 始终存在）
• write_todos、task 或 filesystem 工具名称
• SKILL.md frontmatter 格式

中断需要 checkpointer。

# WRONG
agent = create_deep_agent(interrupt_on={"write_file": True})

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

中断需要 checkpointer。

// WRONG
const agent = await createDeepAgent({ interruptOn: { write_file: true } });

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

StoreBackend 需要一个 Store 实例，以便在不同线程间持久保存记忆。

# WRONG
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))

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

StoreBackend 需要一个 Store 实例，以便在不同线程间持久保存记忆。

// WRONG
const agent = await createDeepAgent({ backend: (config) => new StoreBackend(config) });

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

使用一致的 thread_id，以便在多次调用间保留对话上下文。

# 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，以便在多次调用间保留对话上下文。

// 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);

# 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 需要适当的后端，才能从文件系统加载。

# 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/"]
)

使用具体的描述，帮助 Agent 判断何时使用某项技能。

# 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 不会继承技能，因此请显式提供。

# 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/"], ...}]
)