Type-safe agent governance for Pydantic AI — structured output validation, dependency-injected verification, and MCP context forwarding without giving up Pydantic's type guarantees.

Pydantic AI Integration

Declare Palveron as a typed dependency on your Pydantic AI Agent. Every user prompt, every tool result, and every structured output is verified against your Palveron policies — without giving up Pydantic AI's type guarantees.

Installation

pip install palveron-pydantic-ai

Quickstart: Governance Dependency

from pydantic_ai import Agent, RunContext
from palveron_pydantic_ai import PalveronDeps

deps = PalveronDeps(api_key="pv_live_xxx")
agent = Agent("openai:gpt-4o", deps_type=PalveronDeps)

@agent.system_prompt
async def system_prompt(ctx: RunContext[PalveronDeps]) -> str:
    ctx.deps.verify_user_input(ctx.prompt)
    return "You are a helpful customer support assistant."

result = agent.run_sync(
    "Transfer $50,000 from account DE89370400440532013000",
    deps=deps,
)
# → PalveronGovernanceError: Blocked — PII detected (IBAN)

Quickstart: Structured Output Validator

Verify structured outputs without losing type safety:

from pydantic import BaseModel
from pydantic_ai import Agent
from palveron_pydantic_ai import palveron_output_validator

class CustomerReply(BaseModel):
    subject: str
    body: str
    sentiment: str

agent = Agent(
    "openai:gpt-4o",
    output_type=CustomerReply,
    output_validators=[palveron_output_validator(api_key="pv_live_xxx")],
)

result = agent.run_sync("Draft a reply to the angry customer")
# result.output is a typed CustomerReply — already governed

Quickstart: Governance Tool

Register Palveron as a tool the model can call explicitly. The return value is the typed PalveronVerifyResult BaseModel:

from pydantic_ai import Agent
from palveron_pydantic_ai import register_palveron_tool

agent = Agent(
    "openai:gpt-4o",
    system_prompt="Before sending any draft, call palveron_verify on the body.",
)
register_palveron_tool(agent, api_key="pv_live_xxx")

What Is Checked

Surface	Method	Use case
User prompt	`deps.verify_user_input(prompt)`	Call from `@agent.system_prompt` to block prompt injection / PII at entry
Tool result	`deps.verify_tool_result(name, result)`	Call inside a `@agent.tool` after retrieving sensitive data
Structured output	`palveron_output_validator(...)`	Attach as output validator to gate the typed result
Explicit verify	`register_palveron_tool(agent, ...)`	Let the model call `palveron_verify(prompt)` during reasoning

Configuration

deps = PalveronDeps(
    api_key="pv_live_xxx",
    base_url="https://gateway.internal.company.com:8080",  # on-prem
    fail_open=False,            # block on gateway outage (Enterprise default)
    metadata={"team": "support", "env": "prod"},
)

Type-Safe Verify Result

PalveronVerifyResult is a pydantic.BaseModel, so you can declare it as an output_type or use it as a tool return type and keep Pydantic AI's structured-output guarantees:

from palveron_pydantic_ai import PalveronVerifyResult

@agent.tool_plain
async def safe_draft(text: str) -> PalveronVerifyResult:
    return deps.verify_user_input(text)

MCP Context Forwarding

Pydantic AI has native MCP server support. When a tool call originates from an MCP server, the adapter pulls the MCP server name, run id, and tool name out of RunContext and forwards them on the Palveron trace as RequestContext. The trace explorer shows the full agentic provenance — no extra wiring on your side.

Governance Records

print(f"Blocked: {deps.blocked_count}")
print(f"Trace IDs: {deps.trace_ids}")

for record in deps.records:
    print(f"{record.event} [{record.surface}]: {record.decision} ({record.latency_ms:.0f}ms)")

Error Handling

from palveron_pydantic_ai import PalveronDeps, PalveronGovernanceError

deps = PalveronDeps(api_key="pv_live_xxx")

try:
    result = agent.run_sync("Send SSN 123-45-6789", deps=deps)
except PalveronGovernanceError as e:
    print(e.decision)   # "BLOCKED"
    print(e.trace_id)   # "trc_abc123"
    print(e.reason)     # "PII detected: Social Security Number"

Source Code

Open source (MIT): github.com/palveron/adapter-pydantic-ai.

Next Steps

Create your own policies for your Pydantic AI agents
LlamaIndex integration for RAG-aware governance
Google ADK integration for multimodal agents

Pydantic AI

On this page