cruldra/using-deepagents-sdk

using-deepagents-sdk

概述

deepagents 是 LangChain 官方的深度代理框架，核心入口是 create_deep_agent()。 它内置了规划工具、文件系统工具、子代理和上下文压缩，适合构建复杂的多步骤任务代理。

快速安装

uv add deepagents
# 或
pip install deepagents

需要设置模型 API Key，默认使用 Anthropic：

export ANTHROPIC_API_KEY=sk-...

最小可运行示例

from deepagents import create_deep_agent

# 默认使用 claude-sonnet-4-6，需要 ANTHROPIC_API_KEY
agent = create_deep_agent()

# 流式调用
for chunk in agent.stream({"messages": [{"role": "user", "content": "列出当前目录的文件"}]}):
    print(chunk)

create_deep_agent 核心参数速查

| 参数 | 类型 | 说明 | |------|------|------| | model | str \| BaseChatModel \| None | 模型，格式 "provider:model-name"，默认 claude-sonnet-4-6 | | tools | Sequence[BaseTool] | 额外工具，与内置工具合并 | | system_prompt | str \| SystemMessage | 自定义系统提示，追加在基础提示之前 | | subagents | Sequence[SubAgent \| CompiledSubAgent \| AsyncSubAgent] | 子代理列表 | | backend | BackendProtocol | 文件存储后端，默认 StateBackend() | | memory | list[str] | AGENTS.md 文件路径列表（注入系统提示） | | skills | list[str] | 技能目录路径列表（按需加载） | | permissions | list[FilesystemPermission] | 文件系统权限规则 | | middleware | Sequence[AgentMiddleware] | 自定义中间件 | | checkpointer | Checkpointer | 断点续跑，持久化对话状态 | | store | BaseStore | 跨线程共享存储 | | interrupt_on | dict[str, bool] | 指定工具调用前暂停，供人工审核 | | response_format | ResponseFormat | 结构化输出格式 |

Backend 选择

详细说明见 Backend 参考

需要执行 Shell 命令？
  ├─ 是，本地环境 → LocalShellBackend
  ├─ 是，云沙箱  → LangSmithSandbox
  └─ 否，只读写文件？
       ├─ 文件在磁盘  → FilesystemBackend(root_dir="/path")
       ├─ 文件在内存/请求中 → StateBackend（默认）
       ├─ 跨会话共享  → StoreBackend(store=..., namespace_factory=...)
       └─ 混合场景    → CompositeBackend([backend1, backend2])

from deepagents.backends import FilesystemBackend, LocalShellBackend, CompositeBackend

# 本地开发：文件系统 + Shell 执行
backend = CompositeBackend([
    FilesystemBackend(root_dir="/workspace"),
    LocalShellBackend(),
])

agent = create_deep_agent(backend=backend)

子代理（Subagents）

详细说明见 子代理参考

from deepagents import SubAgent, create_deep_agent

researcher: SubAgent = {
    "name": "researcher",
    "description": "负责网络搜索和信息收集，返回结构化研究报告",
    "system_prompt": "你是专业研究员，负责深度搜索并整理信息。",
    "tools": [search_tool],
    "model": "openai:gpt-4o",  # 可以用不同模型
}

agent = create_deep_agent(subagents=[researcher])

子代理类型：

• SubAgent：声明式，SDK 自动套标准中间件栈
• CompiledSubAgent：传入预编译的 LangGraph runnable
• AsyncSubAgent：远程后台运行（LangSmith Deployments）

Memory 与 Skills

详细说明见 Skills 与 Memory 参考

Memory（每轮全量注入系统提示，适合项目背景/规范）：

agent = create_deep_agent(
    memory=["/project/AGENTS.md"],
    backend=FilesystemBackend(root_dir="/"),
)

Skills（按需加载，适合工作流程/SOP）：

agent = create_deep_agent(
    skills=["/skills/base/", "/skills/project/"],
    backend=FilesystemBackend(root_dir="/"),
)

权限控制

详细说明见 Backend 参考 → FilesystemPermission

from deepagents import FilesystemPermission

agent = create_deep_agent(
    permissions=[
        # 先匹配先生效，第一条命中即止
        FilesystemPermission(operations=["write"], paths=["/workspace/**"], mode="allow"),
        FilesystemPermission(operations=["write"], paths=["/**"], mode="deny"),
    ]
)

Middleware

详细说明见 Middleware 参考

from langchain.agents.middleware.types import AgentMiddleware, ModelRequest, ModelResponse

class LoggingMiddleware(AgentMiddleware):
    def wrap_model_call(self, request, handler):
        response = handler(request)
        print(f"tokens: {response.response.usage_metadata}")
        return response

agent = create_deep_agent(middleware=[LoggingMiddleware()])

Store 与 Checkpointer

详细说明见 Store 与 Checkpointer 参考

from langgraph.checkpoint.memory import InMemorySaver

agent = create_deep_agent(checkpointer=InMemorySaver())

# 同一 thread_id 下跨请求续跑
config = {"configurable": {"thread_id": "conversation-001"}}
agent.invoke({"messages": [...]}, config=config)

常见错误

| 错误 | 原因 | 修复 | |------|------|------| | ANTHROPIC_API_KEY not set | 缺少 API Key | 设置环境变量 | | SubAgent must specify 'model' | SubAgent 缺少 model 字段 | 显式指定 "model": "..." | | execute tool returns error | StateBackend 不支持 Shell 执行 | 换用 LocalShellBackend | | File not found | FilesystemBackend root_dir 路径不对 | 检查 root_dir 是否正确 |

与 LangGraph 集成

create_deep_agent 返回 CompiledStateGraph，可直接用于 LangGraph Studio 或 LangSmith 部署：

# langgraph.json 中配置
{
  "graphs": {
    "agent": "agent.py:agent"
  }
}

参考资源

• 官方文档：https://docs.langchain.com/oss/python/deepagents/overview
• API 参考：https://reference.langchain.com/python/deepagents/