FAI Agent Governance

Review agent implementations before they ship. This skill covers tool allowlists, approval boundaries, token budgets, audit trails, escalation paths, and the evidence needed to sign off a production agent.

Governance Scope

A governed agent should answer five questions clearly:

Phase 1: Inventory the Agent Surface

Start by collecting the files that define agent behavior.

Get-ChildItem .github/agents -Filter *.agent.md | Select-Object Name
Get-ChildItem .github/hooks -Filter *.json | Select-Object Name
Get-ChildItem config -Filter *.json | Select-Object Name

Read the agent file and capture:

• declared tools
• model list and fallback order
• references to skills, prompts, or hooks
• instructions about production actions, secrets, or approvals

Phase 2: Validate Tool and Action Boundaries

Every high-risk action needs a hard boundary, not just a polite instruction.

Example agent frontmatter with bounded tools:

---
description: "Builds and validates a solution play implementation"
model: ["gpt-4o", "gpt-4o-mini"]
tools: ["codebase", "terminal"]
---

If an agent asks for broad tools such as unrestricted shell plus deployment plus secret access, treat that as a governance finding until the boundaries are narrowed.

Phase 3: Check Token and Iteration Budgets

Agents fail operationally when they can loop forever, retry endlessly, or silently route all work to expensive models.

{
  "agentGovernance": {
    "maxIterations": 6,
    "maxRetriesPerTool": 3,
    "requestTimeoutSeconds": 90,
    "tokenBudget": {
      "builder": 60000,
      "reviewer": 25000,
      "tuner": 15000
    },
    "requiresApprovalFor": ["production-deploy", "delete-resource", "read-secret"]
  }
}

Audit checks:

• Every loop has a max iteration count.
• Every external call has retry and timeout bounds.
• Expensive models are deliberate, not default everywhere.
• Budget overrun behavior is defined: stop, fallback, or escalate.

Phase 4: Require Human Escalation for Sensitive Paths

Use a lightweight policy file when the agent crosses trust boundaries.

{
  "approvalPolicy": {
    "humanRequired": [
      "deploy:prod",
      "rotate:key-vault-secret",
      "delete:resource-group",
      "disable:guardrail"
    ],
    "notify": ["security-team", "platform-team"],
    "recordAuditEvent": true
  }
}

Your governance review should fail if the agent can perform these operations directly with no approval checkpoint.

Phase 5: Produce a Governance Scorecard

Use a repeatable scorecard so every agent is judged the same way.

from dataclasses import dataclass

@dataclass
class GovernanceFinding:
    category: str
    severity: str
    message: str
    remediation: str


def review_agent(agent_text: str) -> list[GovernanceFinding]:
    findings = []
    if "tools:" not in agent_text:
        findings.append(GovernanceFinding(
            category="tool-boundary",
            severity="high",
            message="Agent does not declare an explicit tool list.",
            remediation="Add a minimal tools allowlist in the frontmatter.",
        ))
    if "gpt-4o" in agent_text and "gpt-4o-mini" not in agent_text:
        findings.append(GovernanceFinding(
            category="cost-control",
            severity="medium",
            message="Primary model has no cheaper fallback.",
            remediation="Add a fallback model or routing policy for low-risk tasks.",
        ))
    if "approval" not in agent_text.lower():
        findings.append(GovernanceFinding(
            category="human-in-the-loop",
            severity="high",
            message="No approval or escalation language found for sensitive actions.",
            remediation="Add approval boundaries and hook enforcement for risky operations.",
        ))
    return findings

Governance Report Format

# Agent Governance Review

## Summary
- Agent: fai-example-builder
- Verdict: CONDITIONAL_PASS
- High findings: 1
- Medium findings: 2

## Findings
1. High - No human approval path for production deploy.
2. Medium - No cheaper fallback model defined.
3. Medium - Retry limits missing for external API calls.

## Required Remediation
- Add approval gate for prod deploy.
- Add `gpt-4o-mini` fallback.
- Bound retries to 3 with exponential backoff.

Logging and Audit Trail

A governed agent should emit auditable events for:

• session start
• tool invocation on sensitive tools
• approval request and approval result
• model fallback activation
• final verdict and artifacts changed

import json
from datetime import datetime, timezone


def audit_event(action: str, agent: str, detail: dict) -> str:
    payload = {
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "agent": agent,
        "action": action,
        "detail": detail,
    }
    return json.dumps(payload)

Failure Conditions

Fail governance review if any of these are true:

• destructive action path has no approval
• secrets access relies on embedded credentials
• iteration and retry limits are undefined
• no observable logs or eval output exist
• content safety or prompt injection controls are absent for public-facing agents

Troubleshooting

Final Verdict

Use these release outcomes:

A governance review is complete only when the verdict, findings, owner, and remediation due dates are recorded in the play or repo audit trail.