Pydantic AI Quickstart

​

Install

pip install "visiq>=0.4.0" "pydantic-ai>=1.107"

​

Set environment variables

VISIQ_API_KEY=vq_prod_...
# VISIQ_ENDPOINT defaults to https://api.visiqlabs.com. Set it ONLY for
# onprem / self-hosted deployments. A bare VISIQ_API_KEY reaches the managed
# SaaS control plane, loads a bundle, and governs automatically.
VISIQ_AGENT_ID=support-bot

​

Govern your agent

from pydantic_ai import Agent
from visiq import govern  # pip install visiq


def issue_refund(customer_id: str, amount: int) -> str:
    """Issue a refund to a customer."""
    return f"Refunded ${amount} to {customer_id}"


def search_knowledge(query: str) -> list:
    """Search the knowledge base."""
    # Your real RAG store returns the same shape: a list of
    # {"page_content", "metadata"} dicts the retrieval facet can filter.
    return [
        {"page_content": f"Q3 revenue was $4.2M. (matched: {query})",
         "metadata": {"classification": "internal"}},
    ]


agent = Agent(
    "openai:gpt-4o",
    system_prompt="You are a helpful assistant.",
    tools=[issue_refund, search_knowledge],
)

# ── One call: every tool on this agent is now governed ──
govern(agent, agent_id="support-bot", retrieval_tools={"search_knowledge"})

print(agent.run_sync("What was Q3 revenue?").output)

from visiq.pydantic_ai import VisiqGovernance

agent = Agent(
    "openai:gpt-4o",
    tools=[issue_refund, search_knowledge],
    capabilities=[VisiqGovernance(agent_id="support-bot",
                                  retrieval_tools={"search_knowledge"})],
)

​

Run this on AWS Bedrock

pip install "pydantic-ai-slim[bedrock]"

from pydantic_ai import Agent
from pydantic_ai.models.bedrock import BedrockConverseModel

from visiq import govern

agent = Agent(
    BedrockConverseModel("amazon.nova-micro-v1:0"),
    system_prompt="You are a helpful assistant.",
    tools=[issue_refund, search_knowledge],
)
govern(agent, agent_id="support-bot", retrieval_tools={"search_knowledge"})

​

What happens at runtime

• Decisions are local. The SDK fetches one cached rule bundle (GET /rules/bundle, ETag revalidation) and refreshes it in the background. Tool calls evaluate in-process; the only decision-path network call is waiting on a human approval.
• Fail-open by default, loudly — strict deny is opt-in. Real policy outcomes always enforce: an explicit rule deny, the operator kill-switch, and an in-core mask/redact that cannot be applied (it downgrades to deny) all block. A harness-internal failure does NOT block: if the backend is unreachable or the governance core is unavailable, the harness proceeds UNGOVERNED with a loud [VisIQ] FAIL-OPEN (no-bundle) report on stderr, so a VisIQ outage never disrupts your agent (owner decision, 2026-07-15). Set VISIQ_FAIL_MODE=closed to block those harness-internal failures instead.
• Deny blocks the call. The tool is never executed, and the model receives the block message as the tool result.
• Approvals pause the call. An approval_required decision holds the tool while a human decides via Slack or Email (Microsoft Teams delivery is built server-side; its connector card is coming soon) — the SDK polls for up to 120 seconds (VISIQ_HITL_TIMEOUT_MS), then fails closed.
• Mask proceeds, redacted. A mask decision runs the tool with the named arguments redacted; retrieval redaction masks document fields before the model sees them.

​

Verify it’s working

• Control Agents → Agents — your agent appears automatically (monitor mode) with a live last-seen heartbeat.
• Control Agents → Runtime Enforcement — a decision row for every governed tool call, with the matched rule and outcome.

​

Next steps