Pydantic AI v2: capable agentic loopsPydantic AI v2：强大的智能体循环

#One primitive: the capability#一个原语：能力

A capability bundles an agent's instructions, tools, lifecycle hooks, and model settings into a single, composable unit, so a whole extension (a memory system, a guardrail, a coding toolkit) can reach every layer of the agent through one concept. It is the unit of agent behavior that lives in the loop, and you attach one the same way you attach any other:能力将智能体的指令、工具、生命周期钩子和模型设置打包成一个可组合的单元，因此整个扩展（如记忆系统、护栏、编码工具包）可以通过一个概念触及智能体的每一层。它是存在于循环中的智能体行为单元，你可以像附加其他任何东西一样附加它：

from pydantic_ai import Agent
from pydantic_ai.capabilities import Capability, Thinking, ToolSearch, WebSearch
from pydantic_ai.mcp import MCPToolset
from pydantic_ai_harness import CodeMode

agent = Agent(
    'anthropic:claude-opus-4-7',
    instructions='Research thoroughly and cite your sources.',
    capabilities=[
        Thinking(effort='high'),  # extended thinking, unified across providers
        CodeMode(),               # one run_code call replaces N tool calls, sandboxed by Monty
        WebSearch(),              # native where the provider supports it, local fallback otherwise
        ToolSearch(),             # discover tools on demand instead of listing hundreds upfront
        Capability(
            id='github',
            description='Look up GitHub issues, pull requests, and code.',
            instructions='Use the GitHub tools when a question is about a repository.',
            toolset=MCPToolset('https://mcp.example.com/github'),
            defer_loading=True,  # stays out of the prompt until the model loads it on demand
        ),
    ],
)

Some of these are just model settings, like Thinking. Some wrap a native tool, like WebSearch, which runs natively where the provider supports it and falls back to a local implementation otherwise. The powerful ones use hooks to read and rewrite what the model sees on every step, including its tools, its instructions, and its message history. Code mode and tool search are built on exactly the same public hooks your own capabilities would use, so the batteries we ship double as worked examples.其中一些只是模型设置，比如 Thinking。有些包装了原生工具，比如 WebSearch，它在支持该工具的提供商处原生运行，否则回退到本地实现。强大的能力使用钩子在每一步读取和重写模型看到的内容，包括其工具、指令和消息历史。代码模式和工具搜索正是基于你自定义能力也会使用的相同公共钩子构建的，因此我们提供的电池也充当了工作示例。

The GitHub entry shows a richer shape: a Capability you build inline from an id, a description, some instructions, and a toolset (here an MCP server). Marked defer_loading=True, it stays out of the prompt until the model needs it: the model sees only the one-line description in a compact catalog, then loads the whole bundle, instructions and tools together, in a single step when it decides to.GitHub 条目展示了一个更丰富的形态：一个你通过 id、描述、一些指令和一个工具集（这里是一个 MCP 服务器）内联构建的能力。标记为 defer_loading=True，它在模型需要之前不会出现在提示中：模型只在一个紧凑的目录中看到一行描述，然后在决定使用时一步加载整个包，包括指令和工具。

The capability is also why so much has landed lately. In recent releases we have turned more and more of the framework into capabilities: instrumentation, deferred tool calls resolved in the loop, server-side compaction for OpenAI and Anthropic, capabilities built dynamically per run, on-demand loading so a deferred capability stays out of the prompt until the model needs it, a pending message queue for steering a run mid-flight, and even durable execution, which is moving onto the same capability layer (in progress, with a runtime extension point tracked for after v2).能力也是最近这么多功能落地的原因。在最近的版本中，我们将越来越多的框架部分变成了能力：仪表化、在循环中解决的延迟工具调用、OpenAI 和 Anthropic 的服务器端压缩、每次运行动态构建的能力、按需加载（使延迟能力在模型需要之前不进入提示）、用于在运行过程中引导的待处理消息队列，甚至持久执行（正在迁移到相同的能力层，正在进行中，并计划在 v2 之后添加运行时扩展点）。

Because capabilities are serializable, an agent can be loaded from a spec file, and the surface is small enough that an LLM can write one: point a coding agent at the capabilities docs and it builds most of what you need. It points at something we are excited about, though not a promise yet: with Monty, our safe Python subset, an agent could propose its own declarative tweaks, like adding a hook that trims an oversized tool result before it fills the context window. And because instrumentation is now a capability too, the traces you already send to Logfire close the loop: an agent that reads its own runs could spot the clearly-wrong things, a pair of contradictory instructions or a tool whose description doesn't match what it does, and suggest the fix. We have already started turning that loop into something real in Logfire.由于能力是可序列化的，智能体可以从规范文件加载，而且其表面足够小，LLM 可以编写一个：将编码智能体指向能力文档，它就能构建你所需的大部分内容。这指向了我们感到兴奋的事情，尽管还不是承诺：借助 Monty（我们的安全 Python 子集），智能体可以提出自己的声明式调整，比如添加一个钩子，在过大的工具结果填满上下文窗口之前将其修剪。而且由于仪表化现在也是一种能力，你已经发送到 Logfire 的追踪信息可以形成闭环：读取自己运行的智能体可以发现明显错误的东西——一对矛盾的指令或一个描述与实际不符的工具——并建议修复。我们已经开始在 Logfire 中将这个循环变成现实。

#The Harness and a leaner core#Harness 和更精简的核心

Some capabilities ship with Pydantic AI itself; more come from the first-party Pydantic AI Harness, the batteries for your agent (memory, guardrails, context management, file system access, code mode, and more); and others are third-party or your own. Plenty already come from the community: VStorm and others ship capabilities that we endorse and link to from the Harness, and are working to upstream. The Harness is where we are spending June: a wave of new capabilities, plus a headless coding agent built on Pydantic AI that we are dogfooding across Pydantic's own repositories.一些能力随 Pydantic AI 本身提供；更多来自第一方 Pydantic AI Harness，即你智能体的电池（记忆、护栏、上下文管理、文件系统访问、代码模式等）；其他则是第三方或你自己的。社区已经提供了很多：VStorm 和其他人提供了我们认可并从 Harness 链接的能力，并且正在努力向上游贡献。Harness 是我们六月份的重点：一波新能力，加上一个基于 Pydantic AI 构建的无头编码智能体，我们正在 Pydantic 自己的仓库中自用。

The split is deliberate. Core stays small and stable, shipping the loop, the providers, the capability and hooks API, and only the capabilities that need deep provider support or are fundamental to every agent. Everything else lives in the Harness, where it can move fast, and a capability can graduate into core once it proves broadly essential. v2 leans into that: uv add pydantic-ai still includes OpenAI, Anthropic, and Google by default, but the long tail of providers (bedrock, groq, mistral, and friends) is now opt-in, so you install only what you use. The full Upgrade Guide covers every behavior change, split into what a deprecation warning already caught and what to check by hand.这种分离是故意的。核心保持小巧稳定，提供循环、提供商、能力和钩子 API，以及仅需要深度提供商支持或对每个智能体都至关重要的能力。其他所有内容都放在 Harness 中，在那里可以快速迭代，一旦能力被证明广泛必要，就可以升级到核心。v2 倾向于这一点：uv add pydantic-ai 仍然默认包含 OpenAI、Anthropic 和 Google，但长尾提供商（bedrock、groq、mistral 等）现在是可选的，因此你只安装你使用的。完整的升级指南涵盖了每个行为变化，分为弃用警告已经捕获的内容和需要手动检查的内容。

#A word on the version policy#关于版本策略的一点说明

One deliberate change comes with v2: the no-breaking-changes window between major versions moves from six months to three. This is not us caring less about stability. The field moves fast enough that committing further out means committing to decisions that fit today and not the world three months from now. Everything else stands. No breaking changes within a major version, and deprecations always land before removals, exactly as you saw in the run-up to this release: the latest v1 already warns about most of what v2 changes.v2 带来一个刻意的变化：主要版本之间的无破坏性更改窗口从六个月缩短到三个月。这不是我们不关心稳定性。这个领域发展太快，承诺更远的未来意味着承诺适合今天而不是三个月后世界的决策。其他一切保持不变。主要版本内没有破坏性更改，弃用总是在移除之前出现，就像你在本次发布前看到的那样：最新的 v1 已经警告了 v2 更改的大部分内容。

#Try it#试试看

uv add pydantic-ai

Try it on something real, keep the Upgrade Guide handy if you are coming from v1, and tell us what you build (or what breaks) on GitHub or in Slack. We can't wait to see it.在真实场景中试试看，如果你从 v1 迁移，请准备好升级指南，并在 GitHub 或 Slack 上告诉我们你构建了什么（或什么出了问题）。我们迫不及待想看到。