Pydantic Deep Agents
用任意支持工具调用的模型构建或运行自托管终端智能体。
- Star 数
- ★ 1.1k
- 最近更新
- 1 个月前
- License
- MIT
- 主语言
- Python
- FA 评分
- 68/100 · 存在缺口
30 秒速览
- 运行形态
- 可在哪里用
- 通用 · 跨平台OpenAI API · Claude APIClaude Code（部分支持）
- 费用
- 软件免费，模型调用费用自付
- 上手难度
- 低 · 几分钟可跑通
- 开始前需要
- 典型场景
- 需要在本机终端让编码助手读取、修改项目文件并执行测试的 Python 团队。
- 不适合
- 不愿为并行分支承担额外模型调用费用的团队
- 需要官方生产部署拓扑与长期支持承诺的企业
- 源码审查
- 68/100 · 存在缺口
这个 Agent 能做什么，适合哪些场景？
Pydantic Deep Agents 同时提供终端 TUI 助手和 Python 智能体框架，底层基于 Pydantic AI。命令行可交互运行，也可通过 pydantic-deep run 用于脚本、基准测试或 CI/CD；库侧则通过 create_deep_agent() 创建可运行的智能体。它可配置文件与 Shell 工具、任务规划、子智能体、团队协作、记忆、上下文压缩、检查点、MCP、成本控制和结构化输出。执行可使用本地或 Docker 后端，Docker 模式支持命名工作区，项目目录挂载到 /workspace。其 Live Run Forking 会把同一运行分成隔离分支，并通过人工选择、自动判定、自动回退或投票合并结果。
通过 create_deep_agent() 创建的实例接收任务后，可调用 ls、read_file、write_file、edit_file、glob、grep 和 execute 操作工作区；可选接入网页搜索、网页抓取和 Playwright 浏览器自动化。它可用 include_todo、include_plan、include_subagents 与 include_teams 组织任务和委派，MEMORY.md 可作为持久记忆，context_manager 可在上下文接近预算时进行摘要或滑动窗口压缩。forking=True 会提供 fork_run、inspect_branches、merge_or_select、terminate_branch、diff_branches 和 fork_cost；分支使用 copy-on-write BranchOverlay，并可通过 LiveForkCapability(test_command="pytest -q") 把测试退出码纳入决策。结果既可在 Textual TUI 中以流式对话、工具调用和差异展示，也可通过 output_type 返回 Pydantic 类型的结果，或用 pydantic-deep run --json 供自动化消费。
- 需要在本机终端让编码助手读取、修改项目文件并执行测试的 Python 团队。
- 要在 CI/CD 或脚本中运行“修复 test_auth.py 中失败测试”这类任务的工程负责人。
- 希望用 create_deep_agent() 为内部开发工具加入文件、Shell、规划和预算控制能力的 Python 开发者。
- 需要把多个实现方案分别运行 pytest -q，再选择通过率与质量更高分支的重构团队。
- 需要让研究、代码审查等并行子智能体通过共享 TODO 和消息总线协作的应用开发者。
- 需要通过 MCP 接入 GitHub、Figma、Context7、DeepWiki 或自定义服务的工程团队。
如何安装或部署这个 Agent？
macOS 或 Linux 可运行：curl -fsSL https://raw.githubusercontent.com/vstorm-co/pydantic-deep/main/install.sh | bash。Windows 或手动安装可运行：pip install "pydantic-deep[cli]"；仅使用框架则运行：pip install pydantic-deep。README 标明 Python 版本要求为 3.10+。使用 Anthropic 示例模型前，设置凭据：export ANTHROPIC_API_KEY=sk-ant-...。
如何使用这个 Agent？
启动交互终端：pydantic-deep。指定模型可用：pydantic-deep tui --model openrouter:anthropic/claude-opus-4-6。无交互执行可用：pydantic-deep run "Fix the failing test in test_auth.py"，需要 JSON 输出时加入 --json。Python 中可写：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")。Docker 沙箱使用 pydantic-deep tui --sandbox docker；浏览器自动化需安装 pydantic-deep[browser] 后使用 pydantic-deep tui --browser。
这个 Agent 有哪些优点和局限？
- 同一项目同时提供可直接使用的终端 TUI、无交互 runner 和 create_deep_agent() 库接口，适合从个人终端工作流延伸到自定义应用。
- Live Run Forking 提供隔离的 copy-on-write 分支、分支预算、测试命令钩子及四种合并模式，可用于比较可验证的实现方案。
- 基于 Pydantic AI，并明确列出 Anthropic、OpenAI、OpenRouter、Gemini、Ollama 与 OpenAI 兼容端点的模型路径。
- output_type 可返回 Pydantic 模型，避免调用方自行解析 JSON；同时提供 token/USD 跟踪和预算限制。
- Docker 命名工作区、MCP、生命周期钩子和 default_security_hook() 覆盖了受控执行与外部工具连接需求。
- 核心能力依赖支持工具调用的模型；模型 API、网络访问及对应凭据由部署者负责配置。
- README 仅明确给出 Python 3.10+；Docker 沙箱和 Playwright 浏览器自动化分别需要 Docker 与浏览器额外依赖。
- Live Run Forking 会并行运行分支并设置每分支预算，采用前需评估额外的模型调用与测试执行成本。
- 默认安全钩子可阻止破坏性 Shell 命令、路径遍历和密钥泄露，但其具体策略与组织安全要求的匹配程度需要自行验证。
- README 提供安装与使用示例，但未在所给材料中说明生产部署拓扑、长期支持政策或各提供商认证配置的完整矩阵。
这个 Agent 与同类方案有什么区别？
README 将其与 Claude Code、Aider、LangGraph 和 CrewAI 对比，并将自身定位为同时具备终端助手、Python 框架、模型选择和 Live Run Forking 的方案。Claude Code 已有终端体验与 MCP，但 README 将分支运行和 Python 框架列为 Pydantic Deep 的差异；LangGraph 与 CrewAI 更偏框架使用。应以所需的 TUI、分支合并和 Pydantic AI 集成为主要选择标准，而非将表中跨项目能力标记视为独立验证。
与相关度最高的同类 agent 并排比较关键指标。
| Agent | 源码审查 | 形态 / 费用 | Star | 最近更新 | 主语言 | 完整支持的平台 |
|---|---|---|---|---|---|---|
| Pydantic Deep Agents 当前 | 68 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 1.1k | 1 个月前 | Python | OpenAI API · Claude API |
| Marvin – Python AI 开发框架 | 45 · 缺口较多 | 代码库 / SDK免费 + 模型费 | ★ 6.2k | 9 天前 | Python | OpenAI API |
| 从原型到生产的生成式AI代理实战指南 | 证据不足 | 代码库 / SDK免费 + 模型费 | ★ 22k | 4 天前 | Jupyter Notebook | — |
| gptme Terminal Agent | 66 · 存在缺口 | 命令行工具免费 + 模型费 | ★ 4.5k | 今天 | Python | OpenAI API · Claude API |
FollowAgents 如何评估这个 Agent？
查看各维度的扣分理由
证据显示：提供工具审批对话框（approve/auto-approve/deny），默认安全钩子阻止破坏性命令，Docker沙箱隔离执行，预算限制，类型安全输入。扣分：数据流透明度不足，未详细说明工具调用如何记录或审计；来源归属仅通过作者字段，未验证发布者身份。
证据显示：测试覆盖广泛，CI包含lint、类型检查、测试、安全扫描，依赖版本有约束。扣分：未提供失败消息的具体示例，依赖可用性未验证（静态审查）。
证据显示：面向开发者和终端用户，提供CLI和框架两种使用方式，支持多种模型和提供商，场景覆盖广泛。扣分：能力边界描述不够精确，触发条件（如forking）未详细说明。
证据显示：README结构清晰，安装说明详细，MIT许可证明确，有CHANGELOG和版本号。扣分：已知限制未明确列出，维护责任未明确（发布者未验证）。
证据显示：输出类型安全，提供结构化输出，边际价值高（独特功能如forking）。扣分：成本效益未量化，实际运行效果未验证。
证据显示：README中的声明与代码和测试部分对应，测试文件验证了部分功能。扣分：跨来源验证不足，仅依赖单一仓库证据。
- 发布者身份未验证，需谨慎对待来源。
- 数据流透明度不足，工具调用审计日志未明确。
- 已知限制未列出，可能隐藏潜在问题。
最近版本
来自该项目 GitHub Releases 的最新发布记录，说明为上游原文摘录，未经本站改写或测试。
-
发布说明摘录
Fixed - **Context compression used a different provider when model was a Model instance.** Only a model string was inherited, so an agent built on, say, an OpenAIChatModel for an OpenAI-compatible gateway summarized with DEFAULT_SUMMARIZATION_MODEL - a provider the deployment may have no key for. summarization_model now defaults to the primary model either way, and accepts a Model instance itself.在 GitHub 查看 ↗ -
发布说明摘录
Added - The CLI's /model picker lists local models under "Local (discovered)": the models Ollama has pulled, and what an OpenAI-compatible server (llama.cpp, LM Studio, vLLM) serves at {base_url}/models. Discovery runs in the background with a two-second timeout; a server that is down adds nothing. ([#216](https://github.com/vstorm-co/pydantic-deepagents/issues/216)) - Messages from outside the terminal into a live CLI session. pydantic-deep tui --listen accepts messages on a loopback HTTP endpoint …在 GitHub 查看 ↗ -
发布说明摘录
Added - memory_namespace= on create_deep_agent and DeepAgentSpec: a segment between memory_dir and the agent's name, fixed or resolved per run (a user id, say), for several users sharing one workspace. The model never sees it. Each /-separated part is letters, digits, _, - and .; a fixed one that is not is refused when the agent is built. - build_memory_capability(), which builds the Memory capability the way create_deep_agent does. Changed - Memory is the pydantic-ai-harness Memory capability. Each agent keeps a …在 GitHub 查看 ↗