Pydantic AI

Connect Pydantic AI to DashClaw and get your first governed action into /decisions in under 20 minutes.

Instance URL detected: https://your-dashclaw-instance.example.com

Deploy DashClaw

Get a running instance. Click the Vercel deploy button or run locally.

Already have an instance? Skip to Step 2.

Install the DashClaw Python SDK and Pydantic AI

Create a virtual environment and install the required packages.

Terminal

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install dashclaw pydantic-ai python-dotenv

Set environment variables

Create a .env file with your DashClaw connection details. No LLM API key required for the example.

.env

DASHCLAW_BASE_URL=https://your-dashclaw-instance.example.com
DASHCLAW_API_KEY=oc_live_...

Wrap your tool in the 4-step governance loop

The tool checks DashClaw guard before executing, records the action, waits for approval when required, and reports the outcome.

main.py

import os
from dotenv import load_dotenv
from dashclaw import DashClaw

load_dotenv()

claw = DashClaw(
    base_url=os.environ["DASHCLAW_BASE_URL"],
    api_key=os.environ["DASHCLAW_API_KEY"],
    agent_id="pydantic-ai-db-agent",
)


def governed_run_migration(migration_name: str, production: bool) -> str:
    """Run a database migration. Governed by DashClaw policies."""
    risk = 75 if production else 25
    goal = f"Run migration {migration_name} on {'production' if production else 'staging'}"

    # 1. GUARD: Check policy before executing
    result = claw.guard({
        "action_type": "database_migration",
        "declared_goal": goal,
        "risk_score": risk,
        "systems_touched": ["postgres"],
        "reversible": not production,
    })
    decision = result.get("decision", "allow")
    if decision == "block":
        return f"BLOCKED: {', '.join(result.get('reasons', []))}"

    # 2. RECORD: Declare intent
    action = claw.create_action(
        "database_migration", goal,
        risk_score=risk, systems_touched=["postgres"],
    )
    action_id = action["action_id"]

    # 3. HITL: Wait for approval if required
    if decision == "require_approval":
        try:
            claw.wait_for_approval(action_id, timeout=120, interval=5)
        except Exception as e:
            claw.update_outcome(action_id, status="cancelled", error_message=str(e))
            return f"DENIED: {e}"

    # 4. ASSUMPTION + EXECUTE + OUTCOME
    claw.register_assumption(
        action_id,
        f"Migration {migration_name} is idempotent",
        basis="Migration uses IF NOT EXISTS guards throughout",
    )
    migration_result = f"Migration {migration_name} applied successfully."
    claw.update_outcome(action_id, status="completed", output_summary=migration_result)
    return migration_result

The guard decision drives the flow: 'block' returns early, 'require_approval' pauses for a human click on /approvals, 'allow' proceeds straight to execution.

Register the governed tool on your Pydantic AI agent

Pass the governed function in the tools list: Pydantic AI builds the tool schema from the signature and docstring; the governance loop runs on every model-initiated call.

agent.py

# Register the governed function as a Pydantic AI tool — the governance
# loop runs identically when the model invokes it.
from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    tools=[governed_run_migration],
    instructions='You manage database migrations. Use the tool to run them.',
)

result = agent.run_sync('Apply the add-indexes migration to staging')
print(result.output)

# For tests: override the model with TestModel — it exercises the full
# agent loop, tools included, without an LLM API key.
#
#   from pydantic_ai.models.test import TestModel
#   with agent.override(model=TestModel()):
#       agent.run_sync('Apply the add-indexes migration to staging')

Run the governed example

Execute the example and watch the governance flow: a staging migration (allowed) and a production migration (may require approval).

Terminal

python main.py

No LLM API key needed: the example runs the governance flow directly. Only the DashClaw SDK calls are real.

Clone the full example

The complete runnable example is in the DashClaw repo.

Terminal

git clone https://github.com/ucsandman/DashClaw.git
cd DashClaw/examples/pydantic-ai-governed
pip install -r requirements.txt
python main.py

What success looks like

Go to /decisions: you should see two actions in the ledger with action_type 'database_migration', agent_id 'pydantic-ai-db-agent': the staging migration completed, and the production migration either completed (after approval) or pending.

Navigate to /decisions in your DashClaw instance. Your action should appear in the ledger within seconds of the agent run.

Governance as Code

guardrails.yml is a policy-as-code template. Import it into your instance — POST the YAML to /api/policies/importor call the Python SDK's import_policies — and DashClaw evaluates these rules at the guard step before any action executes.

guardrails.yml

version: 1
project: my-pydantic-ai-agent
description: >
  Governance policy for a Pydantic AI database agent.
  Production migrations require approval.
  Staging migrations are auto-allowed.

policies:
  - id: approve_production_migrations
    description: Production database migrations require human approval
    applies_to:
      action_types:
        - database_migration
      systems:
        - postgres
    rule:
      require: approval

  - id: allow_staging
    description: Staging migrations are low risk
    applies_to:
      action_types:
        - database_migration
    rule:
      allow: true