Approval Boundaries

Human-in-the-loop checkpoints that pause agent execution and require human sign-off before high-risk actions proceed.

When Humans Must Be in the Loop

Not every agent action needs human review. But some do — and identifying that boundary is a security decision, not a UX decision.

Approval boundaries should be placed on:

• Any irreversible action — delete, send, publish, transfer. These cannot be undone.
• Any action with external effect — emails, webhooks, database writes, API calls that trigger downstream processes
• Any action touching sensitive data — PII, financial records, credentials, health data
• Any action outside the agent's normal scope — if it's unusual, a human should confirm it

Defining Approval Boundaries

from agentcop import ApprovalBoundary

@ApprovalBoundary(
    reason="Sending email to external recipient",
    timeout=300,  # seconds to wait for approval
    notify=["security@company.com", "manager@company.com"],
    on_timeout="block"  # block | allow | escalate
)
def send_customer_email(to: str, subject: str, body: str):
    # This function will pause and wait for approval
    # before executing
    mailer.send(to=to, subject=subject, body=body)

Approval Request Format

When a boundary is triggered, AgentCop generates a structured approval request containing the full context of what is being requested and why.

{
  "approval_id": "apr_abc123",
  "agent_id": "customer-support-bot",
  "action": "send_customer_email",
  "parameters": {
    "to": "customer@example.com",
    "subject": "Your refund has been processed",
    "body": "..."
  },
  "risk_level": "MEDIUM",
  "requested_at": "2026-04-06T14:23:11Z",
  "expires_at": "2026-04-06T14:28:11Z",
  "context": {
    "triggered_by": "user: process refund for order #4821",
    "agent_run_id": "run_xyz789"
  }
}

Approving via API

# Approve
httpx.post(f"/api/approvals/{approval_id}/approve",
           json={"approver": "admin@company.com", "note": "Refund verified"})

# Deny
httpx.post(f"/api/approvals/{approval_id}/deny",
           json={"approver": "admin@company.com", "reason": "Wrong amount"})

Audit Trail

Every approval decision is recorded in an immutable audit log. The log captures the approver identity, timestamp, the full parameters of the requested action, and the outcome (approved, denied, timed out).

This audit trail supports compliance requirements for frameworks including SOC 2 and HIPAA, where demonstrating human oversight of automated systems handling sensitive data is a control requirement.