Tool Governance

Tool governance policies control which tools an agent may call and how often. This covers two policy types: Tool ACL (allowlist/denylist) and Rate Limit (call frequency).

Tool ACL

Allowlist mode

Deny all tools except those matching an approved pattern list.

from pavri import secure, PavriConfig

agent = secure(agent, config=PavriConfig(
    policies=["prod-tool-guard"],
    fail_mode="closed",
))

When the prod-tool-guard policy has mode: allowlist and patterns: ["tool:http.gateway.*", "tool:billing.customer.query"], only those tools are permitted. Everything else raises PolicyDeniedError.

Denylist mode

Allow all tools except those matching a blocked pattern list. Useful when you want to block a small set of dangerous tools.

Pattern syntax

Tool selectors use glob matching via fnmatch:

Pattern	Matches
tool:*	All tools
tool:http.*	All HTTP tools
tool:db_read	Exact match
tool:mcp.*.write	Any MCP write tool

SDK behavior

When a tool call is denied:

1. The plugin's enforcement hook calls enforce_policy("tool:{name}", ctx).
2. The ToolAclEvaluator checks the tool name against the pattern list.
3. On denial, PolicyDeniedError is raised with the matched rule and reason.
4. The framework plugin converts this into a framework-native error:
   • LangGraph: exception in invoke
   • CrewAI: before-hook returns False
   • OpenAI Agents: guardrail triggers
   • Generic: check_policy() raises

Rate Limit

How it works

A sliding-window counter tracks tool call timestamps. When calls within the window exceed the threshold, subsequent calls receive a throttle decision.

Default parameters:

• max_calls_per_minute: 60
• window_seconds: 60

Configuration

Create a Rate Limit policy in the dashboard or via the API:

curl -X POST https://api.pavri.ai/api/policies \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-rate-guard",
    "type": "Rate Limit",
    "enforcementMode": "Active"
  }'

What happens on throttle

The SDK's TokenBucketThrottler tracks token availability. When exhausted:

1. A policy_eval telemetry event is emitted.
2. PolicyDeniedError is raised with action throttle.
3. The pavri_policy_denials_total Prometheus counter increments.

The agent receives a structured error it can handle — retry after a delay, fall back to a cached result, or terminate gracefully.

Observability

Both tool ACL and rate limit decisions emit Prometheus metrics:

• pavri_policy_evaluations_total{result, policy_type} — counts every evaluation
• pavri_policy_evaluation_duration_seconds — evaluation latency
• pavri_policy_denials_total{rule_type} — counts denials

These are exposed on the SDK's metrics registry and on the policy service's /metrics endpoint.