Pydantic AI V2 Beta 4 Tightens the Agent Contract Where Production Systems Actually Break

Pydantic AI V2 Beta 4 is the kind of release that looks minor if you scan for features and important if you operate agents for a living. The headline is not “new agent toys.” The headline is that Pydantic is tightening the contracts around the places production agent systems actually fail: MCP prompts, client-submitted metadata, unsafe file flags, ambiguous tool preparation, and model-router settings that quietly change latency or spend.

That is the right direction. The hard part of building agents in 2026 is no longer wiring an LLM to a function. The hard part is knowing which boundary you are crossing, which fields you trust, which tools are exposed, which prompts came from which server, and which model settings actually reached the provider. Beta 4 reads like maintainers cleaning up those seams before V2 becomes the default path.

MCP prompts are now part of the supply chain

The most visible addition is MCP prompt discovery. PR #3889 adds list_prompts() and get_prompt() support to McpServer, while preserving caching behavior and prompt-list-change notifications. Pydantic’s MCP docs already position MCP servers as toolsets attached to an Agent(..., toolsets=[server]), with Streamable HTTP, SSE, and stdio transports, JSON configuration loading, environment-variable expansion, custom process_tool_call hooks, custom TLS/httpx clients, and client-identifying Implementation metadata.

Adding prompts to that surface matters because tools are not the only capability an MCP server can smuggle into an agent runtime. A server-provided prompt can shape behavior just as strongly as a server-provided tool. If an agent can list and fetch those prompts dynamically, platform teams need the same governance questions they ask for tools: who authored this prompt, which server served it, did it change, does the current agent have permission to use it, and is the prompt logged as part of the run record?

Pydantic gives builders the API surface. It does not magically give them policy. The practical move is to treat MCP prompts as runtime artifacts, not harmless text snippets. Version them. Attribute them. Log prompt IDs and server identities in traces. If a prompt can change behavior, it belongs in the audit trail.

The Vercel adapter draws the right trust boundary

The Vercel AI message metadata work in PR #5279 is the release’s most quietly important security change. It round-trips ModelResponse.timestamp and ModelRequest.timestamp through Vercel AI UIMessage.metadata, but deliberately excludes server-owned fields such as usage, model_name, provider IDs, provider_response_id, and finish_reason. The PR calls out the risk directly: trusting client-submitted history could let someone forge a provider_response_id and chain OpenAI previous_response_id='auto' into another user’s conversation.

That distinction should become a default design rule for every agent UI. Browser history can help reconstruct a conversation. It should not be trusted to assert billing facts, provider response IDs, model identity, finish reasons, or server-side execution state. If your app accepts those fields back from the client and treats them as truth, you are not persisting history. You are outsourcing runtime state to an adversarial cache with nice CSS.

The same theme shows up in PR #5571, which strips unsafe client-submitted file-download trust flags. The issue is FileUrl.force_download='allow-local', a flag that can bypass private-IP blocking in safe_download. That may be acceptable for server-authored URLs. It is not acceptable when the URL and flag come back from UI history. Resetting allow-local unless explicitly allowlisted is the correct boring default: client-submitted trust flags should be scrubbed or revalidated, not obeyed because they happen to deserialize cleanly.

Ambiguous tool prep should fail loudly

Beta 4 also turns the V1 deprecation warning for prepare-callback None returns into a hard TypeError. Some migrations will grumble. They should still take the hint.

Tool preparation is not a cosmetic callback. It decides what an agent can do. Ambiguous semantics here are how systems accidentally expose no tools, too many tools, or stale tools while still appearing to run normally. A callback should return the tool list to expose or explicitly return an empty list. Runtime clarity beats permissive magic once multiple toolsets, MCP servers, and prepared-tool callbacks compose.

The model-router fixes are less security-flavored but still operationally meaningful. PR #5656 adds Anthropic eager_input_streaming support for OpenRouter-routed Anthropic models, so large tool-call arguments can stream incrementally instead of waiting for a full JSON buffer. PR #5433 forwards thinking=False across hybrid OpenRouter, xAI, and Bedrock routes where it had been silently dropped, affecting shapes including Kimi, Qwen, GLM, gpt-oss-120b, Claude, Grok, and Bedrock routes. PR #5674 preserves Bedrock’s full tools array when native single-tool toolChoice is used.

These are not splashy features. They are the difference between the runtime doing what the caller asked and the runtime silently changing latency, cost, or provider behavior. That matters when Pydantic AI sits between users and a multi-provider bill.

The project had 17,393 stars, 2,157 forks, 579 open issues, and a push as recent as 2026-05-30T07:18:24Z at research time. Public discussion was quiet — no relevant Hacker News hits for the release-specific queries — but the GitHub review activity tells the real story: #3889 alone had 20 comments and 87 review comments. This is maintainers grinding through boundary cases, not trying to win a launch-day thread.

Practitioners should use Beta 4 as an audit checklist. If you use MCP, log prompt and server identity. If you persist UI history, separate client-owned metadata from server-owned execution facts. If users can submit file URLs, scrub trust flags. If a callback controls tool exposure, make its empty state explicit. If you route through OpenRouter or Bedrock, verify the settings you pass are the settings the provider receives.

The larger take: Pydantic AI is moving V2 from ergonomic framework toward runtime contract. That is where agent frameworks need to go. The future is not “how fast can I wire a tool?” It is “which fields, flags, prompts, and model settings are trusted across every boundary?” The boring answer is the one that survives production.

Sources: Pydantic AI release notes, PR #3889, PR #5279, PR #5571, PR #5656, Pydantic AI MCP docs