Python pydantic-deepagents 基于Pydantic AI的自托管终端AI编程代理

很多团队想要一个“自己的 Claude Code”，但又不希望把代码和上下文完全交给第三方云服务。开源方案要么太重、要么缺关键能力（工具调用、沙箱、多智能体协作）。pydantic-deepagents 给出了一个折中：它既是一个可自托管的终端 AI 助手（对标 Claude Code），也是支撑它的 Python 框架，跑在 Pydantic AI 之上，任何模型都能接。

项目基本信息

一、项目介绍

vstorm-co/pydantic-deepagents 提供两条使用路径。其一，开箱即用的终端助手 pydantic-deep：支持工具调用、沙箱执行、多智能体团队、skills、检查点（checkpoint）与近乎无限的上下文。其二，作为 Python 框架，你可以用几十行代码构建自己的 deep agent，复用它的代理调度、forking（分支探索）等能力。底层基于 Pydantic AI，天然兼容 OpenAI、Anthropic 等主流模型。

二、核心优势

1. 自托管可控：数据留在本地，不依赖特定厂商的云端 Coding Agent。
2. 分支探索（Live Run Forking）：同一任务并行尝试多种实现，由 AI 裁判按“质量+测试通过率+一致性”加权选择最优分支，这是它宣称的独有能力。
3. 测试驱动置信度：confidence = 质量差·0.4 + 测试通过率·0.4 + 内部一致性·0.2，把“agent 靠不靠谱”量化出来。
4. 沙箱与检查点：危险操作在沙箱执行，关键节点可回滚。
5. 任意模型：通过 model="anthropic:claude-sonnet-4-6" 这类字符串切换供应商。

三、适用场景

• 企业内部 Coding Agent：在隔离环境跑自动化重构、生成。
• 研究实验：用 forking 对比多种实现方案的优劣。
• 教学：用清晰置信度公式理解 agent 决策过程。
• 多智能体流水线：把不同子任务分给子 agent 协作。

四、安装教程

方式一，安装终端助手（macOS / Linux）：

curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deepagents/main/install.sh | bash
pydantic-deep

方式二，作为 Python 库安装：

pip install pydantic-deep

常见报错：curl 管道安装若报 Permission denied，先 chmod +x 后再运行；pip 安装若提示 Python 版本过低，需 3.10+。Windows 用户建议使用 WSL2 运行 install.sh。

五、使用示例

构建自己的 deep agent：

from pydantic_deep import create_deep_agent

agent = create_deep_agent(model="anthropic:claude-sonnet-4-6")
result = await agent.run("Build a REST API for auth")

启用分支探索：

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    forking=True,   # 赋予 agent：fork_run / inspect_branches / merge_or_select
)

真实运行输出（forking 调试视图节选）：

branch A: "use a decorator"       tests: 8/8 ✓  conf 0.71
branch B: "use a context manager" tests: 6/8 ✗  conf 0.42
branch C: "extract a base class"  tests: 8/8 ✓  conf 0.55
-> AI judge adopts branch A

可以看到 agent 在三个实现间做了实测对比，最终采纳测试全过且置信度最高的方案。

六、常见问题

Q：和官方 Claude Code 是什么关系？
A：它是开源自托管的对标实现，API 风格相似但可换模型、可本地运行。

Q：forking 很耗 token 吗？
A：会并行跑多分支，建议在明确收益的任务（如重构）上开启，简单任务用普通模式。

Q：支持 Docker 沙箱吗？
A：支持，docker-sandbox 是它的能力标签之一，危险命令可隔离执行。

七、总结

pydantic-deepagents 把“自托管 Coding Agent + 可复用框架”打包在一起，核心卖点是用测试反馈驱动的分支探索来提升可靠性。对重视数据主权、又想要 Claude Code 体验的团队，是目前少有的成熟开源选项，MIT 协议。