deepagents-setup-configuration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Deep Agents Setup and Configuration

Deep Agents 搭建与配置

Deep Agents are an agent harness on top of LangChain + LangGraph with built-in planning, filesystem context management, and subagent delegation.

Deep Agents是基于LangChain + LangGraph构建的Agent封装框架，内置规划、文件系统上下文管理和子代理委托功能。

Use This Skill When

适用场景

You need a Deep Agent quickly (Python or JavaScript).
You need subagents, filesystem-backed context, planning (
```
write_todos
```
), or long-term memory patterns.
You need migration guidance from older
```
create_react_agent
```
flows.
You need to scaffold a starter project with repository scripts.
You need to statically validate an
```
agent.py
```
/
```
agent.js
```
/
```
agent.ts
```
config.
You need safety checks before open-sourcing Deep Agents examples/templates.

你需要快速创建Deep Agent（支持Python或JavaScript）。
你需要子代理、基于文件系统的上下文、规划（
```
write_todos
```
）或长期记忆模式。
你需要从旧版
```
create_react_agent
```
流程迁移的指导。
你需要通过仓库脚本搭建初始项目框架。
你需要静态验证
```
agent.py
```
/
```
agent.js
```
/
```
agent.ts
```
配置文件。
你需要在开源Deep Agents示例/模板前进行安全检查。

Tooling In This Skill

本技能包含的工具

```
scripts/init_deep_agent_project.py
```
: scaffolds Python/JS projects with templates.
```
scripts/validate_deep_agent_config.py
```
: static checks for Deep Agent config quality.
```
references/deep-agents-reference.md
```
: detailed API, middleware, backends, migration, troubleshooting.
```
assets/templates/deep-agent-simple/
```
: minimal Python starter template.
```
assets/examples/basic-deep-agent/
```
: richer Python example.

```
scripts/init_deep_agent_project.py
```
：通过模板搭建Python/JS项目。
```
scripts/validate_deep_agent_config.py
```
：对Deep Agent配置进行静态质量检查。
```
references/deep-agents-reference.md
```
：详细的API、中间件、后端、迁移和故障排查文档。
```
assets/templates/deep-agent-simple/
```
：极简Python启动模板。
```
assets/examples/basic-deep-agent/
```
：功能更丰富的Python示例。

Recommended Workflow

Choose The Right Abstraction

选择合适的抽象方案

Need	Deep Agents	LangChain `create_agent`	LangGraph
Built-in planning/filesystem/subagents	✅ Best fit	⚠️ Manual middleware setup	❌ Manual graph design
Fast path for complex multi-step tasks	✅	⚠️	⚠️
Fully custom graph topology	❌	❌	✅ Best fit
Minimal/simple agent (1-3 steps)	⚠️ Overhead	✅ Best fit	⚠️

需求	Deep Agents	LangChain `create_agent`	LangGraph
内置规划/文件系统/子代理	✅ 最佳选择	⚠️ 需手动配置中间件	❌ 需手动设计图结构
复杂多步骤任务的快速实现路径	✅	⚠️	⚠️
完全自定义的图拓扑结构	❌	❌	✅ 最佳选择
轻量/简单Agent（1-3步任务）	⚠️ 存在冗余	✅ 最佳选择	⚠️

Initialize A Project

初始化项目

Use repo-local scripts and prefer

uv run

bash

undefined

使用仓库本地脚本，优先使用

uv run

执行。

bash

undefined

Python simple template

Python简单模板

uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language python --template simple --path skills/

Python with subagents

Python带代理模板

uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language python --template with-subagents --path skills/

Python CLI-config template (memory/checkpointer toggles)

Python CLI配置模板（支持记忆/检查点开关）

uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language python --template cli-config --path skills/

JavaScript template

JavaScript模板

uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language javascript --template simple --path skills/


Templates currently supported by the script:
- `simple`
- `with-subagents`
- `cli-config`

Generated outputs include:
- `agent.py` or `agent.js`
- `tools/example_tools.py` or `tools/example_tools.js`
- `.env.example`
- `README.md`
- `.gitignore`
- `pyproject.toml` (Python) or `package.json` (JavaScript)

uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language javascript --template simple --path skills/


当前脚本支持的模板：
- `simple`
- `with-subagents`
- `cli-config`

生成的输出文件包括：
- `agent.py`或`agent.js`
- `tools/example_tools.py`或`tools/example_tools.js`
- `.env.example`
- `README.md`
- `.gitignore`
- `pyproject.toml`（Python）或`package.json`（JavaScript）

Validate Agent Configuration

验证Agent配置

Run static validation before shipping examples/templates:

bash

uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.py
uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.js
uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.ts

Validator behavior:

Errors on missing agent calls or invalid file types.
Warns on risky/weak configs (missing prompt, odd backend usage, deprecated models).
Supports dynamic config patterns (
```
create_deep_agent(**kwargs)
```
,
```
createDeepAgent(config)
```
), with warning that some static checks are skipped.
Validates HITL style:
```
interrupt_on
```
/
```
interruptOn
```
should be mapping/object, and requires checkpointer.

在发布示例/模板前运行静态验证：

bash

uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.py
uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.js
uv run skills/deepagents-setup-configuration/scripts/validate_deep_agent_config.py path/to/agent.ts

验证器行为：

当缺少Agent调用或文件类型无效时抛出错误。
对风险/弱配置（缺少提示词、异常后端使用、已弃用模型）发出警告。
支持动态配置模式（
```
create_deep_agent(**kwargs)
```
、
```
createDeepAgent(config)
```
），但会警告部分静态检查将被跳过。
验证HITL风格：
```
interrupt_on
```
/
```
interruptOn
```
应为映射/对象，且需要检查点。

Current Deep Agents Defaults (Verified)

当前Deep Agents默认配置（已验证）

Default middleware includes:

```
TodoListMiddleware
```
```
FilesystemMiddleware
```
```
SubAgentMiddleware
```
```
SummarizationMiddleware
```
```
AnthropicPromptCachingMiddleware
```
```
PatchToolCallsMiddleware
```

Conditionally added middleware:

```
MemoryMiddleware
```
when
```
memory
```
is set
```
SkillsMiddleware
```
when
```
skills
```
is set

HumanInTheLoopMiddleware

when

interrupt_on

interruptOn

is set

默认中间件包括：

```
TodoListMiddleware
```
```
FilesystemMiddleware
```
```
SubAgentMiddleware
```
```
SummarizationMiddleware
```
```
AnthropicPromptCachingMiddleware
```
```
PatchToolCallsMiddleware
```

条件添加的中间件：

当设置
```
memory
```
时添加
```
MemoryMiddleware
```
当设置
```
skills
```
时添加
```
SkillsMiddleware
```

当设置

interrupt_on

interruptOn

时添加

HumanInTheLoopMiddleware

Core Configuration Patterns

核心配置模式

python

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",  # string or model object
    tools=[...],
    system_prompt="...",
    subagents=[...],          # optional delegation specialists
    middleware=[...],         # optional custom middleware
    store=store,              # needed for StoreBackend patterns
    backend=backend_factory,  # State/Store/Filesystem/Composite
    checkpointer=checkpointer # required for HITL interrupts
)

Backend guidance:

```
StateBackend
```
(default): thread-scoped, ephemeral.
```
StoreBackend
```
: persistent files via LangGraph store (requires
```
store=
```
).
```
CompositeBackend
```
: route prefixes (common
```
/memories/
```
->
```
StoreBackend
```
).
```
FilesystemBackend
```
: direct disk access; use carefully, prefer
```
virtual_mode=True
```
with
```
root_dir
```
.

python

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-5-20250929",  # 字符串或模型对象
    tools=[...],
    system_prompt="...",
    subagents=[...],          # 可选的委托专用子代理
    middleware=[...],         # 可选的自定义中间件
    store=store,              # StoreBackend模式所需
    backend=backend_factory,  # State/Store/Filesystem/Composite
    checkpointer=checkpointer # HITL中断所需
)

后端指导：

```
StateBackend
```
（默认）：线程作用域，临时存储。
```
StoreBackend
```
：通过LangGraph store实现持久化文件（需要
```
store=
```
参数）。
```
CompositeBackend
```
：路由前缀（常见
```
/memories/
```
->
```
StoreBackend
```
）。
```
FilesystemBackend
```
：直接磁盘访问；谨慎使用，优先启用
```
virtual_mode=True
```
并设置
```
root_dir
```
。

HITL And Persistence

HITL与持久化

If using human approval interrupts:

Python: use
```
interrupt_on={...}
```
JavaScript: use
```
interruptOn={...}
```
Always provide a checkpointer (
```
InMemorySaver
```
,
```
MemorySaver
```
, Sqlite/Postgres saver, etc.)

如果使用人工审核中断：

Python：使用
```
interrupt_on={...}
```
JavaScript：使用
```
interruptOn={...}
```
必须提供检查点（
```
InMemorySaver
```
、
```
MemorySaver
```
、Sqlite/Postgres存储等）

Migration Guidance

迁移指导

```
langgraph.prebuilt.create_react_agent
```
is deprecated in LangGraph v1.
For standard agents, prefer
```
langchain.agents.create_agent
```
.
For harness capabilities (planning/filesystem/subagents), use
```
deepagents.create_deep_agent
```
/
```
createDeepAgent
```
.

```
langgraph.prebuilt.create_react_agent
```
在LangGraph v1中已弃用。
对于标准Agent，优先使用
```
langchain.agents.create_agent
```
。
对于框架功能（规划/文件系统/子代理），使用
```
deepagents.create_deep_agent
```
/
```
createDeepAgent
```
。

Versioning Note

版本说明

```
deepagents
```
is currently a pre-1.0 package, so minor-version upgrades may include API changes.
Re-validate generated templates and examples when bumping
```
deepagents
```
versions.

```
deepagents
```
目前是1.0前的预发布包，小版本升级可能包含API变更。
升级
```
deepagents
```
版本时，需重新验证生成的模板和示例。

Open-Source Safety Checklist

开源安全检查清单

Before publishing this skill:

Ensure no real secrets are committed (
```
.env.example
```
must stay placeholder-only).
Remove generated artifacts like
```
__pycache__/
```
and
```
*.pyc
```
from skill folders.
Avoid absolute local paths in code/examples.
Keep provider credentials in environment variables only.
Re-run validator on all shipped
```
agent.py
```
/
```
agent.js
```
templates.

发布本技能前：

确保没有提交真实密钥（
```
.env.example
```
必须仅保留占位符）。
从技能文件夹中移除生成的产物如
```
__pycache__/
```
和
```
*.pyc
```
。
避免在代码/示例中使用绝对本地路径。
仅将服务商凭证存储在环境变量中。
对所有发布的
```
agent.py
```
/
```
agent.js
```
模板重新运行验证器。

Troubleshooting Quick Hits

故障排查速览

Model/tool-call errors: verify tool-calling model and provider credentials.
Files not persisting: confirm
```
StoreBackend
```
route +
```
store=
```
wiring.
HITL not interrupting: verify interrupt mapping/object and checkpointer.
Too much overhead for simple tasks: use
```
create_agent
```
or plain LangGraph.

模型/工具调用错误：验证支持工具调用的模型和服务商凭证。
文件未持久化：确认
```
StoreBackend
```
路由和
```
store=
```
参数的关联配置。
HITL未触发中断：验证中断映射/对象和检查点配置。
简单任务存在过多冗余：使用
```
create_agent
```
或原生LangGraph。

Resources

资源

```
references/deep-agents-reference.md
```
for detailed API and migration patterns.
```
assets/templates/deep-agent-simple/
```
for minimal template files.
```
assets/examples/basic-deep-agent/
```
for a fuller runnable example.
Python docs: https://docs.langchain.com/oss/python/deepagents/overview
JavaScript docs: https://docs.langchain.com/oss/javascript/deepagents/overview
LangGraph v1 migration: https://docs.langchain.com/oss/python/migrate/langgraph-v1

```
references/deep-agents-reference.md
```
：详细的API和迁移模式文档。
```
assets/templates/deep-agent-simple/
```
：极简模板文件。
```
assets/examples/basic-deep-agent/
```
：完整可运行示例。
Python文档：https://docs.langchain.com/oss/python/deepagents/overview
JavaScript文档：https://docs.langchain.com/oss/javascript/deepagents/overview
LangGraph v1迁移：https://docs.langchain.com/oss/python/migrate/langgraph-v1

deepagents-setup-configuration

Original

Translation

Deep Agents Setup and Configuration

Deep Agents 搭建与配置

Use This Skill When

适用场景

Tooling In This Skill

本技能包含的工具

Recommended Workflow

推荐工作流程

Choose The Right Abstraction

选择合适的抽象方案

Initialize A Project

初始化项目

Python simple template

Python简单模板

Python with subagents

Python带代理模板

Python CLI-config template (memory/checkpointer toggles)

Python CLI配置模板（支持记忆/检查点开关）

JavaScript template

JavaScript模板

Validate Agent Configuration

验证Agent配置

Current Deep Agents Defaults (Verified)

当前Deep Agents默认配置（已验证）

Core Configuration Patterns

核心配置模式

HITL And Persistence

HITL与持久化

Migration Guidance

迁移指导

Versioning Note

版本说明

Open-Source Safety Checklist

开源安全检查清单

Troubleshooting Quick Hits

故障排查速览

Resources

资源