Add tool approval integration for Vercel AI adapter

[bendrucker]

Closes #4279

Adds tool approval integration for the Vercel AI adapter, enabling human-in-the-loop workflows with AI SDK UI.

Summary

• Setting sdk_version=6 enables tool approval
• Emit tool-approval-request chunks for deferred tool approvals
• Emit tool-output-denied chunks when user denies tool execution
• Auto-extract approval responses from follow-up requests
• Add approval field to tool parts with ToolApprovalRequested/ToolApprovalResponded states

Usage

from pydantic_ai import Agent
from pydantic_ai.ui.vercel_ai import VercelAIAdapter

agent = Agent('openai:gpt-5.2')

@agent.tool_plain(requires_approval=True)
def delete_file(path: str) -> str:
    """Delete a file from the filesystem."""
    os.remove(path)
    return f'Deleted {path}'

@app.post('/chat')
async def chat(request: Request) -> Response:
    adapter = await VercelAIAdapter.from_request(request, agent=agent, sdk_version=6)
    return adapter.streaming_response(adapter.run_stream())

When sdk_version=6, the adapter will:

1. Emit tool-approval-request chunks when tools with requires_approval=True are called
2. Automatically extract approval responses from follow-up requests
3. Emit tool-output-denied chunks for rejected tools, passing the denial reason through as ToolDenied

AI SDK Tool Approval Protocol

Tool approval is an AI SDK v6 feature. Here's how the protocol works:

Protocol Flow

sequenceDiagram
    participant Model
    participant Server
    participant Client

    Model->>Server: tool call
    Server->>Client: tool-input-start
    Server->>Client: tool-input-available
    Server->>Client: tool-approval-request

    Note over Client: User approves/denies

    Client->>Server: approval response (next request)

    alt Approved
        Server->>Server: Execute tool
        Server->>Client: tool-output-available
    else Denied
        Server->>Client: tool-output-denied
        Server->>Model: denial info
    end

Loading

Chunk Types

tool-approval-request

Server → client:

{
  "type": "tool-approval-request",
  "approvalId": "<uuid>",
  "toolCallId": "<tool-call-id>"
}

tool-output-denied

Server → client, when denied:

{
  "type": "tool-output-denied",
  "toolCallId": "<tool-call-id>"
}

Why the Server Emits This Chunk

"Pydantic AI doesn't have an event for denials because denials never originate in Pydantic AI itself, they come from the user in the form of DeferredToolResults passed into agent.run" — #3760 comment

This is correct—the denial decision originates from the user via the ToolApprovalResponded field in tool parts. However, the AI SDK protocol expects the server to emit tool-output-denied for two reasons:

1. The client needs confirmation that the tool lifecycle is complete. When the server receives a denial and emits tool-output-denied, the client can transition its UI from "awaiting result" to "denied".

2. Just as the server emits tool-output-available when a tool executes successfully, it emits tool-output-denied when execution is skipped due to denial. This gives the client a consistent signal for each tool call's final state.

The flow is:

1. Client sends denial via approval: { id, approved: false, reason } in the tool part
2. Server extracts this from deferred_tool_results and passes it to the agent
3. When processing the denied tool result, server emits tool-output-denied to the client
4. Client updates UI to show the tool was denied

Tool Part Approval States

Tool parts include an approval field tracking the approval lifecycle:

Awaiting Response

{ "id": "<approval-id>" }

User Responded

{ "id": "<approval-id>", "approved": true/false, "reason": "optional" }

Two-Step Flow

Unlike regular tool calls, approved tools require two model interactions:

1. Model requests tool → server returns with tool-approval-request → awaits user
2. User decision sent → server executes (if approved) or informs model (if denied)

Changes

• Add ToolApprovalRequested/ToolApprovalResponded types and approval field to tool UI parts
• Add ToolApprovalRequestChunk and ToolOutputDeniedChunk response chunks to event stream
• Gate tool approval behavior on sdk_version=6 (added in Fix compatibility with Vercel AI SDK v5 by adding SDK version param #4166), enabling auto-extraction of approval responses via deferred_tool_results cached property
• Pass denial reason through as ToolDenied when provided
• Add tool approval section to Vercel AI docs

Testing

• Approval request/denied chunk emission, opt-out behavior, and approval extraction (approved, denied with reason, no approval)
• Snapshot updates for approval field on tool parts

References

• Builds on Add AI SDK data chunk ID and tool approval types #3760 (merged)
• AI SDK Human-in-the-Loop Cookbook
• AI SDK Stream Protocol
• Pydantic AI Deferred Tools

[bendrucker]

Thanks for the quick reviews! Will get the test issue fixed and reply to your comments shortly.

[github-actions]

This PR is stale, and will be closed in 3 days if no reply is received.

[github-actions]

Closing this PR as it has been inactive for 10 days.

[bendrucker]

Have been on a break for a bit, will get the comments addressed early this week if not today.

[DouweM]

@bendrucker Thanks Ben, I should probably have disabled the stale bot before the holidays :)

[bendrucker]

Thanks for your patience! Made the requested changes and provided a reference to relevant AI SDK test snapshots for the behavioral question.

[bendrucker]

Squashing another upstream cause of a test flake: pytest-dev/pytest-xdist#1299

[DouweM]

@bendrucker I merged some other changes for the Vercel AI event stream that had been in the works for a few weeks -- can you resolve the conflicts please?

[bendrucker]

Resolved!

[DouweM]

@bendrucker Please have a look at the conflicts

[DouweM]

@bendrucker Did you mean to push your changes?

[bendrucker]

Whoops, done!

[DouweM]

@bendrucker We've got merge conflicts 😅

[bendrucker]

No worries, saw em, fixing them now!

[DouweM]

@bendrucker Thanks Ben! It took a minute but I'll get this out in a release later today :)

[bendrucker]

Thank you! Appreciate your patience, Python is still somewhat new to me. Learned a bunch and will be eager to integrate this soon!