pydantic-ai-toolguard 0.1.0

Deny-first tool authorization for pydantic-ai agents — by AgentsID

pydantic-ai-toolguard

Deny-first tool authorization for pydantic-ai agents — by AgentsID.

Implements the AgentsID Permission Specification: glob-based tool patterns, parameter conditions, schedule windows, rate limiting, approval workflows, and an append-only audit log.

Install

pip install pydantic-ai-toolguard

Quick Start

from pydantic_ai import Agent
from pydantic_ai_toolguard import ToolGuard, PermissionRule

guard = ToolGuard(rules=[
    PermissionRule(tool_pattern="delete_*", action="deny"),
    PermissionRule(tool_pattern="*", action="allow"),
])

agent = Agent("openai:gpt-5.2", capabilities=[guard])

The guard hides denied tools from the model and blocks execution if a denied tool is somehow called. Every decision is recorded in the audit log.

How It Works

Rules are evaluated deny-first:

1. DENY rules checked first — first matching deny = blocked
2. ALLOW rules checked second — first matching allow = permitted (subject to rate limits, schedule, approval)
3. Default DENY — no matching rule = blocked

This integrates via three pydantic-ai capability hooks:

• prepare_tools — filters denied tools out of the model's view
• before_tool_execute — evaluates permissions before execution
• after_tool_execute — records the result

Features

Glob Pattern Matching

PermissionRule(tool_pattern="*", action="allow")         # all tools
PermissionRule(tool_pattern="db_*", action="deny")        # prefix match
PermissionRule(tool_pattern="*_readonly", action="allow")  # suffix match

Parameter Conditions

PermissionRule(
    tool_pattern="query_db",
    action="deny",
    conditions={"env": "production"},  # only deny production queries
)

Schedule Windows

from pydantic_ai_toolguard import ScheduleConfig

PermissionRule(
    tool_pattern="deploy_*",
    action="allow",
    schedule=ScheduleConfig(
        hours_start=9, hours_end=17,
        timezone="US/Pacific",
        days=("mon", "tue", "wed", "thu", "fri"),
    ),
)

Rate Limiting

from pydantic_ai_toolguard import RateLimitConfig

PermissionRule(
    tool_pattern="search_*",
    action="allow",
    rate_limit=RateLimitConfig(max=10, per="minute"),
)

Approval Workflows

async def ask_user(tool: str, rule: PermissionRule) -> bool:
    return input(f"Allow {tool}? (y/n) ") == "y"

guard = ToolGuard(
    rules=[PermissionRule(tool_pattern="transfer_*", action="allow", requires_approval=True)],
    on_approval=ask_user,
)

Audit Log

guard = ToolGuard(rules=[...])

# After agent runs...
for entry in guard.audit_log.query(decision="denied"):
    print(f"{entry.timestamp} — {entry.tool}: {entry.reason}")

# Export as JSON
print(guard.audit_log.export_json())

Configuration

Parameter	Type	Default	Description
rules	Sequence[PermissionRule]	required	Permission rules
on_approval	async (str, PermissionRule) -> bool	None	Approval callback
hide_denied	bool	True	Remove denied tools from model view
log_decisions	bool	True	Record to audit log
deny_message	str	"Permission denied: {reason}"	Message returned to model on deny

Links

• AgentsID — Identity and auth for AI agents
• Permission Specification
• AgentsID Scanner — Security scanner for MCP servers
• pydantic-ai Capabilities

License

MIT