What is OnceOnly?

What is OnceOnly?

OnceOnly is a safety and governance platform for AI agents. It solves a critical problem: how do you deploy an AI agent to production so it doesn’t duplicate actions, overspend its budget, or violate safety policies?

The Problem OnceOnly Solves

When AI agents execute tools (external APIs), several problems can occur:

1. Duplication (Idempotency Loss)

An agent retries a request, but both attempts execute — resulting in duplicate charges, duplicate emails, or duplicate database writes.

Payment Flow:
1st attempt: "Charge $100" → Success ✓
              Network timeout (agent doesn't receive response)
Retry:       "Charge $100" → Success ✓ (again!)
              Result: Customer charged $200 instead of $100 ❌

2. Budget Overruns

The agent doesn’t know the price of each tool, so it can burn through the daily budget on just 3 expensive API calls.

3. Policy Violations

The agent calls a tool it’s not supposed to (delete_user, process_refund) or exceeds rate limits.

4. Lack of Audit Trail

When something goes wrong, you can’t quickly find who authorized the agent to take that action.

How OnceOnly Solves It

┌────────────────────────────────────┐
│  AI Agent (Claude, GPT-4, etc.)    │
│  Wants: Call tools[5] with args    │
└──────────────┬─────────────────────┘
               │
    ┌──────────▼──────────────┐
    │  OnceOnly API Gateway   │
    │  ┌────────────────────┐ │
    │  │ 1. Check Lease     │ │  Is this agent already doing this?
    │  │    (Idempotency)   │ │  → "acquired" or "polling"
    │  └────────────────────┘ │
    │  ┌────────────────────┐ │
    │  │ 2. Check Policy    │ │  Is this action allowed?
    │  │    (Access Control)│ │  → "allowed" or "blocked"
    │  └────────────────────┘ │
    │  ┌────────────────────┐ │
    │  │ 3. Check Budget    │ │  Enough money left?
    │  │    (Cost Control)  │ │  → "within limit" or "exceeded"
    │  └────────────────────┘ │
    │  ┌────────────────────┐ │
    │  │ 4. Log Decision    │ │  Record for audit
    │  │    (Audit Trail)   │ │
    │  └────────────────────┘ │
    └──────────┬──────────────┘
               │
         ┌─────▼──────────────┐
         │ → Allow execution  │
         │ → Return lease ID  │
         │ → Agent proceeds   │
         └────────────────────┘

Core Concepts

Idempotency (Check Lock)

A unique key per action. If the agent retries with the same key, OnceOnly returns “duplicate” instead of executing again.

# First attempt
POST /v1/check-lock {"key": "payment_123"}
→ {"success": true, "status": "locked", "first_seen_at": null}  # New action, execute it

# Retry within 1 hour
POST /v1/check-lock {"key": "payment_123"}
→ {"success": false, "status": "duplicate", "first_seen_at": "2025-01-15T10:30:00Z"}  # Don't execute again!

AI Leases (Long-running Tasks)

For operations lasting minutes to hours, agents get a “lease” — permission to hold exclusive execution for that task.

# Acquire lease for 30 minutes
POST /v1/ai/lease {"key": "support_chat_1", "ttl": 1800}
→ {"status": "acquired", "lease_id": "lease_xyz"}

# If agent retries
POST /v1/ai/lease {"key": "support_chat_1", "ttl": 1800}
→ {"status": "polling"}  # Another agent owns this, wait

Policies (Governance)

Define what each agent can do:

• Which tools are allowed/blocked
• Rate limits (actions per hour)
• Budget limits (max spend per day)

# Admin sets policy for "support_bot"
{
  "agent_id": "support_bot",
  "allowed_tools": ["send_email", "read_knowledge_base"],
  "blocked_tools": ["delete_user"],
  "max_actions_per_hour": 100,
  "max_spend_usd_per_day": 500
}

Tools Registry

Users register their own external APIs (webhooks, microservices) as “tools” that agents can call. Each tool has:

• URL (where to call)
• Auth (HMAC-SHA256 signature)
• Timeout & retry settings
• Pricing (for budget tracking)

Audit Logging

Every decision is logged:

• What action did the agent attempt?
• Was it allowed? Why or why not?
• What was the cost?
• When did it happen?

Platform Architecture

┌─────────────────────────────────────────┐
│  FastAPI Application                     │
│  Version: 0.6.5                          │
├─────────────────────────────────────────┤
│ • Core API (check-lock, ai/lease)       │
│ • User Auth (API keys, billing)         │
│ • Billing (Stripe/PayPro integration)   │
│ • Policy Engine (agent controls)        │
│ • Tools Registry (user-defined APIs)    │
│ • Audit Logging (decision trail)        │
│ • Governance API (team management)      │
└──────────┬──────────────┬───────────────┘
           │              │
      ┌────▼──┐      ┌────▼──────────────┐
      │ Redis │      │ PostgreSQL        │
      │ Cache │      │ (users, policies, │
      │ (locks)      │  tools, logs)     │
      └───────┘      └───────────────────┘

Component Breakdown

Component	Purpose
Idempotency Engine	Prevents duplicate action execution via Redis locks
AI Lease Manager	Handles long-running async tasks with TTL renewal
Policy Engine	Enforces access control, rate limits, and budgets
Tools Registry	Stores and manages user-defined external APIs
Audit Trail	Logs all decisions with timestamps and reasons
Billing Integration	Tracks usage and integrates with Stripe/PayPro
Governance API	Team management: enable/disable agents, set policies

Pricing Plans

Feature	Free	Starter	Pro	Agency
Idempotency	✓	✓	✓	✓
AI Leases	✓	✓	✓	✓
Rate Limiting	-	✓	✓	✓
Budget Controls	-	✓	✓	✓
Tools Registry	-	✓	✓	✓
Policies	-	✓	✓	✓
Audit Logging	-	-	✓	✓
Multiple Agents	-	-	✓	✓
Multi-tenant	-	-	-	✓
API Access	-	-	-	✓

Your First Request

The simplest request: check if an action is safe.

curl -X POST https://api.onceonly.tech/v1/check-lock \
  -H "Authorization: Bearer once_live_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "payment_invoice_789",
    "ttl": 3600,
    "metadata": {
      "invoice_id": "789",
      "amount_usd": 99.99
    }
  }'

Response (New Action):

{
  "success": true,
  "status": "locked",
  "key": "payment_invoice_789",
  "ttl": 3600,
  "first_seen_at": null
}

Response (Duplicate):

{
  "success": false,
  "status": "duplicate",
  "key": "payment_invoice_789",
  "ttl": 3600,
  "first_seen_at": "2025-01-15T10:30:00Z"
}

Next Steps

1. Mental Model — Learn how requests flow through the system
2. Quickstart — First 5 minutes of integration
3. Idempotency — Deep dive into duplication protection
4. AI Leases — Long-running async task management
5. Policies — Governance and access control
6. Tools Registry — Custom API management