Smart Top-Up (Human-in-the-Loop)

The Flaw of Hard Rate Limits

When an autonomous agent hits a hard spending limit in conventional gateways, the server drops the connection with HTTP 429.

In multi-step agent pipelines (research swarms, document processing, code audits):

• A hard crash destroys in-memory state and execution context.
• Restarting forces the agent to re-run from step 1, wasting double the budget.

---

The AgentRail Solution

AgentRail decouples budget enforcement from execution state:

1. State Preservation: When an agent hits the limit, requests halt gracefully in INSUFFICIENT_FUNDS.
2. Operator Alert: The system alerts the human manager / Tech Lead.
3. Atomic Top-Up: The operator increases the budget via /v1/admin/control.
4. Resumption: The agent seamlessly continues its task with full context.

---

Executing a Top-Up via cURL

Administrators use their ADMIN_TOKEN to execute a top-up:

curl -X POST "https://<your-pilot-id>.agentrail.workers.dev/v1/admin/control" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "topup-001",
    "expectedRevision": 3,
    "action": "topUp",
    "deltaMicros": 20000000,
    "evidence": {
      "reference": "JIRA-PROJ-88",
      "note": "Approved $20.00 additional budget for batch document parsing."
    }
  }'

Parameters

• id: Unique identifier for the control command.
• expectedRevision: Current version of the ledger state (prevents race conditions with concurrent operator commands).
• action: Must be "topUp".
• deltaMicros: Budget increase in microdollars ($1 USD = 1,000,000 µ$). E.g. 20000000 = $20.00 USD.
• evidence: Audit trail recording the reference ticket and business rationale.