deepagents-setup-configuration

用途

Deep Agents 是构建在 LangChain + LangGraph 之上的智能体框架（agent harness），内置规划、文件系统上下文管理和子智能体委派能力。本技能用于在 Python 或 JavaScript 中初始化、验证和排查 Deep Agents 项目，使用 deepagents 包。

适用场景

需要快速构建 Deep Agent（Python 或 JavaScript）。
需要子智能体、文件系统支撑的上下文、规划（write_todos）或长期记忆模式。
需要从旧的 create_react_agent 流程迁移的指导。
需要用仓库脚本脚手架生成起步项目。
需要静态校验 agent.py / agent.js / agent.ts 配置。
需要在开源 Deep Agents 示例或模板前做安全检查。

本技能内含工具

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 示例。

抽象选型

需求	Deep Agents	LangChain create_agent	LangGraph
内置规划/文件系统/子智能体	✅ 最合适	⚠️ 需手动配置中间件	❌ 需手动设计图
复杂多步任务的快速路径	✅	⚠️	⚠️
完全自定义图拓扑	❌	❌	✅ 最合适
极简/简单智能体（1-3 步）	⚠️ 开销偏大	✅ 最合适	⚠️

初始化项目

使用仓库内脚本，优先使用 uv run。

# Python 简单模板
uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language python --template simple --path skills/

# 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 模板（memory/checkpointer 开关）
uv run skills/deepagents-setup-configuration/scripts/init_deep_agent_project.py my-agent --language python --template cli-config --path skills/

# 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）。

校验智能体配置

在交付示例/模板前运行静态校验：

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 应为映射/对象，并要求提供 checkpointer。

当前 Deep Agents 默认值（已核对）

默认中间件包括：

TodoListMiddleware
FilesystemMiddleware
SubAgentMiddleware
SummarizationMiddleware
AnthropicPromptCachingMiddleware
PatchToolCallsMiddleware

条件性添加的中间件：

设置 memory 时添加 MemoryMiddleware
设置 skills 时添加 SkillsMiddleware
设置 interrupt_on / interruptOn 时添加 HumanInTheLoopMiddleware

核心配置模式

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 与持久化

如果使用人工审批中断：

Python：使用 interrupt_on={...}
JavaScript：使用 interruptOn={...}
始终提供 checkpointer（InMemorySaver、MemorySaver、Sqlite/Postgres saver 等）

迁移指导

langgraph.prebuilt.create_react_agent 在 LangGraph v1 中已弃用。
标准智能体建议使用 langchain.agents.create_agent。
框架能力（规划/文件系统/子智能体）使用 deepagents.create_deep_agent / createDeepAgent。

版本说明

deepagents 目前是 pre-1.0 包，次版本升级可能包含 API 变更。升级 deepagents 版本时，需重新校验生成的模板和示例。

开源安全检查清单

在发布本技能前：

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

排查快查

模型/工具调用错误：检查支持工具调用的模型与提供商凭据。
文件不持久化：确认 StoreBackend 路由与 store= 接线。
HITL 未中断：检查 interrupt 映射/对象与 checkpointer。
简单任务开销过大：改用 create_agent 或纯 LangGraph。

资源

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

技能介绍

用途