pydantic-ai-harness：把 Pydantic AI 从单轮对话变成能跑几小时的代理
Pydantic AI 代理的电池。 Pydantic AI 核心提供了需要模型或框架支持的功能，以及每个代理网络搜索、工具搜索、思维的基础功能。
秒懂
- 它是什么？
- pydantic-ai-harness 是 Pydantic AI 的官方能力库，用 30 多个可组合的 capability 把简单代理扩展成能改代码、做研究、跨会话记忆的完整 harness。本文拆解它的设计、用法和边界。
- 适合谁用？
- 适合已经用 Pydantic AI 构建代理、但发现单轮对话不够用的团队。如果你需要代理长时间自主工作，比如修复代码库、研究问题、跨会话记忆，这个库能把这类能力以声明式方式加到现有 Agent 上。
- 能商用吗？
- 可以。MIT 是宽松许可证：你可以使用、修改并销售基于它的软件，只需保留版权和许可证声明。
- 还在维护吗？
- 在维护。仓库在最近一天内有新的提交。
- 用什么语言写的？
- 主要是 Python（依据 GitHub 的语言统计）。
以上回答依据项目的 GitHub 数据（最近同步于 2026年9月19日）和我们的分析，不构成法律意见。
开源项目深度解析
它解决什么问题：代理跑久了，模型之外的东西才是瓶颈
Pydantic AI 核心自带一个轻量 harness：类型化的代理循环、任意模型接入、自定义工具、结构化输出。对简单代理够用。但文档明确说，把代理放到复杂、长时间运行的任务里，比如修复一个代码库、研究一个问题、无人值守跑几小时，它需要的就不只是模型了。需要工作空间来操作文件，需要一份持续更新的计划，需要跨会话的记忆，需要子代理来分派工作，需要上下文管理撑到第十个小时，还需要持久执行，重启后不丢状态。pydantic-ai-harness 就是把这些东西打包成一个个 capability，让你按需加到任何 Agent 上。它面向的是已经用 Pydantic AI、但发现单轮对话满足不了需求的工程师。
核心机制：一切皆 capability，连完整代理也是组合出来的
这个库的全部内容就是一个原语：capability，一个自包含的代理行为单元，加到 `capabilities=[...]` 里就行。文档强调，Coder 不是框架里的框架，它是一个 CombinedCapability，把 FileSystem、Shell、RepoContext、Planning、SubAgent、ToolOutputLimits 这些块捆在一起。README 里给出了展开写法，每个块都是你可以直接单独用的。这意味着你可以从完整代理出发，拆掉不想要的部分；也可以从零开始，一块块往上加。构造参数，比如工作目录、命令白名单、窗口大小，会穿透到底层 capability。这个设计让组合和定制变成同一件事，没有两套 API。
快速上手：两条命令，一个完整编码代理
安装用 uv，一条命令带上 anthropic extra：`uv add "pydantic-ai-harness[anthropic]"`。然后创建一个 Agent，传入 capabilities 列表：`agent = Agent('anthropic:claude-fable-5', capabilities=[Coder()])`，调用 `agent.run_sync('Find out why tests/test_parser.py fails and fix the bug it caught.')` 就能得到一个能改文件的编码代理。README 里给了输出示例，显示它定位到 `parse()` 返回 None 的问题并修复了测试。如果不想写文件，可以用 `uvx --with pydantic-ai-harness clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5` 直接跑。换模型只需改字符串，比如 `openai:gpt-5.6-sol`，再加 WebSearch 和 Memory capability 就能跨会话记忆。所有 capability 都遵循同样的声明式添加方式。
能力清单：50 多个模块，按用途分组
README 列出了 50 多个 capability，分几类。Harnesses 类有两个完整代理栈：Coder 提供文件、shell、仓库上下文、规划、只读探索子代理和上下文控制；Researcher 提供搜索、页面抓取、委派子研究员和受限工具输出。执行环境类有 FileSystem，负责读写文件。还有 Skills，支持按需加载 `SKILL.md` 流程；Web Fetch、Guardrails、Dynamic Workflow 也以同样方式接入。每个 capability 都是自包含的，可以互相组合，也可以和你自己的自定义 capability 组合。文档强调，这些能力有些来自 pydantic-ai 核心，有些来自这个包，表格里用 Package 列标明来源。
一个真实局限：模型和框架支持是硬约束
README 开头就点明：Pydantic AI 核心自带的能力需要模型或框架支持，而 web search、tool search、thinking 这些是每个代理都需要的，但并非所有模型都提供。这意味着你不能假设每个 capability 在任何模型字符串下都能工作。比如 WebSearch 可能只对特定模型有效。文档没有给出兼容性矩阵，所以实际使用前必须查对应模型的文档。另一个局限是 Shell 能力默认有一个命令白名单，README 里 Coder 的例子允许 `git`, `rg`, `grep`, `find`, `ls`, `cat`, `sed`, `head`, `tail`, `python`, `uv`, `pytest`, `ruff`, `make`。如果代理需要跑白名单外的命令，你得自己扩展，这既是安全特性也是限制。
替代方案：自己拼装 vs 用完整代理
这个库本身就是替代方案的集合。文档明确说，你可以从 Coder 这样的完整代理开始，然后拆掉不需要的块；也可以从单个 capability 开始，自己组合。这两种方式都是官方支持的一等公民。如果你不想用这个库，替代方案是直接用 Pydantic AI 核心，自己写工具函数和循环来管理文件、记忆和上下文。区别在于：pydantic-ai-harness 把常见的代理周边设施预封装成可复用单元，省去重复造轮子；但代价是你得接受它的抽象和默认配置。自己写则完全可控，但每个代理都要重新实现这些模式。另一个相关项目是 Pydantic AI 本身的 CLI 工具 clai，它配合 uvx 可以运行导出的代理，但那是运行方式，不是能力库。
维护与许可：MIT 协议，活跃发布节奏
仓库采用 MIT 许可证，这对商业使用友好，没有 copyleft 约束。最近发布记录显示 v0.27.0 在 2026-08-27 发布，v0.26.0 在 2026-08-26，v0.25.0 在 2026-08-24，三天内三个版本，迭代速度很快。这意味着 API 可能还在变化，升级时需要留意 changelog。文档提到要保持 README、docs 和示例代码同步，说明项目对一致性有要求，但也暗示这些文件可能因为手工维护而出现偏差。采用前建议锁定版本，不要直接追 latest。
编辑结论
适合已经用 Pydantic AI 构建代理、但发现单轮对话不够用的团队。如果你需要代理长时间自主工作，比如修复代码库、研究问题、跨会话记忆，这个库能把这类能力以声明式方式加到现有 Agent 上。不适合只想写个简单问答脚本的人，那直接用 Pydantic AI 核心就够了，加 harness 只会增加依赖和概念负担。采用前先验证三件事：确认你用的模型支持你需要的 capability，比如 WebSearch 是否要求特定模型；检查 FileSystem 和 Shell 的默认权限是否符合你的安全要求；跑一遍 Coder 的导出代理，确认它在你的 Python 环境和模型字符串下能实际运行。这个库的边界很清楚：它解决的是代理的周边设施，不是模型能力本身，模型不支持的功能加再多 capability 也白搭。
社区笔记