返回博客列表

Deep Agents SDK 功能全清单：我逐行读了源码，整理出这份完整参考手册

2026-05-13T23:10:00+08:00
Deep AgentsSDKAPI ReferenceLangChainAgent

前面几篇文章聊了 Deep Agents 是什么、架构怎么设计、CLI 怎么用。但我一直觉得差一篇真正"硬核"的——把 SDK 的每一个功能、每一个参数、每一个类型都列出来的参考手册。

所以我逐行读了 libs/deepagents/ 下所有源码，整理出这份清单。不管你是想快速查阅还是深度定制，这篇文章都是你的案头参考。

本文提纲

  1. 公共 API 导出清单
  2. create_deep_agent 完整参数
  3. 内置工具清单（21 个）
  4. 中间件栈详解（11 个）
  5. 后端系统（8 种）
  6. Profile 系统
  7. 权限模型
  8. 子代理类型
  9. 模型解析和插件系统

公共 API 导出清单

from deepagents import ... 能导出的所有东西：

导出项 类型 用途
create_deep_agent 函数 创建 Deep Agent 的唯一入口
FilesystemMiddleware 类 文件操作中间件
FilesystemPermission 类 文件权限规则
SubAgentMiddleware 类 同步子代理中间件
AsyncSubAgentMiddleware 类 异步子代理中间件
MemoryMiddleware 类 记忆中间件
SubAgent TypedDict 声明式同步子代理定义
CompiledSubAgent TypedDict 预编译子代理定义
AsyncSubAgent TypedDict 远程异步子代理定义
SubagentRunStream 类 同步子代理流句柄
AsyncSubagentRunStream 类 异步子代理流句柄
SubagentTransformer 类 子代理流转换器
HarnessProfile dataclass 运行时 harness 配置
HarnessProfileConfig dataclass 声明式（YAML/JSON）harness 配置
GeneralPurposeSubagentProfile dataclass 通用子代理配置
ProviderProfile dataclass 模型提供商配置
register_harness_profile 函数 注册 harness profile
register_provider_profile 函数 注册 provider profile
__version__ str 版本号

create_deep_agent 完整参数

def create_deep_agent(
    # ── 模型 ──
    model: str | BaseChatModel | None = None,

    # ── 工具 ──
    tools: Sequence[BaseTool | Callable | dict] | None = None,

    # ── 提示词 ──
    system_prompt: str | SystemMessage | None = None,

    # ── 中间件 ──
    middleware: Sequence[AgentMiddleware] = (),

    # ── 子代理 ──
    subagents: Sequence[SubAgent | CompiledSubAgent | AsyncSubAgent] | None = None,

    # ── 技能 ──
    skills: list[str] | None = None,

    # ── 记忆 ──
    memory: list[str] | None = None,

    # ── 权限 ──
    permissions: list[FilesystemPermission] | None = None,

    # ── 后端 ──
    backend: BackendProtocol | BackendFactory | None = None,

    # ── 人机协作 ──
    interrupt_on: dict[str, bool | InterruptOnConfig] | None = None,

    # ── 结构化输出 ──
    response_format: ResponseFormat | type | dict | None = None,

    # ── 上下文 ──
    context_schema: type[ContextT] | None = None,

    # ── 持久化 ──
    checkpointer: Checkpointer | None = None,
    store: BaseStore | None = None,

    # ── 其他 ──
    debug: bool = False,
    name: str | None = None,
    cache: BaseCache | None = None,
) -> CompiledStateGraph

返回值：编译好的 LangGraph StateGraph，支持 .invoke()、.stream()、.astream() 等所有 LangGraph 方法。

Prompt 组装顺序：USER → BASE/CUSTOM → SUFFIX（你的 system_prompt 永远在最前面）。

Recursion Limit：9999（几乎无限递归）。

内置工具清单（21 个）

文件操作工具（7 个，来自 FilesystemMiddleware）

工具 参数 说明
ls path: str 列出目录内容
read_file file_path: str, offset: int=0, limit: int=100 分页读取文件
write_file file_path: str, content: str 创建新文件
edit_file file_path: str, old_string: str, new_string: str, replace_all: bool=False 字符串替换编辑
glob pattern: str, path: str="/" 按模式匹配查找文件
grep pattern: str, path: str=None, glob: str=None, output_mode: str 搜索文件内容
execute command: str, timeout: int=None Shell 命令执行（仅沙箱后端）

规划工具（1 个，来自 TodoListMiddleware）

工具 参数 说明
write_todos （TodoList 操作） 任务分解和进度追踪

同步子代理工具（1 个，来自 SubAgentMiddleware）

工具 参数 说明
task description: str, subagent_type: str 启动同步子代理

异步子代理工具（5 个，来自 AsyncSubAgentMiddleware）

工具 参数 说明
start_async_task description: str, subagent_type: str 启动后台异步任务
check_async_task task_id: str 查询任务状态/结果
update_async_task task_id: str, message: str 向运行中的任务发送新指令
cancel_async_task task_id: str 取消运行中的任务
list_async_tasks status_filter: str=None 列出所有追踪的任务

上下文管理工具（1 个，来自 SummarizationToolMiddleware）

工具 参数 说明
compact_conversation （无参数） 手动触发对话压缩

中间件栈详解（11 个）

中间件按固定顺序执行，分为 Base Stack、User Zone、Tail Stack 三层。

Base Stack

1. TodoListMiddleware

  • 注入 write_todos 工具
  • 无配置参数

2. SkillsMiddleware（可选）

  • 注入技能系统的元数据
  • 配置：backend, sources: Sequence[SkillSource]
  • SkillSource = str | tuple[str, str]（路径或 (路径, 标签) 元组）

3. FilesystemMiddleware（不可排除）

  • 注入所有文件操作工具 + execute
  • 配置参数：
参数 类型 默认值 说明
backend BackendProtocol StateBackend() 后端实例
system_prompt str None 自定义系统提示词
custom_tool_descriptions Mapping[str, str] None 按工具名覆盖描述
tool_token_limit_before_evict int 20000 工具结果的 token 驱逐阈值
human_message_token_limit_before_evict int 50000 用户消息的 token 驱逐阈值
max_execute_timeout int 3600 单条命令最大超时（秒）
_permissions list[FilesystemPermission] None 权限规则（内部参数）

4. SubAgentMiddleware（不可排除，有子代理时激活）

  • 注入 task 工具
  • 配置：backend, subagents, system_prompt, task_description
  • task_description 支持 {available_agents} 占位符

5. AsyncSubAgentMiddleware（可选，有异步子代理时激活）

  • 注入 5 个异步任务工具
  • 配置：async_subagents, system_prompt

6. SummarizationMiddleware

  • 自动上下文压缩
  • 核心配置：
参数 类型 默认值 说明
model str/BaseChatModel （必需） 用于摘要的模型
backend BackendProtocol （必需） 后端实例
trigger ContextSize 自动计算 触发摘要的阈值
keep ContextSize 自动计算 保留多少上下文
token_counter Callable 近似计数 Token 计数函数
summary_prompt str 内置默认 摘要提示词
trim_tokens_to_summarize int 4000 截断待摘要内容的 token 数
truncate_args_settings dict 自动计算 参数截断配置

ContextSize 类型：tuple[Literal["tokens", "messages", "fraction"], int | float]

7. PatchToolCallsMiddleware

  • 修复悬挂的工具调用（用取消消息填充）
  • 无配置参数

User Zone

8. 用户自定义中间件

  • 你通过 middleware= 参数传入的中间件
  • 插在 Base Stack 和 Tail Stack 之间

Tail Stack

9. HarnessProfile extra_middleware

  • Profile 定义的额外中间件

10. _ToolExclusionMiddleware（内部）

  • 按 Profile 的 excluded_tools 过滤工具

11. AnthropicPromptCachingMiddleware

  • 无条件启用，非 Anthropic 模型自动 no-op

12. MemoryMiddleware（可选）

  • 注入 AGENTS.md 记忆到系统提示词
  • 配置：backend, sources: list[str], add_cache_control: bool

13. HumanInTheLoopMiddleware（可选）

  • 在指定工具调用前暂停等待人工审批
  • 配置：interrupt_on: dict[str, bool | InterruptOnConfig]

后端系统（8 种）

所有后端都实现 BackendProtocol 接口：

class BackendProtocol(abc.ABC):
    def ls(path) -> LsResult
    def read(file_path, offset, limit) -> ReadResult
    def write(file_path, content) -> WriteResult
    def edit(file_path, old_string, new_string, replace_all) -> EditResult
    def glob(pattern, path) -> GlobResult
    def grep(pattern, path, glob) -> GrepResult
    def upload_files(files) -> list[FileUploadResponse]
    def download_files(paths) -> list[FileDownloadResponse]
    # 以上全部有 async 版本 (als, aread, awrite, ...)

支持命令执行的后端额外实现 SandboxBackendProtocol：

class SandboxBackendProtocol(BackendProtocol):
    @property
    def id(self) -> str
    def execute(command, timeout) -> ExecuteResponse
    async def aexecute(command, timeout) -> ExecuteResponse

后端对比

后端 文件操作 命令执行 持久化 适用场景
StateBackend ✅ ❌ 内存 测试、简单场景（默认）
FilesystemBackend ✅ ❌ 本地磁盘 本地开发
LocalShellBackend ✅ ✅ 本地磁盘 完全信任的环境
StoreBackend ✅ ❌ 跨线程 需要持久化存储
CompositeBackend ✅ 可选 混合 路由分发
ContextHubBackend ✅ ❌ LangSmith Hub 知识库同步
LangSmithSandbox ✅ ✅ 远程 远程沙箱执行
Partner Sandboxes ✅ ✅ 远程 Daytona/Modal/Runloop

CompositeBackend 路由

backend = CompositeBackend(
    default=FilesystemBackend(root_dir="/workspace"),
    routes={
        "/data": StoreBackend(store=my_store),
        "/sandbox": DaytonaSandbox(),
    },
)

按路径前缀路由到不同后端，默认后端处理未匹配的路径。

Profile 系统

ProviderProfile（模型提供商配置）

@dataclass(frozen=True)
class ProviderProfile:
    init_kwargs: Mapping[str, Any]          # 传给 init_chat_model 的静态参数
    pre_init: Callable[[str], None] | None  # 初始化前的副作用
    init_kwargs_factory: Callable[[], dict] # 动态参数（运行时生成）

注册方式：

register_provider_profile("openai", ProviderProfile(init_kwargs={"use_responses_api": True}))
register_provider_profile("openai:gpt-5.4", ProviderProfile(init_kwargs={...}))

HarnessProfile（Agent 行为配置）

@dataclass(frozen=True)
class HarnessProfile:
    base_system_prompt: str | None = None           # 替换 SDK 默认 prompt
    system_prompt_suffix: str | None = None         # 追加到 prompt 末尾
    tool_description_overrides: Mapping[str, str]   # 按工具名覆盖描述
    excluded_tools: frozenset[str]                   # 排除的工具
    excluded_middleware: frozenset[type | str]       # 排除的中间件
    extra_middleware: Sequence | Callable            # 额外中间件
    general_purpose_subagent: GeneralPurposeSubagentProfile  # GP 子代理配置

GeneralPurposeSubagentProfile

@dataclass(frozen=True)
class GeneralPurposeSubagentProfile:
    enabled: bool | None = None       # None/True=启用, False=禁用
    description: str | None = None    # 覆盖 GP 子代理描述
    system_prompt: str | None = None  # 覆盖 GP 子代理系统提示词

内置 Profile

匹配 Key 特性
anthropic:claude-sonnet-4-6 并行工具调用、先调查后回答、工具结果反思
anthropic:claude-haiku-4-5 与 Sonnet 相同的通用 Claude 指导
anthropic:claude-opus-4-7 额外的工具使用引导 + 子代理使用指导
openai:gpt-5.*-codex Codex 行为：自主工程师、行动导向、并行工具、计划卫生

权限模型

FilesystemPermission

@dataclass
class FilesystemPermission:
    operations: list[Literal["read", "write"]]  # 覆盖的操作类型
    paths: list[str]                            # Glob 模式（必须以 "/" 开头）
    mode: Literal["allow", "deny"] = "allow"    # 允许或拒绝

工具到操作的映射

工具 操作类型
ls, read_file, glob, grep read
write_file, edit_file write

评估规则

  • 按声明顺序匹配，第一个命中生效
  • 未匹配的调用默认允许
  • 子代理继承父代理权限，除非指定自己的 permissions（完全覆盖）

示例

permissions=[
    # 只允许读取 /data 目录
    FilesystemPermission(operations=["read"], paths=["/data/*"], mode="allow"),
    # 禁止写入配置文件
    FilesystemPermission(operations=["write"], paths=["/etc/*"], mode="deny"),
    # 禁止读取密钥文件
    FilesystemPermission(operations=["read"], paths=["/secrets/*"], mode="deny"),
]

子代理类型

SubAgent（声明式同步子代理）

class SubAgent(TypedDict):
    name: str                          # 必需：唯一标识
    description: str                   # 必需：功能描述
    system_prompt: str                 # 必需：指令
    tools: NotRequired[Sequence[...]]  # 可选：默认继承主代理
    model: NotRequired[str | BaseChatModel]  # 可选：默认继承主代理
    middleware: NotRequired[list[...]] # 可选：额外中间件
    interrupt_on: NotRequired[dict]    # 可选：默认继承主代理
    skills: NotRequired[list[str]]     # 可选：技能路径
    permissions: NotRequired[list[...]]# 可选：默认继承主代理
    response_format: NotRequired[...]  # 可选：结构化输出

CompiledSubAgent（预编译子代理）

class CompiledSubAgent(TypedDict):
    name: str          # 必需
    description: str   # 必需
    runnable: Runnable  # 必需：预编译的 LangGraph 图（state 必须有 'messages'）

AsyncSubAgent（远程异步子代理）

class AsyncSubAgent(TypedDict):
    name: str                      # 必需
    description: str               # 必需
    graph_id: str                  # 必需：远程图名/助手 ID
    url: NotRequired[str]          # 可选：Agent Protocol 服务器 URL
    headers: NotRequired[dict]     # 可选：额外请求头

默认通用子代理

每个 Deep Agent 自动添加一个 general-purpose 子代理（除非 HarnessProfile 禁用）。它会：

  • 继承主代理的 tools、model、middleware、permissions
  • 有独立的上下文窗口
  • 用于委派通用子任务

模型解析和插件系统

模型解析

# 支持三种输入
create_deep_agent(model="openai:gpt-4o")            # provider:model 字符串
create_deep_agent(model=ChatAnthropic(model="..."))  # 预初始化模型实例
create_deep_agent(model=None)                        # 默认模型（已弃用）

插件系统

SDK 支持通过 importlib.metadata 入口点加载第三方插件：

入口点组 作用
deepagents.provider_profiles 自动注册 ProviderProfile
deepagents.harness_profiles 自动注册 HarnessProfile

内置 Profile 先加载，第三方插件通过加法合并语义叠加在上面。这意味着你可以：

  • 在不修改 SDK 的情况下注册新模型的适配
  • 通过 pip install 一个包就能让 Deep Agents 支持新的模型提供商
  • 用 YAML/JSON 声明式配置（HarnessProfileConfig）而不写 Python 代码

这份清单覆盖了 Deep Agents SDK 的每一个公共 API。如果你要基于它做开发，建议收藏本文。有任何遗漏或疑问，欢迎在评论区指出。

作者: itech001 来源: 公众号：AI人工智能时代(the-ai-era) 主页: https://www.theaiera.top 关注每日最新AI新闻和技术博客，主页有更多的文章的AI 技术参考：https://www.theaiera.top 本文首发于 AI人工智能时代，转载请注明出处。

分享给朋友
上一篇 · 2026-05-13
Deep Agents vs Claude Code vs Cursor：2026 年 AI 编程 Agent 终极对比
下一篇 · 2026-05-13
一个 Deep Agent 到底能干什么？从功能视角拆解它的全部能力

相关阅读

拆解 Deep Agents 架构：中间件、后端、Profile 三板斧，这设计比我想的还深

2026-05-13 Deep AgentsLangChainArchitecture

Deep Agents：LangChain 出品的 2026 年最强开源 Agent 框架，3 行代码搞定一切

2026-05-13 Deep AgentsLangChainAgent

用 Jev 和 LangGraph 构建生产级 Agent：LangChain 官方教程翻译

2026-09-26 JevLangGraphLangChain

Jev 能成为更好的 Agent 评估器吗？LangChain 用 LangSmith 做的实测翻译

2026-09-24 JevLangChainLangSmith