Pydantic-DeepAgents：基于 Pydantic-AI 的轻量级生产级 Agent 框架

DeepAgents的灵感源自 LangChain deepagents，但在设计上更做减法，它强调类型安全且内置了 Docker 沙箱

2025 年的Autonomous AI Agents早就不是实验室里的花架子了。在现实世界的自动化流程、代码生成工具、数据管道以及各类智能助手中都能看到它们的身影。

现在的很多主流 Agent 框架越来越重。为了用上 Agent，你往往得引入一堆沉重的依赖，面对复杂的图结构（Graphs），还得学完陡峭的学习曲线。想把这些东西真正部署到生产环境，确实挺折腾。

Vstorm 开发 Pydantic-DeepAgents 是一个极简但功能并不弱的开源框架，它的思路很清晰：在 Pydantic-AI 的基础上进行扩展，只提供构建可靠、生产级 Agent 真正需要的东西。

为什么还要造一个轮子？

其实这个项目的灵感直接来源于 LangChain 的 deepagents项目。那个项目对“Deep Agent”模式的实现——包括规划循环（Planning loops）、工具调用、子智能体委托（Subagent delegation）以及 Human-in-the-loop（人机协同）等等功能都设计得很好。

但与其说是重新造轮子，不如反问一个问题：如果完全在 Pydantic-AI 的生态里实现这些强大的模式，体验会不会更好？

所以Pydantic-DeepAgents 就来了：它是真的轻量级，没有引入 LangGraph 这种庞大的生态；反而充分利用了 Pydantic 原生的类型安全来做结构化输出；同时它把很多同类竞品缺失的生产级特性给补齐了。

核心能力拆解

这个框架在功能设计上很务实。

在规划与推理方面，它通过 TodoToolset 来实现自主的任务拆解和自我修正。对于文件系统的操作权限是完整的并且通过 FilesystemToolset 可以进行读写操作。如果遇到复杂的任务还支持通过 SubAgentToolset 将任务委托给专门的子智能体去处理。

特别值得一提的是它的技能系统，你只需要写简单的 Markdown 提示词就能定义新的 Agent 能力，这一点对于快速迭代原型非常友好。

在后端支持上除了内存和本地文件系统它还支持 DockerSandbox，这一点对于需要隔离执行代码的场景至关重要，而且它也支持混合后端（CompositeBackend）。

文件处理的流程也很顺滑，无论是通过 run_with_files() 还是 deps.upload_file() 都能无缝处理上传文件。对于长对话，它内置了上下文管理能自动进行摘要总结。

针对生产环境的交互需求，它内置了Human-in-the-loop 机制，关键操作可以配置人工确认工作流。支持逐 Token 的流式输出，方便构建响应迅速的前端 UI，基于 Pydantic 模型定义的 output_type 保证了输出的结构化和类型安全。

技术选型

官方仓库里直接给了一套全栈 Demo（FastAPI 后端 + 流式 Web UI）。跑起来能看到 Agent 的完整思考过程（Reasoning traces），包括文件上传处理、人工审批步骤以及流式响应的效果，代码本身很有参考价值。

什么情况下该考虑用它？

如果你受够了臃肿的框架，想要个干净、好维护的 Agent 架构，或者你对数据验证有强迫症，需要强类型的响应保证，那这个框架很适合。特别是它自带 Docker 沙箱在安全性上有天然优势。

对于原本就在用 Pydantic-AI 的开发者，或者需要 Agent 安全地操作文件和外部工具的场景，Pydantic-DeepAgents 基本就是无缝衔接的选择。

快速上手

安装非常简单：

 pip install pydantic-deep

总结

在 Agent 落地过程中，我们往往容易陷入过度设计的陷阱。Pydantic-DeepAgents 给出了答案：有时候严格的类型安全加上一个干净的 Docker 容器，远比一张错综复杂的有向无环图（DAG）要好维护得多。 如果你也认同这种“做减法”的工程美学，或者正苦于现有框架的臃肿，不妨试试这个方案。

https://github.com/vstorm-co/pydantic-deepagents

作者：Kacperwlodarczyk