PydanticAI Integration Blueprint

Approve deferred PydanticAI tools without losing typed guarantees.

Use Stacksona around deferred tool requests and typed output validation so side effects wait for review while your schema remains the contract.

Governance object: deferred tool request + typed output validation.

Official docs ↗Deferred tools ↗Output API ↗

Where Stacksona sits

Typed request

validated model

Deferred tool

pending side effect

Gate check

schema context

Reviewer

decision

Fulfill

approved payload

Emit

typed result

The useful integration point is the last safe moment before an external action, privileged read, or customer-visible response occurs.

Implementation steps

Use these steps as the first implementation pass. Start with one high-risk action, verify the reviewer workflow, then expand coverage.

Define approval-worthy tool schemasIdentify Pydantic models that represent side effects: refunds, account changes, messages, writes, or privileged reads.
Create the decision before fulfillmentWhen a deferred tool request is produced, send the typed arguments and validation result to Stacksona before running the side effect.
Keep decision status typedRepresent approved, rejected, and pending states as explicit fields in your result model.
Validate again before executionUse the approved typed payload, not free-form reviewer notes, as the final execution contract.

Recommended package

Use the Stacksona SDK or API wrapper

For Node.js or TypeScript guard services, start with the live SDK. For Python runtimes, call the same guard through your backend or a small HTTP wrapper.

npm i @stacksona/sdk

View SDK on npm

Approval payload to send

Keep the payload compact enough for a reviewer to decide quickly, but specific enough to explain exactly what the agent wants to do.

Field	What to include
agent	Stable name for the agent, crew, graph, or workflow that is asking for approval.
action	Human-readable verb such as `send_email`, `issue_refund`, or `execute_tool`.
risk	Use `low`, `medium`, or `high` so reviewers can triage quickly.
subject	The customer, ticket, repository, account, or data source affected by the action.
context	Small, reviewable facts: proposed arguments, policy signals, retrieved sources, role, task id, and links.

Deferred tool approval

starter pattern

class RefundRequest(BaseModel):
    customer_id: str
    amount: float
    reason: str


def fulfill_refund(request: RefundRequest):
    decision = gate_request({
        "agent": "pydanticai-refund-agent",
        "action": "issue_refund",
        "risk": "high",
        "subject": request.customer_id,
        "context": {
            "schema": "RefundRequest",
            "validated_args": request.model_dump(),
        },
    })

    if decision["status"] != "approved":
        return {"status": "pending_review", "decision_id": decision["id"]}
    return issue_refund(request)

Treat this as the shape of the guard. Replace gate_request, stacksona.gate.request, or run_tool with the SDK/API calls used in your runtime.

Practical guidance

Best gate points

Deferred tool fulfillment, output validators, and any typed object that triggers a side effect.

Reviewer context

Schema name, validated arguments, risk reason, and downstream side effect.

Avoid

Do not let untyped reviewer comments replace validated tool arguments.

Try 14 Days Free View Integration Overview