Pydantic Deep Agents

从框架到终端 —— 打造具备规划、编码和交付能力的自主 AI Agent

文档 · PyPI · CLI · DeepResearch · 示例

---

无限上下文  •  子 Agent 委派  •  持久化内存  •  生命周期钩子 (Hooks)

---

与顶尖产品相同的架构

pydantic-deep 实现了深度 Agent 模式 (Deep Agent Pattern)，这也是支撑以下产品的核心架构：

	产品	构建内容
	Claude Code	Anthropic 的 AI 编码助手
	Manus AI	自主任务执行
	Devin	AI 软件工程师

现在你也可以构建同样的产品，或者直接使用 CLI。

灵感来源： LangChain 的 Deep Agents 关于自主 Agent 架构的研究。

---

pydantic-deep 包含三个核心部分：

1. Python 框架：用于构建具备规划、文件系统访问、子 Agent、记忆功能和无限上下文的 Claude Code 风格 Agent。
2. CLI：开箱即用的终端 AI 助手。
3. DeepResearch：功能齐全的研究型 Agent，包含 Web UI、网络搜索、图表生成及沙箱代码执行。

---

CLI —— 终端 AI 助手

pip install pydantic-deep[cli]
pydantic-deep chat

只需上述操作，你即可在终端获得一个交互式 AI Agent，具备：

• 文件读/写/编辑、Shell 执行、Glob、Grep 等功能
• 任务规划与子 Agent 委派
• 跨会话的持久化内存
• 用于无限对话的上下文压缩
• 感知 Git 状态的项目上下文
• 内置命令：/commit, /pr, /review, /test, /fix, /explain
• 可自定义的技能 (Skills)、钩子 (Hooks) 和输出风格

# 交互模式
pydantic-deep chat

# 执行单个任务
pydantic-deep run "Fix the failing tests in src/"

# 用于隔离执行的 Docker 沙箱
pydantic-deep run "Build a web scraper" --sandbox

# 选择模型
pydantic-deep chat --model anthropic:claude-sonnet-4-20250514

# 管理配置
pydantic-deep config set model openai:gpt-4.1

查看 CLI 文档 获取完整参考。

---

框架 —— 构建你自己的 Agent

pip install pydantic-deep

要求 pydantic-ai >= 1.71.0。

from pydantic_ai_backends import StateBackend
from pydantic_deep import create_deep_agent, create_default_deps

agent = create_deep_agent()
deps = create_default_deps(StateBackend())

result = await agent.run("Create a todo list for building a REST API", deps=deps)

只需一个函数调用，即可创建一个具备规划、文件系统工具、子 Agent、技能、上下文管理和成本追踪功能的 Agent。所有功能均可按需开启：

agent = create_deep_agent(
    model="openai:gpt-4.1",
    include_todo=True,          # 任务规划
    include_filesystem=True,    # 文件读/写/编辑/执行
    include_subagents=True,     # 委派任务给子 Agent
    include_skills=True,        # 来自 SKILL.md 文件的领域特定技能
    include_memory=True,        # 跨会话的持久化 MEMORY.md
    include_plan=True,          # 执行前的结构化规划
    include_teams=True,         # 带有共享 TODO 的多 Agent 团队
    include_web=True,           # 内置 WebSearch() 和 WebFetch() 能力
    context_manager=True,       # 自动摘要实现无限上下文
    cost_tracking=True,         # Token/USD 预算执行
    include_checkpoints=True,   # 保存、重置和分叉对话
)

结构化输出

from pydantic import BaseModel

class CodeReview(BaseModel):
    summary: str
    issues: list[str]
    score: int

agent = create_deep_agent(output_type=CodeReview)
result = await agent.run("Review the auth module", deps=deps)
print(result.output.score)  # 类型安全！

上下文管理

from pydantic_deep import create_summarization_processor

processor = create_summarization_processor(
    trigger=("tokens", 100000),
    keep=("messages", 20),
)
agent = create_deep_agent(history_processors=[processor])

钩子 (Claude Code 风格)

from pydantic_deep import Hook, HookEvent

agent = create_deep_agent(
    hooks=[
        Hook(
            event=HookEvent.PRE_TOOL_USE,
            command="echo 'Tool called: $TOOL_NAME' >> /tmp/audit.log",
        ),
    ],
)

成本追踪

agent = create_deep_agent(
    cost_tracking=True,
    cost_budget_usd=5.0,
    on_cost_update=lambda info: print(f"Cost: ${info.total_usd:.4f}"),
)

自定义子 Agent

agent = create_deep_agent(
    subagents=[
        {
            "name": "code-reviewer",
            "description": "Reviews code for quality issues",
            "instructions": "You are a senior code reviewer...",
            "preferred_mode": "sync",
        },
    ],
)

查看完整 API 参考