Skip to content

Exceptions

All shield exceptions inherit from GuardrailError.

Exception Raised by
InputBlocked InputGuard, PromptInjection, PiiDetector, BlockedKeywords
OutputBlocked OutputGuard, SecretRedaction, NoRefusals
ToolBlocked ToolGuard
BudgetExceededError CostTracking
PricingError CostTracking(strict=True)

Guardrail capabilities for pydantic-ai agents.

Ready-to-use capabilities for safety, cost control, and permission management. Built on pydantic-ai's native capabilities API.

Example
Python
from pydantic_ai import Agent
from pydantic_ai_shields import CostTracking, ToolGuard

agent = Agent(
    "openai:gpt-4.1",
    capabilities=[
        CostTracking(budget_usd=5.0),
        ToolGuard(blocked=["execute"], require_approval=["write_file"]),
    ],
)

GuardrailError

Bases: Exception

Base exception for guardrail violations.

Source code in src/pydantic_ai_shields/guardrails.py
Python
42
43
class GuardrailError(Exception):
    """Base exception for guardrail violations."""

InputBlocked

Bases: GuardrailError

Raised when user input is blocked by a guardrail.

Source code in src/pydantic_ai_shields/guardrails.py
Python
46
47
class InputBlocked(GuardrailError):
    """Raised when user input is blocked by a guardrail."""

OutputBlocked

Bases: GuardrailError

Raised when model output is blocked by a guardrail.

Source code in src/pydantic_ai_shields/guardrails.py
Python
50
51
class OutputBlocked(GuardrailError):
    """Raised when model output is blocked by a guardrail."""

ToolBlocked

Bases: GuardrailError

Raised when a tool call is blocked by a guardrail.

Source code in src/pydantic_ai_shields/guardrails.py
Python
54
55
56
57
58
59
60
61
62
63
class ToolBlocked(GuardrailError):
    """Raised when a tool call is blocked by a guardrail."""

    def __init__(self, tool_name: str, reason: str = ""):
        self.tool_name = tool_name
        self.reason = reason
        msg = f"Tool '{tool_name}' blocked"
        if reason:
            msg += f": {reason}"
        super().__init__(msg)

BudgetExceededError

Bases: GuardrailError

Raised when cost budget is exceeded.

Source code in src/pydantic_ai_shields/guardrails.py
Python
66
67
68
69
70
71
72
class BudgetExceededError(GuardrailError):
    """Raised when cost budget is exceeded."""

    def __init__(self, total_cost: float, budget: float):
        self.total_cost = total_cost
        self.budget = budget
        super().__init__(f"Budget exceeded: ${total_cost:.4f} > ${budget:.4f}")

PricingError

Bases: GuardrailError

Raised when cost calculation fails (strict mode only).

Attributes:

Name Type Description
model_name

The model name that failed to resolve.
Source code in src/pydantic_ai_shields/guardrails.py
Python
75
76
77
78
79
80
81
82
83
84
class PricingError(GuardrailError):
    """Raised when cost calculation fails (strict mode only).

    Attributes:
        model_name: The model name that failed to resolve.
    """

    def __init__(self, model_name: str):
        self.model_name = model_name
        super().__init__(f"Failed to resolve price for model '{model_name}'")