Typsichere Agent-Governance für Pydantic AI — strukturierte Output-Validierung, Dependency-Injection und MCP-Kontext-Weiterleitung ohne Verlust der Pydantic-Typ-Garantien.

Pydantic AI Integration

Deklarieren Sie Palveron als typisierte Abhängigkeit Ihres Pydantic-AI-Agenten. Jeder Nutzer-Prompt, jedes Tool-Ergebnis und jede strukturierte Ausgabe wird gegen Ihre Palveron-Policies verifiziert — ohne die Typ-Garantien von Pydantic AI aufzugeben.

Installation

pip install palveron-pydantic-ai

Schnellstart: 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 "Du bist ein hilfsbereiter Kundensupport-Assistent."

result = agent.run_sync(
    "Überweise 50.000 € von Konto DE89370400440532013000",
    deps=deps,
)
# → PalveronGovernanceError: Blockiert — PII erkannt (IBAN)

Schnellstart: Output-Validator für strukturierte Typen

Verifizieren Sie strukturierte Ausgaben ohne Verlust der Typsicherheit:

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("Entwirf eine Antwort an den verärgerten Kunden")
# result.output ist ein typisierter CustomerReply — bereits governiert

Schnellstart: Governance-Tool

Registrieren Sie Palveron als Tool, das das Modell explizit aufrufen kann. Der Rückgabewert ist das typisierte PalveronVerifyResult BaseModel:

from pydantic_ai import Agent
from palveron_pydantic_ai import register_palveron_tool

agent = Agent(
    "openai:gpt-4o",
    system_prompt="Bevor du einen Entwurf sendest, rufe palveron_verify auf dem Text auf.",
)
register_palveron_tool(agent, api_key="pv_live_xxx")

Was geprüft wird

Surface	Methode	Anwendungsfall
Nutzer-Prompt	`deps.verify_user_input(prompt)`	Aus `@agent.system_prompt` aufrufen, um Prompt-Injection / PII am Eingang zu blockieren
Tool-Ergebnis	`deps.verify_tool_result(name, result)`	In einem `@agent.tool` nach dem Abruf sensibler Daten aufrufen
Strukturierte Ausgabe	`palveron_output_validator(...)`	Als Output-Validator anhängen, um das typisierte Ergebnis zu kontrollieren
Explizite Prüfung	`register_palveron_tool(agent, ...)`	Das Modell kann `palveron_verify(prompt)` während der Reasoning-Phase aufrufen

Konfiguration

deps = PalveronDeps(
    api_key="pv_live_xxx",
    base_url="https://gateway.internal.firma.de:8080",  # on-prem
    fail_open=False,            # Bei Gateway-Ausfall blockieren (Enterprise-Standard)
    metadata={"team": "support", "env": "prod"},
)

Typsicheres Verify-Ergebnis

PalveronVerifyResult ist ein pydantic.BaseModel. Sie können es als output_type deklarieren oder als Tool-Rückgabetyp verwenden — die Pydantic-AI-Strukturgarantien bleiben erhalten:

from palveron_pydantic_ai import PalveronVerifyResult

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

MCP-Kontext-Weiterleitung

Pydantic AI unterstützt MCP-Server nativ. Wenn ein Tool-Aufruf von einem MCP-Server stammt, liest der Adapter MCP-Server-Name, Run-ID und Tool-Name aus dem RunContext und leitet sie über RequestContext an die Palveron-Trace weiter. Der Trace Explorer zeigt die vollständige Agenten-Provenienz.

Governance-Records

print(f"Blockiert: {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)")

Fehlerbehandlung

from palveron_pydantic_ai import PalveronDeps, PalveronGovernanceError

deps = PalveronDeps(api_key="pv_live_xxx")

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

Quellcode

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

Nächste Schritte

Eigene Policies erstellen für Ihre Pydantic-AI-Agenten
LlamaIndex Integration für RAG-spezifische Governance
Google ADK Integration für multimodale Agenten

Pydantic AI

On this page