Agent Governance Patterns
Patterns for adding safety, trust, and policy enforcement to AI agent systems.
Use this skill when
- Building AI agents that call external tools (APIs, databases, file systems)
- Implementing policy-based access controls for agent tool usage
- Adding semantic intent classification to detect dangerous prompts
- Creating trust scoring systems for multi-agent workflows
- Building audit trails for agent actions and decisions
- Enforcing rate limits, content filters, or tool restrictions on agents
- Working with any agent framework (PydanticAI, CrewAI, OpenAI Agents, LangChain, AutoGen)
Do not use this skill when
- The agent runs in a fully trusted environment with no external tool access and no compliance requirements.
- You only need static code analysis or security review of agent source code; this skill provides runtime governance patterns, not static audit tools.
Inputs to gather
Required before implementing
- The agent framework in use (PydanticAI, CrewAI, OpenAI Agents SDK, etc.)
- The list of tools the agent calls.
- The risk level for the use case (internal dev, standard production, compliance-critical).
Helpful if present
- Existing policy config files or security review requirements.
- Whether human-in-the-loop approval is needed for any tool.
First move
- Determine the governance level (open, standard, strict, or locked) based on the use case risk.
- Define the
GovernancePolicy with allowed tools, blocked patterns, and rate limits.
- Apply the
@govern decorator to tool functions.
- Wire up the
AuditTrail for compliance logging.
Governance patterns
Select the smallest control set that meets the risk level, then read references/policy-patterns.md for the implementation details:
- Governance policy and YAML configuration
- Semantic intent classification
- Tool-level governance decorators
- Trust scoring
- Append-only audit trails
- PydanticAI, CrewAI, and OpenAI Agents SDK integration
- Governance-level selection and best practices
Load the reference when implementing or comparing controls. Keep audit-only, guardrail, and full-governance modes distinct, and layer policies from broad defaults to task-specific restrictions.
Outputs
- Policy, allowlists, trust scoring, or audit trail changes implemented with clear boundaries and tests or validation steps.
- Runtime governance behavior documented or demonstrated.
Workflow
- Classify risk level: open, standard, strict, or locked for the agent and its tools.
- Inventory tools the agent can call and the sensitive actions among them.
- Define a
GovernancePolicy (allowed tools, blocked patterns, rate limits, human-approval needs).
- Read
references/policy-patterns.md for the control set that matches the risk level.
- Implement enforcement at the tool boundary (
@govern or framework-equivalent middleware).
- Add intent classification when prompt-level danger detection is required.
- Wire append-only audit logging for allowed, denied, and error events.
- For multi-agent setups, add trust scoring before privileged tool access.
- Integrate with the target framework using
references/framework-integration.md.
- Validate fail-closed behavior: blocked tools deny, rate limits fire, audit events exist, and secrets never appear in logs.
Guardrails
- Must not allow tool calls to proceed when a governance check errors; fail closed.
- Must not store or log secret values; only confirm whether expected policy names and scopes are present.
- Should compose policies with most-restrictive-wins semantics when layering org, team, and agent policies.
- Should keep governance enforcement independent of agent business logic.
- Should use append-only audit entries; never modify or delete them.
Validation
Apply the implementation checklist after wiring governance into an agent:
- Blocked tools raise
PermissionError with the correct policy name
- Content filters catch the blocked patterns before tool execution occurs
- Rate limit counts calls correctly and denies at the configured threshold
- Audit trail captures allowed, denied, and error events for every tool call
- Policy composition uses most-restrictive-wins semantics when layers are combined
### Implementation checklist
- [ ] Define governance policy (allowed tools, blocked patterns, rate limits)
- [ ] Choose governance level (open/standard/strict/locked)
- [ ] Add @govern decorator to all tool functions
- [ ] Add intent classification to user input processing
- [ ] Implement trust scoring for multi-agent interactions
- [ ] Wire up audit trail export
- [ ] Test that blocked tools are properly denied
- [ ] Test that content filters catch sensitive patterns
- [ ] Test rate limiting behavior
- [ ] Verify audit trail captures all events
- [ ] Test policy composition (most-restrictive-wins)
- Smoke test:
- should trigger: "Add tool allowlists and audit logs to this coding agent."
- should not trigger: "Generate a SHA-256 manifest for this plugin bundle." (→
agent-supply-chain)
Examples
Select the governance controls appropriate for the risk level of the agent:
- Internal dev agent — audit-only mode, no restrictions: create an
AuditTrail and log events without blocking any calls.
- Standard production agent — allowlist + content filters + rate limiting: use
GovernancePolicy with allowed_tools, blocked_patterns, and max_calls_per_request.
- Compliance-critical agent — all controls + human approval: add
require_human_approval for sensitive tool operations such as send_email or write_report.
See references/policy-patterns.md for full Python code for each governance component and framework-specific wiring.
Reference files
references/policy-patterns.md — governance policy, classifier, decorator, trust, audit, and governance-level implementation patterns
references/framework-integration.md — framework-specific integration notes for PydanticAI, CrewAI, OpenAI Agents SDK, LangChain, and AutoGen
1---2name: agent-governance3description: "Use this skill when building AI agents that call external tools, implementing policy-based access controls, adding semantic intent classification, creating trust scoring systems, building audit trails, or enforcing rate limits and content filters on agents."4license: GNU GPL v35metadata:6 source: https://skillmd.com/skills/matt-riley/agent-governance7 version: 1.1.1 # x-release-please-version8 category: workflow9 audience: general-coding-agent10 maturity: draft11 kind: task12---1314# Agent Governance Patterns1516Patterns for adding safety, trust, and policy enforcement to AI agent systems.1718## Use this skill when1920- Building AI agents that call external tools (APIs, databases, file systems)21- Implementing policy-based access controls for agent tool usage22- Adding semantic intent classification to detect dangerous prompts23- Creating trust scoring systems for multi-agent workflows24- Building audit trails for agent actions and decisions25- Enforcing rate limits, content filters, or tool restrictions on agents26- Working with any agent framework (PydanticAI, CrewAI, OpenAI Agents, LangChain, AutoGen)2728## Do not use this skill when2930- The agent runs in a fully trusted environment with no external tool access and no compliance requirements.31- You only need static code analysis or security review of agent source code; this skill provides runtime governance patterns, not static audit tools.3233## Inputs to gather3435**Required before implementing**3637- The agent framework in use (PydanticAI, CrewAI, OpenAI Agents SDK, etc.)38- The list of tools the agent calls.39- The risk level for the use case (internal dev, standard production, compliance-critical).4041**Helpful if present**4243- Existing policy config files or security review requirements.44- Whether human-in-the-loop approval is needed for any tool.4546## First move47481. Determine the governance level (open, standard, strict, or locked) based on the use case risk.492. Define the `GovernancePolicy` with allowed tools, blocked patterns, and rate limits.503. Apply the `@govern` decorator to tool functions.514. Wire up the `AuditTrail` for compliance logging.5253## Governance patterns5455Select the smallest control set that meets the risk level, then read [`references/policy-patterns.md`](references/policy-patterns.md) for the implementation details:5657- Governance policy and YAML configuration58- Semantic intent classification59- Tool-level governance decorators60- Trust scoring61- Append-only audit trails62- PydanticAI, CrewAI, and OpenAI Agents SDK integration63- Governance-level selection and best practices6465Load the reference when implementing or comparing controls. Keep audit-only, guardrail, and full-governance modes distinct, and layer policies from broad defaults to task-specific restrictions.6667## Outputs6869- Policy, allowlists, trust scoring, or audit trail changes implemented with clear boundaries and tests or validation steps.70- Runtime governance behavior documented or demonstrated.7172## Workflow73741. Classify risk level: open, standard, strict, or locked for the agent and its tools.752. Inventory tools the agent can call and the sensitive actions among them.763. Define a `GovernancePolicy` (allowed tools, blocked patterns, rate limits, human-approval needs).774. Read [`references/policy-patterns.md`](references/policy-patterns.md) for the control set that matches the risk level.785. Implement enforcement at the tool boundary (`@govern` or framework-equivalent middleware).796. Add intent classification when prompt-level danger detection is required.807. Wire append-only audit logging for allowed, denied, and error events.818. For multi-agent setups, add trust scoring before privileged tool access.829. Integrate with the target framework using [`references/framework-integration.md`](references/framework-integration.md).8310. Validate fail-closed behavior: blocked tools deny, rate limits fire, audit events exist, and secrets never appear in logs.8485## Guardrails8687- **Must not** allow tool calls to proceed when a governance check errors; fail closed.88- **Must not** store or log secret values; only confirm whether expected policy names and scopes are present.89- **Should** compose policies with most-restrictive-wins semantics when layering org, team, and agent policies.90- **Should** keep governance enforcement independent of agent business logic.91- **Should** use append-only audit entries; never modify or delete them.9293## Validation9495Apply the implementation checklist after wiring governance into an agent:9697- Blocked tools raise `PermissionError` with the correct policy name98- Content filters catch the blocked patterns before tool execution occurs99- Rate limit counts calls correctly and denies at the configured threshold100- Audit trail captures allowed, denied, and error events for every tool call101- Policy composition uses most-restrictive-wins semantics when layers are combined102103```markdown104### Implementation checklist105- [ ] Define governance policy (allowed tools, blocked patterns, rate limits)106- [ ] Choose governance level (open/standard/strict/locked)107- [ ] Add @govern decorator to all tool functions108- [ ] Add intent classification to user input processing109- [ ] Implement trust scoring for multi-agent interactions110- [ ] Wire up audit trail export111- [ ] Test that blocked tools are properly denied112- [ ] Test that content filters catch sensitive patterns113- [ ] Test rate limiting behavior114- [ ] Verify audit trail captures all events115- [ ] Test policy composition (most-restrictive-wins)116```117118- Smoke test:119 - should trigger: "Add tool allowlists and audit logs to this coding agent."120 - should not trigger: "Generate a SHA-256 manifest for this plugin bundle." (→ `agent-supply-chain`)121122## Examples123124Select the governance controls appropriate for the risk level of the agent:125126- **Internal dev agent** — audit-only mode, no restrictions: create an `AuditTrail` and log events without blocking any calls.127- **Standard production agent** — allowlist + content filters + rate limiting: use `GovernancePolicy` with `allowed_tools`, `blocked_patterns`, and `max_calls_per_request`.128- **Compliance-critical agent** — all controls + human approval: add `require_human_approval` for sensitive tool operations such as `send_email` or `write_report`.129130See [`references/policy-patterns.md`](references/policy-patterns.md) for full Python code for each governance component and framework-specific wiring.131132## Reference files133134- [`references/policy-patterns.md`](references/policy-patterns.md) — governance policy, classifier, decorator, trust, audit, and governance-level implementation patterns135- [`references/framework-integration.md`](references/framework-integration.md) — framework-specific integration notes for PydanticAI, CrewAI, OpenAI Agents SDK, LangChain, and AutoGen