pydantic-deepagents
vstorm-co/pydantic-deepagents加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
2024年底，Anthropic 推出 Claude Code，一款专为开发者设计的终端 AI 助手，能够自主完成代码编写、调试、Git 操作等复杂任务，迅速成为开发者社群的热议工具。然而，Claude Code 是闭源商业产品——模型调用需走 Anthropic API，数据流向不可控，且无法私有化部署。这让很多对数据隐私敏感的企业、有合规要求的团队望而却步。
正是在这样的背景下，Pydantic Deep Agents（项目内部名 pydantic-deep）应运而生。它由 Vstorm 团队开发，定位是"开源版 Claude Code，同时也是一个可以基于其构建自有 Agent 的 Python 框架"。项目在 GitHub 上获得了 1000+ stars，并被冠以"pydantic-co"组织的名义（与 Pydantic 官方无关但共享生态），展现出极强的社区吸引力。
Pydantic Deep Agents 的 CLI 是整个项目最直观的使用入口。它基于 Python 的 Textual 框架构建，呈现出一个功能完整的终端 UI（Textual User Interface），集成了以下能力：
/fork（创建分支会话）、/merge（合并）、/mcp（MCP 服务管理）、/improve（优化代码）、/compact（压缩上下文）、/diff（对比变更）、/model（切换模型）等@filename 直接引用本地文件让 AI 读取，!command 执行 Shell 命令
图：CLI TUI 界面演示（来源：项目官方仓库）
项目底层基于 Pydantic AI（v2+），因此天然支持所有兼容 OpenAI Chat Completions API 的模型，包括：
| 类别 | 代表模型 |
|---|---|
| OpenAI | GPT-4o、GPT-4o-mini |
| Anthropic | Claude 3.5/3.7 系列（本地运行 Claude Code 的关键） |
| OpenRouter | 聚合数十个模型的统一网关 |
| 本地模型 | Ollama、LM Studio 等 |
更重要的是，项目通过 Pydantic 的 output_type 参数实现类型安全的结构化输出——AI 的回复可以直接映射到 Python 的 Pydantic 模型，无需解析字符串，开发者体验极为丝滑。
Agent 在真实环境中执行命令有天然的风险。Pydantic Deep Agents 提供了两套安全机制：
rm -rf /）、路径穿越、密钥泄露等高危操作pydantic-ai-backend[docker] 插件，在隔离的 Docker 容器中执行工具命令，即使出问题也不会影响宿主机。apps/deepresearch 子应用完整展示了这一模式。# Docker 沙箱示例（来自项目 examples）
from pydantic_deep import Agent
agent = Agent(
model="claude-3-5-sonnet",
tools=["bash", "read_file", "write_file"],
sandbox=True # 启用 Docker 沙箱
)
MCP 是 Anthropic 主导的开放协议，用于让 AI Agent 连接各类外部数据源和工具。Pydantic Deep Agents 对 MCP 提供了完整支持：
项目支持子 Agent（Subagents）协作模式，可以创建一个主 Agent 协调多个专门化的子 Agent，每个子 Agent 负责特定任务（如代码审查、测试生成、文档编写），通过消息队列协调工作流。
项目自带一个完整的示例应用 DeepResearch，这是一个基于 AI 的深度研究助手，能够：
Pydantic Deep Agents 的源码组织高度模块化，核心源码在 pydantic_deep/ 目录下：
| 模块 | 功能 |
|---|---|
agent.py | Agent 核心类，封装工具调用、循环控制 |
subagents.py | 多智能体协作编排 |
goal.py | 目标管理与分解 |
mcp/ | MCP 协议客户端实现 |
features/ | 功能插件目录（按能力拆分） |
features/browser/ | 浏览器自动化（Playwright） |
features/checkpointing/ | 检查点存储与恢复 |
features/context/ | 上下文管理与压缩服务 |
features/forking/ | 分叉与隔离执行（Materializer + Judge 模式） |
features/improve/ | 代码优化分析与合成 |
features/memory/ | 长期记忆服务 |
features/skills/ | Skills 框架（Claude Code 技能扩展） |
features/teams/ | 多智能体团队原语 |
bundled_skills/ | 内置技能集（代码审查、测试生成、系统调试等） |
这种"特征即模块"（Feature as Module）的架构使得每个功能都可以独立使用或替换，降低了学习曲线的陡峭程度，也方便社区贡献者聚焦单个功能的改进。
pip install "pydantic-deep[cli]"
# 或一键安装脚本（支持 macOS/Linux）
curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deep/main/install.sh | bash
# 配置 API Key（支持 .env 文件）
export ANTHROPIC_API_KEY=sk-...
# 启动交互式 TUI
pydantic-deep
上手门槛极低，有 Python 3.10+ 环境即可。需要注意的是，所有模型调用均通过 API 进行，不自带模型，用户需自行准备 API Key（Anthropic、OpenAI 或其他兼容 provider）。
# apps/deepresearch 子应用
cd apps/deepresearch
# 取消 docker-compose.yml 中 Option B 的注释
docker-compose up
Docker 模式适合希望将整个研究助手服务化部署的团队，配合 API Key 配置即可运行。
Pydantic Deep Agents 并非没有短板，客观来看：
模型依赖外部 API：项目本身是 Agent 框架而非模型，这意味着所有推理能力都依赖第三方 API。如果 Anthropic/OpenAI 的 API 发生故障或涨价，用户将直接受影响。本地模型（如 Ollama）虽被支持，但能力和速度通常不及商业 API。
安全边界仍有争议：即使有 Docker 沙箱，Agent 执行任意代码的固有风险无法完全消除。在企业环境中使用可能需要额外的网络隔离和权限控制。
文档与维护状态：项目处于 Beta 阶段（版本 0.3.42），API 尚未完全稳定。文档质量尚可但不够详尽，部分高级功能的用法需要阅读源码或源码中的示例来理解。
与 Claude Code 的差距：虽然定位是"开源 Claude Code"，但 Claude Code 在任务规划、长程记忆、工具生态等方面已有深厚的积累。Pydantic Deep Agents 要达到同等水平还需要社区的持续投入。
Pydantic Deep Agents 的出现，代表了 AI Agent 开源生态的一个重要趋势：从"用商业工具"到"构建自己的 Agent"。它让开发者不仅能使用 Claude Code 式的体验，还能深入理解其内部机制，甚至基于它构建领域专用的 Agent 应用。
从增长曲线看，项目在发布后短时间内获得 1000+ stars，并持续更新（当前版本 0.3.x），显示出活跃的开发状态。Vstorm 团队还围绕 pydantic-deep 构建了一个小型生态，包括 full-stack-ai-agent-template、harbor 等相关项目，形成了从框架到应用的完整闭环。
对于 AI 开发者而言，Pydantic Deep Agents 是一个值得关注的框架——它将 Pydantic 的类型安全哲学引入 Agent 开发，使得构建复杂 AI 工作流变得可预测、可调试。对于 AI 爱好者，它提供了一个免费体验 Claude Code 式交互的入口，零成本探索 AI 编程的边界。
本报告基于 GitHub 仓库 vstorm-co/pydantic-deepagents (v0.3.42) 源码分析生成，数据截至 2026 年 8 月。