Deep Agents Core

• 任务规划：TodoListMiddleware 用于拆解复杂任务
• 上下文管理：带有可插拔后端的文件系统工具
• 任务委派：SubAgent 中间件用于生成专用子 Agent
• 长期记忆：通过 Store 实现跨线程的持久化存储
• 人机协同（Human-in-the-loop）：针对敏感操作的审批工作流
• 技能（Skills）：按需加载专用能力

Agent 运行环境（harness）会自动提供这些能力——你只需进行配置，无需自行实现。

from deepagents import create_deep_agent
from langchain.tools import tool

@tool
def get_weather(city: str) -> str:
    """获取指定城市的天气。"""
    return f"{city}的天气总是阳光明媚"

agent = create_deep_agent(
    model="claude-sonnet-4-5-20250929",
    tools=[get_weather],
    system_prompt="你是一个乐于助人的助手"
)

config = {"configurable": {"thread_id": "user-123"}}
result = agent.invoke({
    "messages": [{"role": "user", "content": "东京的天气怎么样？"}]
}, config=config)

import { createDeepAgent } from "deepagents";
import { tool } from "@langchain/core/tools";
import { z } from "zod";

const getWeather = tool(
  async ({ city }) => `${city}的天气总是阳光明媚`,
  { name: "get_weather", description: "获取指定城市的天气", schema: z.object({ city: z.string() }) }
);

const agent = await createDeepAgent({
  model: "claude-sonnet-4-5-20250929",
  tools: [getWeather],
  systemPrompt: "你是一个乐于助人的助手"
});

const config = { configurable: { thread_id: "user-123" } };
const result = await agent.invoke({
  messages: [{ role: "user", content: "东京的天气怎么样？" }]
}, config);

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="自定义指令",
    subagents=[research_agent, code_agent],
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    interrupt_on={"write_file": True},
    skills=["./skills/"],
    checkpointer=MemorySaver(),
    store=InMemoryStore()
)

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: "自定义指令",
  subagents: [researchAgent, codeAgent],
  backend: new FilesystemBackend({ rootDir: ".", virtualMode: true }),
  interruptOn: { write_file: true },
  skills: ["./skills/"],
  checkpointer: new MemorySaver(),
  store: new InMemoryStore()
});

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

SKILL.md 格式

目录结构

skills/
└── my-skill/
    ├── SKILL.md        # 必需：主技能文件
    ├── examples.py     # 可选：支持文件
    └── templates/      # 可选：模板

SKILL.md 格式

---
name: my-skill
description: 清晰、具体地描述该技能的功能
---

# 技能名称

## 概述
简要说明该技能的目的。

## 何时使用
该技能适用的条件。

## 说明指南
为 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": "使用 python-testing 技能"}]
}, config={"configurable": {"thread_id": "session-1"}})

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: "使用 python-testing 技能" }]
}, { configurable: { thread_id: "session-1" } });

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

# 将技能内容加载到 store 中
skill_content = """---
name: python-testing
description: 使用 pytest 进行 Python 测试的最佳实践
---
# 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 或文件系统工具的名称
• SKILL.md frontmatter 格式

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

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

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

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

# 错误
agent = create_deep_agent(backend=lambda rt: StoreBackend(rt))

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

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

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

# 错误：每次调用都是相互隔离的
agent.invoke({"messages": [{"role": "user", "content": "Hi"}]})
agent.invoke({"messages": [{"role": "user", "content": "What did I say?"}]})

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

// 错误：每次调用都是相互隔离的
await agent.invoke({ messages: [{ role: "user", content: "Hi" }] });
await agent.invoke({ messages: [{ role: "user", content: "What did I say?" }] });

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

# 错误：SKILL.md 中缺少 frontmatter
# My Skill
This is my skill...

# 正确：包含 YAML frontmatter
---
name: my-skill
description: 包含 pytest fixture 和 mock 的 Python 测试最佳实践
---
# My Skill
This is my skill...

# 错误：没有合适的后端，技能将无法加载
agent = create_deep_agent(skills=["./skills/"])

# 正确：本地技能使用 FilesystemBackend
agent = create_deep_agent(
    backend=FilesystemBackend(root_dir=".", virtual_mode=True),
    skills=["./skills/"]
)

# 错误：描述模糊
---
name: helper
description: 有用的技能
---

# 正确：描述具体
---
name: python-testing
description: 包含 pytest fixture、mock 和异步模式的 Python 测试最佳实践
---

# 错误：自定义子 Agent 不会继承技能
agent = create_deep_agent(
    skills=["/main-skills/"],
    subagents=[{"name": "helper", ...}]  # 没有技能
)

# 正确：显式提供技能
agent = create_deep_agent(
    skills=["/main-skills/"],
    subagents=[{"name": "helper", "skills": ["/helper-skills/"], ...}]
)