Pydantic AI

Answer Pydantic AI's requires_approval tool calls with a person's decision from an inbox, inside the run or hours later.

Pydantic AI already knows when a tool call needs a person: mark the tool requires_approval=True and the agent stops before running it. What it leaves to you is who decides and where. This page makes that a request in your VariantGate inbox, so the decision can come from a phone, an email link or Slack, a rule can answer the routine ones, and every answer is kept on the record.

1. Install the client

pip install https://variantgate.com/sdk/variantgate-latest.tar.gz

It has no dependencies beyond the standard library and works on Python 3.9 or newer. Make an agent key under Agents in your workspace and put it in VARIANTGATE_KEY. The client reads it from there.

2. Answer approvals with a person’s decision

HandleDeferredToolCalls is the Pydantic AI capability that resolves calls needing approval inside the run. Its handler below asks about every pending call at once, so a person sees them side by side, then waits for each answer and tells the agent which calls may run. The tool itself stays plain.

import asyncio
import contextlib

from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities import HandleDeferredToolCalls
from pydantic_ai.messages import ToolCallPart
from pydantic_ai.tools import DeferredToolRequests, DeferredToolResults, ToolDenied
from variantgate import (
    ApprovalClient,
    ChangedApprovalError,
    NotApprovedError,
    VariantGateError,
    is_allowed,
    is_changed,
)

approvals = ApprovalClient("support-agent")  # reads VARIANTGATE_KEY


def describe(call: ToolCallPart) -> dict:
    """What a person sees for one tool call: an action, a summary, an amount."""
    args = call.args_as_dict()
    if call.tool_name == "refund_order":
        return {
            "action": "payment.refund",
            "summary": f"Refund €{args['amount_eur']} for order {args['order_id']}",
            "amount": args["amount_eur"],
            "currency": "EUR",
            "details": {"order": args["order_id"]},
        }
    return {"action": f"tool.{call.tool_name}", "summary": f"Run {call.tool_name}", "details": args}


def answer(decision: dict) -> bool | ToolDenied:
    """Approve the call only on an unchanged yes; otherwise tell the model why not."""
    if not is_allowed(decision):
        return ToolDenied(str(NotApprovedError(decision)))
    if is_changed(decision):  # a person approved less, or other wording
        approvals.report_outcome(decision["id"], "failed", "not done: approved with changes")
        return ToolDenied(str(ChangedApprovalError(decision)))
    return True


async def ask_a_person(ctx: RunContext, requests: DeferredToolRequests) -> DeferredToolResults:
    """Ask about every call at once, then answer each with a person's decision."""
    asked = {
        call.tool_call_id: await asyncio.to_thread(approvals.ask, **describe(call))
        for call in requests.approvals
    }
    results = DeferredToolResults()
    for call_id, request in asked.items():
        decision = await asyncio.to_thread(approvals.wait, request, 900)
        results.approvals[call_id] = await asyncio.to_thread(answer, decision)
        results.metadata[call_id] = {"approval": decision["id"]}
    return results


agent = Agent(
    "openai:gpt-5",
    instructions="Help customers with their orders.",
    capabilities=[HandleDeferredToolCalls(handler=ask_a_person)],
)


@agent.tool(requires_approval=True)
def refund_order(ctx: RunContext, order_id: str, amount_eur: str) -> str:
    """Refund an order to the customer's original payment method."""
    refund_id = shop.refund(order_id, amount_eur)
    with contextlib.suppress(VariantGateError):  # the money moved: never fail over the record
        approvals.report_outcome(ctx.tool_call_metadata["approval"], "succeeded", f"refund {refund_id}")
    return f"Refunded €{amount_eur} for order {order_id}."


result = agent.run_sync("Order 1182 arrived broken. Please refund the €49.")
print(result.output)
  • An approved call runs. A denied, expired or withdrawn one, or any call while the workspace is paused, reaches the model as a ToolDenied message, such as “Not approved: the request is denied”, so it can tell the customer instead of trying again.
  • describe is where you write what a person reads. Give each tool a clear action name and state the amount, so rules with amount limits can answer the small ones.
  • If a person lowers the amount or rewords the request, answer denies the call and records that nothing was done. The model is told what was approved and can ask again for that.
  • The request id travels to the tool in tool_call_metadata, so the tool can record the refund. Once the money has moved, a failure to record it never fails the run, so nothing tempts the agent into a second refund.
  • The calls to the API run in a thread, so other runs on the same event loop keep going while a person decides. If the API cannot be reached, the handler raises, the run fails and nothing is refunded.

When the answer may take hours

The handler above holds the run open while a person decides, up to 900 seconds a call. For a decision that may take longer, leave the capability out and let the run end with the calls still waiting. Ask without waiting, save the message history with the request ids, and start a new run with deferred_tool_results when a signed webhook says the last request was decided. The webhook only says when: the new run reads each request with check, and the same answer approves a call only on an unchanged yes. Pass the request ids as metadata again, so the tool can record the outcome.

from pydantic_ai.tools import DeferredToolRequests, DeferredToolResults

# The same agent and tool, without the capability: the run ends with the calls.
agent = Agent("openai:gpt-5", output_type=[str, DeferredToolRequests])
agent.tool(requires_approval=True)(refund_order)

result = agent.run_sync("Order 1182 arrived broken. Please refund the €49.")
if isinstance(result.output, DeferredToolRequests):
    asked = {
        call.tool_call_id: approvals.ask(**describe(call), ttl_seconds=24 * 3600)["id"]
        for call in result.output.approvals
    }
    save(asked, result.all_messages())  # your database

# Later, once a webhook says the last of them was decided:
asked, history = load()
results = DeferredToolResults()
for call_id, request_id in asked.items():
    decision = approvals.check(request_id)
    results.approvals[call_id] = answer(decision)
    results.metadata[call_id] = {"approval": request_id}
result = agent.run_sync(message_history=history, deferred_tool_results=results)

When the built-in approval is enough

If the person chatting with the agent is the one who should decide, answer DeferredToolRequests in your own UI and leave VariantGate out. It earns its place when the agent runs with nobody watching, when someone else must decide, when rules should settle the routine calls, or when you need a record of who approved what. The framework comparison goes through that choice.