Skip to content

Guide: Progressive Governance — Start Simple, Add Layers

Applies to: All AGT packages · Time: 15 minutes · Prerequisites: None

What You'll Learn

  • The 5-level progressive complexity model for agent governance
  • When to add each governance layer based on your team's risk profile

You don't need the full stack to start. Most teams run Level 1–2 in production and never need Level 5. Pick the level that matches your risk.

Level 1: Govern in 3 Lines

When you need this: You have one agent, you want to block dangerous actions, and you need something running today.

from agent_os.policies import PolicyEvaluator, PolicyDocument

doc = PolicyDocument.from_dict({
    "version": "1.0",
    "rules": [
        {"action": "web_search", "effect": "allow"},
        {"action": "read_file", "effect": "allow"},
        {"action": "*", "effect": "deny"},
    ],
})

evaluator = PolicyEvaluator(policies=[doc])
decision = evaluator.evaluate({"action": "delete_file"})
assert not decision.allowed  # blocked by default-deny

💡 This is enough for 80% of teams starting out. You get deterministic policy enforcement with zero infrastructure.

Level 2: Add YAML Policies

When you need this: Your rules are growing, you want version-controlled policies, or you need content filtering (PII, prompt injection).

# policies/production.yaml
version: "1.0"
rules:
  - action: "web_search"
    effect: allow
  - action: "read_file"
    effect: allow
    conditions:
      path_pattern: "/data/public/**"
  - action: "*"
    effect: deny
content_filters:
  blocked_patterns:
    - '\b\d{3}-\d{2}-\d{4}\b'   # SSN
    - '\b\d{16}\b'               # Credit card numbers

from agent_os.policies import PolicyEvaluator

evaluator = PolicyEvaluator.from_yaml("policies/production.yaml")
decision = evaluator.evaluate({"action": "read_file", "path": "/data/public/report.csv"})

💡 Generate policies instantly with agent-os policy generate --template strict. See Policy Generator CLI.

Level 3: Add Agent Identity

When you need this: You have multiple agents, you need to know which agent did what, or you need trust scoring between agents.

from agentmesh.identity import AgentIdentity

identity = AgentIdentity.create(
    name="research-agent",
    capabilities=["web_search", "read_file"],
)

# Identity gives each agent a verifiable SPIFFE SVID
# Use with policy evaluation: evaluator.evaluate({"agent_id": identity.id, "action": "web_search"})

💡 Add this when you move to multi-agent systems. Single-agent setups rarely need identity management.

Level 4: Add Lifecycle Management

When you need this: Agents are created dynamically, credentials need rotation, or you need to detect orphaned/shadow agents.

from agentmesh.lifecycle import LifecycleManager, OrphanDetector

manager = LifecycleManager()
agent = manager.request_provisioning(
    name="data-analyst",
    owner="platform-team",
    capabilities=["read_file", "web_search"],
)

detector = OrphanDetector()
orphans = detector.scan()  # finds agents with no active owner
for orphan in orphans:
    manager.decommission(orphan.id)

💡 Add this when you're running agents in production at scale. Credential rotation and orphan detection prevent security drift.

Level 5: Full Stack

When you need this: Regulated industries, enterprise compliance requirements, or you need a complete governance dashboard with SRE capabilities.

from agentmesh.governance import govern, GovernanceConfig
from agent_os.policies import PolicyEvaluator

# Wrap any agent with full governance: policies, identity, audit, SRE
config = GovernanceConfig(
    policy="policies/",
    agent_id="enterprise-agent",
    audit=True,
    audit_file="audit/governance.jsonl",
)

safe_agent = govern(agent.run, config=config)

# Everything from Levels 1–4, plus:
# - Policy enforcement with conflict resolution
# - Full audit trail with compliance mapping
# - Approval workflows for high-risk actions
result = safe_agent(action="transfer_funds", amount=10000)

💡 Most teams never need Level 5. It exists for regulated industries (finance, healthcare, government) with strict compliance requirements.

Summary

Level What You Get Lines of Code When You Need It
1 Policy enforcement ~5 Day one — block dangerous actions
2 YAML policies + content filters ~3 + YAML Rules are growing, need version control
3 Agent identity + trust scoring ~8 Multi-agent systems
4 Lifecycle + orphan detection ~10 Production scale, credential rotation
5 Full stack (SRE, compliance, dashboard) ~12 Regulated industries

Next Steps