Deep Agents SDK 功能全清单：我逐行读了源码，整理出这份完整参考手册
前面几篇文章聊了 Deep Agents 是什么、架构怎么设计、CLI 怎么用。但我一直觉得差一篇真正"硬核"的——把 SDK 的每一个功能、每一个参数、每一个类型都列出来的参考手册。
所以我逐行读了 libs/deepagents/ 下所有源码，整理出这份清单。不管你是想快速查阅还是深度定制，这篇文章都是你的案头参考。
本文提纲
- 公共 API 导出清单
create_deep_agent完整参数- 内置工具清单（21 个）
- 中间件栈详解（11 个）
- 后端系统（8 种）
- Profile 系统
- 权限模型
- 子代理类型
- 模型解析和插件系统
公共 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人工智能时代
主页: https://www.theaiera.cn，每日分享最前沿的AI新闻和技术。
本文首发于 AI人工智能时代，转载请注明出处。
浙公网安备 33010602011771号