Agent Approval Workflows

Overview

AgentMetal uses a risk-based approval system to balance automation speed with safety. Every action an agent plans is classified by risk level, and the system enforces appropriate review based on that classification.

Risk Levels

## Risk Classification Examples

Safe Operations

• Listing resources
• Reading status or metrics
• Health checks
• Fetching logs

Moderate Operations

• Creating a new instance
• Scaling up a cluster
• Adding a DNS record
• Creating a database replica

Dangerous Operations

• Deleting a production instance
• Removing a VPC with active resources
• Dropping a database
• Modifying security group rules to allow public access
• Destroying an IaC stack

Approval Flow

When an agent generates a plan containing dangerous actions:

1. Agent generates execution plan
Risk classifier marks plan as "dangerous"
Plan is submitted to the approval queue
Notification sent (webhook, email, or dashboard)
Human reviews the plan via API or dashboard
Human approves or rejects
If approved: plan executes
If rejected: plan is discarded, reason recorded

Configurable Auto-Approval Policies

For environments where speed is prioritized over manual review, auto-approval policies can override the default behavior:

{
  "policy": "auto-approve-moderate",
  "resource_kinds": ["Instance", "DNSRecord"],
  "max_risk_level": "moderate",
  "conditions": {
    "labels": {"env": "staging"}
  }
}

This policy auto-approves moderate-risk operations on Instance and DNSRecord resources in the staging environment.

Approval API

Review and act on pending approvals:

# List pending approvals
curl -H "$AUTH" $API/v1/approvals
Review a specific approval
curl -H "$AUTH" $API/v1/approvals/appr-abc123
Approve
curl -X POST -H "$AUTH" -H "$CT" $API/v1/approvals/appr-abc123/approve \
  -d '{"comment": "Approved during maintenance window"}'
Reject
curl -X POST -H "$AUTH" -H "$CT" $API/v1/approvals/appr-abc123/reject \
  -d '{"reason": "Not during business hours"}'

Audit Trail

Every decision is recorded with full context:

{
  "id": "audit-xyz789",
  "agent": "instance-agent",
  "action": "delete",
  "resource_id": "inst-abc123",
  "risk_level": "dangerous",
  "approval_id": "appr-abc123",
  "approved_by": "admin@example.com",
  "reasoning": "Instance marked for decommission per ticket INFRA-456",
  "outcome": "success",
  "timestamp": "2025-01-15T14:00:00Z"
}

The audit log provides a complete record of who requested what, why the agent decided to act, who approved it, and what happened. This is essential for compliance, debugging, and post-incident review.