“Pydantic AI 框架：30 项能力将裸模型转化为平台”

Pydantic AI 发布了一个框架库。不是框架，而是一个库。包含 30 个独立的能力，你可以像乐高积木一样组合成一个代理。我阅读了每一页文档。这里告诉你哪些是关键。

核心理念

Pydantic AI 的核心为你提供了代理循环、模型提供者以及一些基本能力：网络搜索、工具搜索、思考、MCP。所有其他能力都存在于 pydantic-ai-harness 中。你只需安装 pydantic-ai-slim 并选择你需要的能力。

uv add pydantic-ai-harness

关键的架构模式是“向上委派”——能力最初作为本地实现，与每个模型兼容，然后在可用时获得提供者本地支持。网络搜索、网络获取和图像生成已经在核心中以这种方式实现。技能、代码模式和压缩是下一步。

突出能力：代码模式

这是改变你对工具调用方式的那一个。模型不再每次行动只调用一个工具，每个调用都是单独的往返——代码模式将所有内容封装在一个 run_code 工具中。模型编写 Python 代码来调用你的工具作为函数。

# 模型在 run_code 中编写的代码：
paris, tokyo = await asyncio.gather(
    get_weather(city='Paris'),
    get_weather(city='Tokyo'),
)
# 本地计算，然后返回
paris_c = round((paris['temp_f'] - 32) * 5 / 9, 1)
{'paris': paris_c, 'tokyo': tokyo_c}

两个天气调用并行运行。转换在沙箱中进行。一次模型往返代替了三次。沙箱是蒙蒂——一个受限的 Python 运行时，没有第三方导入，没有时间原语，通过挂载点控制文件系统访问。

代码模式是早期候选者，将毕业进入核心。这告诉你团队认为代理架构将走向何方。

多代理编排：两个层次

框架有两个不同层次的委派能力：

子代理 提供一个 delegate_task(agent_name, task) 工具。每次委派都是一个单独的工具调用和模型回合。每个委派的预算（使用限制、超时、最大调用次数），从可配置菜单中选择模型，错误包含。当委派偶尔发生或每个结果需要父代理的判断时，效果很好。

动态工作流 将编排代码化。模型编写一个 Python 脚本，调用子代理作为异步函数——扇出、链式调用、投票、重试循环——所有这些都在一次工具调用中完成。中间结果从未进入父代理的上下文。这是将代码模式应用于整个代理而不是工具的思路。

从子代理开始。当编排本身成为实际工作时，转换为动态工作流。

上下文管理：三重奏

长时间运行的代理有三种死亡方式。框架解决了所有三种：

压缩——一系列策略（滑动窗口、总结、去重、分层升级）在每次请求前编辑消息历史。所有编辑都持久化。所有保留工具调用/工具返回配对。

工具输出限制——拦截过大的工具返回。三种模式：截断（零 LLM，有损），溢出（零 LLM，无损，按需读取），总结（一次 LLM 调用）。可配置大小范围，每个工具可覆盖。

系统提醒——在运行中重新注入行为指导，以对抗指令遗忘。按固定节奏注入静态提醒，或动态可调用（包括零成本目标重新锚定和 LLM 动力提示）。以缓存点的临时尾部形式注入——从不持久化，从不使提示缓存失效。

这个最后的设计细节很重要。几个能力都使用了临时尾部模式：在 CachePoint 后面附加可变内容，以保持持久前缀在每次回合中字节不变。计划、系统提醒和记忆都这样做。这是将生产级代理基础设施与演示区分开的工程。

持久化与记忆

步骤持久化 在每次边界记录一切：只读步骤事件、可继续的快照和工具效果日志。发生崩溃后，你知道哪些工具启动但从未报告。四种后端：内存、文件、SQLite、MongoDB。大型负载的媒体外部化会自动进行。

记忆为代理提供一个持久的笔记本，具有乐观并发、命名空间隔离和有限的提示注入。模型看到的是经过精简的 MEMORY.md 摘要以及文件名——不是整个存储。按需工具用于读取、写入、删除和搜索。存储：文件（原子化 Markdown + SQLite 日志）、SQLite、Postgres。

对话搜索 在步骤持久化存储的历史记录上叠加 BM25 搜索。恢复压缩丢弃的回忆，以及同一存储中的过去运行。纯 Python，无依赖。

值得注意的其他功能

文件系统 和 Shell 为代理提供沙盒 I/O，具有允许/拒绝控制、环境清理（包括预设中从生成的命令中剥离 LLM API 密钥），以及自动后台进程清理。

代码库上下文 自动加载工作区树中的 CLAUDE.md/AGENTS.md 并暴露一个工具，用于展示代码库中的编码助手资产。遍历模式下，代理导航时会显示目录特定的指令。

护栏验证代理运行的三个边缘——输入提示、工具调用、输出结果——具有允许/阻止/替换/重试/批准判决。现成的密钥和 PII 检测器。

计划为模型提供一个结构化的任务列表，包括子任务、依赖关系和缓存安全的实时提醒。持久化存储使计划者/执行者分离：一个代理编写计划，另一个执行，存储是它们之间唯一的状态。

浏览器使用 将开放的网络任务委派给自主浏览器使用子代理。一个 browse_web 工具，真正的 Chromium，域白名单，模型从未见过的密钥处理。互补的方法——脚本化的 Playwright 风格工具——适用于已知流程。浏览器使用适用于未知页面上的模糊目标。

顾问使执行者可以咨询一个单独的顾问模型。在 Anthropic/OpenRouter 上是原生的，在其他地方是本地回退。本地路径共享父代理的使用计数。

运行时能力创建——代理在一次运行中编写、验证并持久化新的 Pydantic AI 能力，以便在下次运行时激活。是的，代理扩展了自己。激活边界是故意的：能力在下次 agent.run() 时生效，而不是当前运行。

缺失的功能

框架是 0.x 版本。API 将会打破。我需要注意的几件事：

没有流式组合。 动态工作流在一个工具调用中运行所有子代理——直到完成你都看不到中间结果。团队承认这一点。
ACP 是实验性的。 代理客户端协议（ACP）适配器（Zed）工作但明确不稳定。
并非所有路径都有持久执行。 本地顾问咨询、浏览器使用 'agent' 会话范围以及记忆的自动注入都存在持久性限制，使用 Temporal/Prefect/DBOS。

总结

Pydantic AI 框架是我见过的最精心设计的代理能力库。缓存安全的模式、明确的信任边界、提供者适应的“向上委派”方法——这些都是从已经将代理部署到生产环境并了解哪些会出问题的人那里学到的。30 项能力涵盖了完整的代理生命周期：输入验证、工具编排、上下文管理、持久化、记忆、多代理委派和输出控制。

如果你正在基于 Pydantic AI 构建，这并非可选。如果你正在评估代理框架，框架是让你考虑 Pydantic AI 而不是在原始模型 API 上自己构建的原因。

安装它。选择三个能力。发布一些东西。