PARAS MADAN
All writing

Latest in AI

Pydantic AI 2.71: Show Validated Tool Arguments Before Approval

Update deferred-tool approval screens for Pydantic AI 2.71, with streaming and adapter caveats, resume-time validation and a practical regression-test plan.

An approval screen is useful only if the person understands the action they are approving. That becomes harder when a tool's validation step changes the arguments after the model produces them.

Pydantic AI 2.71 adds DeferredToolRequests.validated_args to make those transformed arguments available. The release notes also include fixes around deferred pauses and keeping approval-required tools native under CodeMode(tools='all'). The release is not a blanket guarantee that every existing approval interface now displays an immutable execution payload.

For teams with a custom approval screen, this is a specific migration worth reviewing. The review below focuses on the places where the displayed request and eventual action can diverge.

Separate the recorded request from the validated view

The merged implementation keeps the model's original arguments in approvals, calls and message history. The new mapping is keyed by tool-call ID and contains JSON-compatible validated values using Python parameter names. Schema coercion and validation-hook rewrites can make that view different from the original request.

I would label the two representations clearly in an internal review interface: what the model requested and what validation produced. Do not silently overwrite the original record. When someone investigates an unexpected action, the difference between those stages can be the most useful evidence.

For an illustrative document-publishing tool, the meaningful review fields might be destination, audience and publication state. A reviewer should not have to infer those details from a large JSON object or a reassuring sentence written by the model.

Handle missing values deliberately

The deferred-tools documentation says run_stream() and run_stream_sync() do not populate this mapping for calls they end on because approval or external execution is required. The implementation PR also identifies gaps in Vercel AI approval input, ApprovalReviewer and the ACP permission flow, which still use model arguments in the described paths.

My recommendation is to make a missing validated view an explicit interface state. For a consequential action, do not relabel raw model arguments as validated just to keep the approve button enabled. Route that case through an application path you have checked, or require a separate review of the final action.

Test the actual adapter and run method your application uses. A passing test for one path is not evidence about another.

Remember that resume validates again

According to the deferred-tools guide, resuming an approved call revalidates the model arguments, including hooks. A hook reading changing external state can therefore produce a different result. ToolApproved(override_args=...) supplies replacement arguments, but those still undergo validation.

For the publishing example, imagine that an alias resolves to a different destination while approval is pending. I would require the application to compare the consequential destination and audience against the reviewed values immediately before acting. If they differ, stop and ask again. That is an application policy recommendation, not something this new field enforces automatically.

Keep such tests deterministic: replace external lookups with controlled fixtures, change the fixture between pause and resume, then assert that your application rejects the mismatch.

Review storage as well as the screen

Validated arguments can include defaults and values added by hooks, and travel into stored conversations. The docs warn against adding credentials that the approver must not see. The PR additionally notes serializer exclusions: the displayed dump is not necessarily every value the Python tool receives.

Audit the fields your review interface serializes, persists and logs. For the example above, a destination identifier belongs in the review; an access token does not. Keep authentication material outside the proposed-action record wherever your application design allows it.

The same documentation warns that client-submitted approval is not a substitute for authenticating the endpoint and enforcing authorization inside the tool.

Upgrade the regression tests, not just the dependency

Existing whole-object equality tests may change because deferred requests now carry validated_args. Update expected values intentionally rather than removing the assertion that caught the change.

I would add a small matrix covering a normal approved request, a denial, a transformed destination, a missing validated view and a pause resumed after external state changes. Use a fake publishing tool that records its inputs without contacting a service.

The acceptance criterion is simple: a reviewer can understand the proposed action, and the application refuses to execute a materially different one. A more informative approval object helps build that behavior. It does not replace it.

I'm Paras. I work at the intersection of AI, engineering and distribution.

I help AI teams explain technical products through clear documentation, practical guides and developer-focused content.

Book a 30-minute call.