Everything ACPpotamia does, explained.
How ACPpotamia works and how to use each part of it, with diagrams, worked examples and code you can paste. The chapters build on each other, but each one stands alone, so skip to whatever you need. Keep the API reference open in another tab for exact endpoints and headers.
Who it is for
| You are | Your problem | What ACPpotamia gives you | Start with |
|---|---|---|---|
| Engineering team | A bug in an agent loop can run up a large bill on a shared API key | Per-key budgets, per-session rate limits, loop stop, test keys | Chapter 2, 6 |
| SaaS or agent platform | One customer or a malicious prompt can use up resources shared by all customers | Per-customer (tenant) budgets and rate limits, set from your code | Chapter 4 |
| Security and FinOps | No central view, policy or evidence across departments running agents | Organizations, model policies, audit export, a global kill switch | Chapter 5 |
Chapters
1. How a call flows
Follow one AI agent call through ACPpotamia: key check at the edge, the team control object's checks, the provider, live token metering, settlement and the audit log.
2. Budgets and limits
How ACPpotamia's budgets and rate limits work: reservations before each call, and limits that stack across team, API key, tenant and session. With worked examples.
3. Loops and the kill switch
How ACPpotamia detects AI agents stuck in loops, how to tune it for your agents, and how to stop one task, a whole team or an entire organization instantly.
4. Per-customer budgets (SaaS)
Give every customer of your AI product their own monthly budget and rate limit with one header, a default and the Tenant API. Step-by-step with Node.js and Python code.
5. Governance and compliance
Run AI agents across departments with one model policy, an organization-wide kill switch, roles, an audit trail and CSV, JSONL or raw log export for your SIEM.
6. Testing and CI
Use ACPpotamia test keys in development and CI: every limit and policy applies, responses are provider-format mocks, nothing is charged, and errors can be simulated.
7. Operations and troubleshooting
Run ACPpotamia in production: fail-open and fail-closed modes, every error code and what to do, monitoring, status checks and a troubleshooting checklist.
Words used in this guide
| Term | Meaning |
|---|---|
| Organization | Several teams (departments) with shared policy, kill switch and export. |
| Team | Your workspace: its own keys, limits, billing and control object. |
| API key | acp_ for real calls, acp_test_ for mock calls. Each can have its own limits. |
| Agent | A name you give each agent (X-ControlPlane-Agent-Id), for activity and spend. |
| Session | One task (X-ControlPlane-Session-Id): the unit for loop detection and stopping. |
| Tenant | One of your own customers (X-ControlPlane-Tenant-Id), with their own budget. |
| Control object | The one server that holds your team's limits and decides each call in a single step. |
| Reservation | Money held for a call in progress, replaced by the real cost when it ends. |