# Pydantic AI Shields — Guardrails for Pydantic AI

> Drop-in guardrail capabilities for Pydantic AI agents: cost budgets, tool permissions, and input/output guards; verified 63★, pushed 2026-05-05.

## Install

Copy the content below into your project:

## Quick Use

```bash
pip install pydantic-ai-shields
python -c "import pydantic_ai_shields; print('pydantic-ai-shields ready')"
# Use in an agent (see README Quick Start):
# from pydantic_ai_shields import CostTracking, ToolGuard, InputGuard
```

## Intro

Drop-in guardrail capabilities for Pydantic AI agents: cost budgets, tool permissions, and input/output guards; verified 63★, pushed 2026-05-05.

**Best for:** Pydantic AI users who want safety + budget controls as first-class capabilities (not ad hoc wrappers)

**Works with:** Python 3.10+ and Pydantic AI agents using the capabilities API

**Setup time:** 8-15 minutes

### Key facts (verified)

- GitHub: 63 stars · 10 forks · pushed 2026-05-05.
- License: MIT · owner avatar + repo URL verified via GitHub API.
- README-backed entrypoint: `python -c "import pydantic_ai_shields; print('pydantic-ai-shields ready')"`.

## Main

- Budgeting by default: add `CostTracking(budget_usd=...)` to stop runaway agent loops and to record total tokens/cost per run.

- Tool permissions: use `ToolGuard(blocked=[...], require_approval=[...])` so unsafe tools never appear (or require explicit approval).

- Input/output controls: `InputGuard` blocks risky user prompts early; `OutputGuard` can enforce redaction or policy checks post-run.

- Prefer incremental rollout: start with cost tracking + tool allowlist, then add input/output guards for the highest-risk surfaces.

### Source-backed notes

- README shows `pip install pydantic-ai-shields` and a Quick Start example using `CostTracking`, `ToolGuard`, and `InputGuard` capabilities.
- README describes `CostTracking` as tracking tokens/cost with optional budget enforcement and raising `BudgetExceededError`.
- README explains `ToolGuard` supports blocking tools entirely and requiring approvals via a callback.

### FAQ

- **Is this a full agent framework?**: No — README positions it as drop-in capabilities for Pydantic AI, not a separate agent runtime.
- **Can I block a tool completely?**: Yes — README shows `ToolGuard(blocked=[...])` removes tools from the model’s tool list.
- **What’s the first guardrail to add?**: Cost tracking + tool permissions; then add input/output guards for your highest-risk prompts.

## Source & Thanks

> Source: https://github.com/vstorm-co/pydantic-ai-shields
> License: MIT
> GitHub stars: 63 · forks: 10

---

<!-- ZH -->

## Quick Use

```bash
pip install pydantic-ai-shields
python -c "import pydantic_ai_shields; print('pydantic-ai-shields ready')"
# Use in an agent (see README Quick Start):
# from pydantic_ai_shields import CostTracking, ToolGuard, InputGuard
```

## Intro

为 Pydantic AI agent 提供可直接插入的护栏 capabilities：成本预算、工具权限、输入/输出拦截等，不用额外中间件包装；已验证 63★，更新于 2026-05-05。

**Best for:** 使用 Pydantic AI 并希望把安全/预算控制做成一等能力（而不是临时 wrapper）的团队

**Works with:** Python 3.10+ 与 Pydantic AI 的 capabilities API

**Setup time:** 8-15 minutes

### Key facts (verified)

- GitHub：63 stars · 10 forks；最近更新 2026-05-05。
- 许可证：MIT；作者头像与仓库链接均已通过 GitHub API 复核。
- README 中可对照的入口命令：`python -c "import pydantic_ai_shields; print('pydantic-ai-shields ready')"`。

## Main

- 先把预算控住：用 `CostTracking(budget_usd=...)` 记录 tokens/成本，并在超预算时中止，避免 agent 死循环烧钱。

- 工具权限最关键：`ToolGuard(blocked=[...], require_approval=[...])` 让危险工具“根本不出现在模型视野里”或强制审批。

- 输入/输出护栏：`InputGuard` 提前拦截高风险提示词；`OutputGuard` 在输出阶段做敏感信息/策略检查。

- 建议分阶段接入：先成本 + 工具白名单，再逐步加输入/输出护栏覆盖最危险的入口。

### Source-backed notes

- README 给出 `pip install pydantic-ai-shields`，并在 Quick Start 中演示 `CostTracking`、`ToolGuard`、`InputGuard`。
- README 说明 `CostTracking` 可统计 tokens/成本并在超预算时触发 `BudgetExceededError`。
- README 解释 `ToolGuard` 可彻底隐藏被 block 的工具，或在调用前通过回调执行审批。

### FAQ

- **这是完整的 agent 框架吗？**：不是；README 把它定位为 Pydantic AI 的可插拔 capabilities，而不是另起一套 runtime。
- **能彻底禁用某些工具吗？**：可以；README 展示 `ToolGuard(blocked=[...])` 会把工具从模型工具列表中移除。
- **第一步该加什么护栏？**：先加成本统计/预算与工具权限控制，再按风险逐步加输入/输出护栏。

## Source & Thanks

> Source: https://github.com/vstorm-co/pydantic-ai-shields
> License: MIT
> GitHub stars: 63 · forks: 10


---
Source: https://tokrepo.com/en/workflows/pydantic-ai-shields-guardrails-for-pydantic-ai
Author: Agent Toolkit