---
id: pydantic-ai-shields
version: "0.3.4"
license: MIT
license_treatment: permissive
maintenance: active
---

# pydantic-ai-shields — Guardrail capabilities for Pydantic AI — cost tracking, tool permissions, input/output guards

License: permissive · Maintenance: active · Downloads: 536.3K/mo

## What it is and what it does

Pydantic AI Shields is a library of ready-to-use guardrail capabilities that integrate directly into Pydantic AI agents without middleware wrappers. It provides infrastructure shields (cost tracking with budget enforcement, tool access control, custom input/output validation, and concurrent guardrail execution) and content shields (prompt injection detection across 6 categories, PII detection for email/phone/SSN/credit card/IP, secret redaction for API keys and tokens, blocked keyword filtering, and LLM refusal blocking).

You compose shields by passing them to an agent's `capabilities` parameter. Each shield raises a specific exception (InputBlocked, OutputBlocked, ToolBlocked, BudgetExceededError) when its guard condition fails. CostTracking auto-detects pricing from genai-prices; PromptInjection supports three sensitivity levels; PiiDetector and SecretRedaction use regex patterns; AsyncGuardrail can cancel LLM calls if guards fail first, saving cost. The library targets Pydantic AI agents and depends on pydantic-ai-slim and pydantic.

Use it for:

- Enforce per-agent or per-run spending limits and track cumulative token costs across multiple LLM calls.
- Prevent agents from calling dangerous or sensitive tools without user approval or hide them entirely from the model.
- Detect and block prompt injection attempts, jailbreaks, and role-play exploits before they reach the LLM.
- Scan user input for PII (email, phone, SSN, credit card, IP) and block or log detections without stopping execution.
- Redact API keys, tokens, and credentials from model output to prevent accidental secret leakage.
- Run safety checks concurrently with LLM inference and cancel the LLM call if a guard fails, reducing wasted API costs.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Pydantic AI Shields provides guardrail capabilities for Pydantic AI agents, including cost tracking, prompt injection detection, PII detection, secret redaction, tool permissions, and async guardrails.

Yes, if you are building Pydantic AI agents and need safety, cost control, or tool permission guardrails. The library is actively maintained, has low install friction, and composes naturally into agent capabilities. MIT license has no restrictions. Start with it if you need any of its built-in shields; the modular design lets you add only what you need. No known vulnerabilities.

## Install

pip install pydantic-ai-shields
uv add pydantic-ai-shields
poetry add pydantic-ai-shields

## Installing pydantic-ai-shields

Before you install: Low install friction with a pure-Python wheel. Active maintenance (last commit 2026-08-14) and recent release cycle. Depends on pydantic-ai-slim and pydantic, both standard ecosystem packages.

License in practice: MIT license permits unrestricted use, modification, and distribution with minimal obligations—suitable for commercial and open-source projects.

Quickstart:

pip install pydantic-ai-shields

from pydantic_ai import Agent
from pydantic_ai_shields import CostTracking, ToolGuard, InputGuard

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[
        CostTracking(budget_usd=5.0),
        ToolGuard(blocked=["execute"], require_approval=["write_file"]),
        InputGuard(guard=lambda prompt: "ignore all instructions" not in prompt.lower()),
    ],
)

result = await agent.run("Hello!")

Requires Python 3.10 or later. Pricing auto-detection for CostTracking uses genai-prices; custom pricing may be needed for models not in that database.

Verify before relying:

- Whether genai-prices covers all LLM providers and models you intend to use, or if custom pricing configuration is required.
- Performance overhead of concurrent guardrails (AsyncGuardrail with timing='concurrent') under high-throughput agent workloads.
- Accuracy and false-positive rates of built-in detectors (PromptInjection, PiiDetector, SecretRedaction) on real-world prompts.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 536.3K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

pydantic ai guardrails, cost tracking for llm agents, prompt injection detection, pii detection and redaction, tool permission control, ai safety guardrails, agent input output validation, guardrails, cost-control, safety-checks

[View on SkillFed](https://skillfed.io/packages/pydantic-ai-shields) · [View on PyPI](https://pypi.org/project/pydantic-ai-shields/)