agent-governance

Files (6)

• SKILL.md
• openai.yaml · agents/
• evals.json · evals/
• trigger-queries.json · evals/
• framework-integration.md · references/
• policy-patterns.md · references/

SKILL.md (first lines)

# 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

1. Determine the governance level (open, standard, strict, or locked) based on the use case risk.
2. Define the `GovernancePolicy` with allowed tools, blocked patterns, and rate limits.
3. Apply the `@govern` decorator to tool functions.
4. 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`](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

1. Classify risk level: open, standard, strict, or locked for the agent and its tools.
2. Inventory tools the agent can call and the sensitive actions among them.
3. Define a `GovernancePolicy` (allowed tools, blocked patterns, rate limits, human-approval needs).
4. Read [`references/policy-patterns.md`](references/policy-patterns.md) for the control set that matches the risk level.
5. Implement enforcement at the tool boundary (`@govern` or framework-equivalent middleware).
6. Add intent classification when prompt-level danger detection is required.
7. Wire append-only audit logging for allowed, denied, and error events.
8. For multi-agent setups, add trust scoring before privileged tool access.
9. Integrate with the target framework using [`references/framework-integration.md`](references/framework-integration.md).
10. 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

```markdown
### 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`](references/policy-patterns.md) for full Python code for each governance component and framework-specific wiring.

## Reference files

From matt-riley/agent-skills, GPL-3.0.

More from matt-riley/agent-skills