Governance

Handler is built around a simple principle: agents should be powerful, but every action must be tied to a profile, and every profile plays by your rules. Every call is evaluated against your spending rules before it executes.

How It Works

When your agent makes a call through Handler, the request passes through your governance rules before anything happens. Based on those rules, Handler does one of three things:

1. Auto-approves the call and executes it immediately.
2. Holds the call and notifies you for approval.
3. Blocks the call outright and tells the agent why.

This happens in milliseconds. Your agent gets an instant response in all three cases — it never hangs waiting for an unknown outcome.

Rule Types

You configure governance through four rule types. Each one controls a different threshold.

auto_approve_below

Calls costing less than this amount execute instantly with no human involvement. This is the fast path for routine, low-cost operations.

auto Example: auto_approve_below: 2.00 means any call under $2.00 runs immediately.

notify_above

Calls costing more than this amount are held and you receive a notification to approve or deny. The agent gets a pending status and knows to wait.

hold Example: notify_above: 10.00 means calls over $10.00 are paused until you respond.

hard_cap

Calls costing more than this amount are always blocked. No notification, no approval flow — the agent is told the action exceeds the limit.

block Example: hard_cap: 50.00 means any single call over $50.00 is rejected outright.

monthly_cap

Total spending limit per agent per calendar month. Once the agent hits this cap, all subsequent calls are blocked until the next month or until you raise the limit.

block Example: monthly_cap: 100.00 means the agent can spend up to $100/month across all superpowers.

Per-Profile, Per-Action

Rules are set at the profile level and can be granular down to individual actions within a service:

• Global (per profile) — applies to every action the agent takes. This is the default.
• Per action — overrides the global rule for a specific superpower or action. Set tighter limits on expensive or sensitive operations.

For example, your research agent might have these rules:

In this setup, most superpowers auto-approve under $5. But AI inference (handler_generate) auto-approves only under $0.50 because it's more expensive per call. And all outbound communications require explicit approval because auto_approve and notify_above are both set to $0.

Approval Channels

When a call is held for approval, Handler notifies you through your configured channel. You can approve or deny with a single tap — no need to log into a dashboard.

• Dashboard — approve from the Handler web UI with full request details.
• WhatsApp — get a message with the action summary and one-tap approve/deny buttons.
• Telegram — inline keyboard buttons for instant approval.
• MCP — orchestrators and master agents approve programmatically via handler_decide.

Pending request lifetime

Pending requests do not expire automatically. A request can sit in the queue for minutes, hours, or days — it will remain actionable until you explicitly approve or reject it. This is intentional: Handler never makes a call on your behalf without your decision.

What this means for your agent: if your agent calls a tool that gets held and the owner goes offline for a weekend, the agent will continue receiving status: "pending" for that request indefinitely. Well-designed agents should:

• Continue other tasks that don't depend on the held result
• Inform the user if the workflow is blocked waiting for approval
• Optionally check the request_id via handler_status to see if approval arrived

Handler does not currently send a "request expired" signal to agents. If you need time-bounded workflows, reject the request manually from the dashboard and the agent will receive status: "rejected" on its next poll.

Risk Profiles

Not sure where to start? Pick a risk profile that matches your comfort level. You can always adjust later.

When you create a new agent, Handler asks you to pick a risk profile during onboarding. This sets smart defaults that you can customize at any time from the dashboard.

Example Scenario

Here's a real-world walkthrough of governance in action.

handler_communicate({
  "task": "send",
  "to": "ceo@bigcorp.com",
  "subject": "Partnership proposal",
  "body": "Hi, I'd like to discuss a potential partnership..."
})

{
  "status": "executed",
  "result": {
    "message_id": "msg_a1b2c3",
    "sent_to": "ceo@bigcorp.com"
  },
  "cost": { "charged": 0.005 }
}

What Agents See

Your agent always gets an immediate, structured response. It never hangs or times out. Here are the three possible outcomes:

Executed

The call was auto-approved and completed successfully.

{
  "status": "executed",
  "result": {
    "results": [...],
    "query": "AI agent frameworks 2026"
  },
  "cost": { "charged": 0.005 },
  "budget": { "remaining": 9.995 }
}

Pending

The call is held for owner approval. The agent should acknowledge and wait or move on to other tasks.

{
  "status": "pending",
  "message": "Held for owner approval. Your owner has been notified.",
  "request_id": "req_x7y8z9"
}

Blocked

The call exceeded a hard cap or monthly limit. The agent should inform the user or try an alternative approach.

{
  "status": "blocked",
  "message": "This action exceeds the hard cap for handler_communicate."
}