agentraas

<img src="src/api-gateway-rs/public/img/agentraas-banner.png" alt="AgentRaaS" width="100%">

# AgentRaaS

**The agent reliability platform.**

AgentRaaS sits between your AI agents and every real-world action, giving you three things at once, not one trick: **reliability** (exactly-once execution, circuit breaking, proven under real concurrent load, not just claimed), **responsibility** (budget/loop limits and human-in-the-loop approval before the calls that matter), and **accountability** (a full audit trail and per-agent identity — scope-restricted credentials — for every action taken). Connect it via webhook, SDK-style headers, or native MCP. Self-hosted or cloud.

---

## The Problem

Your n8n workflow hits Stripe. It times out. n8n retries.

**Result:** The customer is charged twice.

Your agent calls HubSpot to create a contact. The request succeeds, but the response is lost. The agent retries.

**Result:** Two duplicate contacts in your CRM.

---

## The Solution

AgentRaaS is a reliability layer that guarantees **exactly-once execution** of agent actions — proven under real concurrent load with an automated test suite.

```mermaid
flowchart LR
    Agent["Agent<br/>(n8n, Python, MCP)"] -->|request| Proxy
    subgraph Proxy["AgentRaaS"]
        direction TB
        D["Deduplicate"] --> V["Validate"] --> C["Circuit breaker"] --> R["Rate limit"] --> A["Audit log"]
    end
    Proxy -->|forwarded once| API["API<br/>(Stripe, Twilio, HubSpot, or any)"]
```

**How it works:**
1. Your agent sends a request to AgentRaaS instead of the API directly
2. AgentRaaS atomically claims a dedup slot in Redis for that exact request
3. **First call:** forwarded to the real API, result cached
4. **A concurrent or later retry:** returns the cached result, or a 409 if the original is still in flight — never a second real execution

---

## Free tools, no server needed

`pip install agentraas` gives you three tools that run entirely on your machine. Start here, and add the server when your team wants the dashboard, human approval and one audit trail.

**Find** the calls your agent would run twice. The chaos tester lets each write request execute, then drops the response (the failure that turns a retry into a double charge) and reports every action that ran twice. It exits non-zero, so it can fail CI ([GitHub Action](src/chaos-action/action.yml)).

```bash
agentraas chaos --mock -- python my_agent.py
```

**Fix** them with a decorator backed by local SQLite or your own Redis:

```python
from agentraas.local import exactly_once

@exactly_once()
def charge(customer, amount, idempotency_key=None):
    return stripe.Charge.create(customer=customer, amount=amount, idempotency_key=idempotency_key).id
```

**Wrap** any MCP server so identical write-tool calls run once and every call is logged. Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.sumedhchatse/agentraas) as `io.github.sumedhchatse/agentraas`:

```json
{ "mcpServers": { "github": { "command": "uvx",
  "args": ["agentraas", "wrap", "--", "npx", "-y", "@modelcontextprotocol/server-github"] } } }
```

Full options: [`src/sdk/README.md`](src/sdk/README.md). The TypeScript `exactlyOnce` is in [`src/sdk-js`](src/sdk-js) (not on npm yet).

---

## Dashboard

Open `http://localhost:13001/dashboard` — requires an account (register/login, encrypted password storage). New accounts get their own org automatically — nothing technical required just to see a working dashboard.

- **+ Connect Agent** — generates a real API key scoped to one org/agent, with curl and n8n examples
- **Credentials** — add your own Stripe/Twilio/etc. keys yourself, encrypted at rest, no server access needed
- **Custom Actions** — register any endpoint (not just the curated list below), SSRF-guarded, so your agents can call it too
- Total actions, success/deduplicated/blocked/error breakdown, request volume and outcome charts, over 24h/7d/30d/90d — scoped to your own data only, never other users'
- Active agents, service health (circuit breaker state), searchable/filterable/sortable recent activity log
- Auto-refreshing, CSV export, account settings (change password)
- A full step-by-step walkthrough lives at [`/guide`](./GETTING_STARTED.md) — worth reading if any of the above is unfamiliar

---

## Getting started

**Option 1 — clone this repo (fastest):**

```bash
git clone https://github.com/sumedhchatse/agentraas.git
cd agentraas
./install.sh
```

**Option 2 — from AgentRaaS Cloud:** register at **agentraas.io**, connect
your first agent, then download the self-host package from the
dashboard's Account menu (unlocks once you've connected an agent). Same
`install.sh`, just packaged with your Cloud account already wired up.

**Option 3 — one-click cloud deploy (Render):**

[![Deploy to Render](https://render.com/images/deploy-to-render-button.svg)](https://render.com/deploy?repo=https://github.com/sumedhchatse/agentraas)

Provisions the Community edition (web service + managed Postgres + Redis)
from [`render.yaml`](./render.yaml) — no server of your own needed. Uses
[`Containerfile.render`](./src/api-gateway-rs/Containerfile.render), a
variant that bakes `public/` and `config/` into the image instead of the
bind-mounts `compose.yaml` uses locally, since Render doesn't support
those. Verified locally end-to-end (build, boot, `/health`, and the
landing page all serving from the built image) before this button
shipped.

`install.sh` handles everything that used to be a manual multi-step
process: generating `JWT_SECRET` and `CREDENTIALS_ENCRYPTION_KEY`, building
the API image, starting the stack, running every migration in order,
handling SELinux relabeling if applicable, and a clean recreate at the end.
The first run compiles the Rust service from source — expect a few minutes
on that step; it isn't a hang.

Then open `http://localhost:13001/dashboard` and register a new account
— self-hosted instances are single-tenant, so whoever registers first is
just the first user, no special admin bootstrap needed. (Option 2's
account is pre-registered instead — use "Forgot password" to set a
password for this instance.)

**A real gotcha worth knowing, if you ever touch the setup manually:** on
SELinux (Fedora/RHEL-family hosts), bind-mounted files can end up with the
wrong context and the container fails with `EACCES` errors. `install.sh`
handles this automatically; if you're troubleshooting by hand, fix it with:
```bash
sudo semanage fcontext -a -t container_file_t "$(pwd)(/.*)?"
sudo restorecon -Rv "$(pwd)"
```
and from then on, always use `podman-compose down && up -d` (full recreate)
after changing files on the host — never plain `restart`, which doesn't
re-apply the SELinux label.

**Services:**
- API Gateway + dashboard: `http://localhost:13001`
- Postgres: `localhost:15432`
- Redis: `localhost:16379`

---

## Testing

```bash
cd src/api-gateway-rs
npm install                                            # one-time: axios/pg/ioredis
TEST_BASE_URL=http://localhost:13001 npm test
```

Runs real integration tests against the running server — concurrent duplicate
requests, sequential replay, distinct-payload isolation, and failure/retry
recovery — not mocked unit tests. Uses the built-in `mockpay` service, so no
real API keys are needed to run them. (These are plain Node HTTP-client tests
that live alongside the Rust service; the server itself has no Node in it.)

Plus a native Rust unit-test suite covering the dedup hashing, loop-detection,
and checkpoint logic directly — including golden-value tests that pin the
dedup hash format so it can't silently shift:

```bash
cd src/api-gateway-rs
cargo test --workspace                      # Community edition
cargo test --workspace --features enterprise
```

Both run on every push/PR via `.github/workflows/rust-test.yml`.

---

## MCP (Model Context Protocol)

AgentRaaS exposes an MCP gateway for Claude Desktop, Cursor, and other MCP clients:

```json
{
  "mcpServers": {
    "agentraas": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:13001/mcp"]
    }
  }
}
```

All tool calls through this gateway are deduplicated, validated, rate-limited, and logged.

---

## Supported services

Curated, pre-configured integrations (no code required — see `config/services.json`):

Stripe, Twilio, HubSpot, Calendly, Shopify, Zoho, Razorpay, WhatsApp,
Zapier, Make, Adyen, Mollie, Airwallex, Xendit, PayPal, Salesforce, Slack,
Klarna, Paystack, GoCardless, Opn Payments, plus the built-in `mockpay`
for safe testing.

**Need something not on this list?** Register it as a **Custom Action** from
the dashboard — any URL, any auth type, protected by the same dedup/audit/
rate-limit pipeline, with an SSRF guard so it can't be pointed at internal
infrastructure.

To add a new *curated* integration permanently, add an entry to
`config/services.json` following the existing pattern — no code changes needed.

---

## Architecture

```mermaid
flowchart TB
    subgraph Incoming["Incoming agent requests"]
        WH["Webhook / SDK / MCP"]
    end
    subgraph GW["MCP Gateway"]
        MCPR["/v1/sdk/:service/:action, /mcp"]
    end
    WH --> MCPR
    MCPR --> APIGW["API Gateway<br/>:13001"]
    APIGW --> Redis["Redis (Dedup)<br/>:16379"]
    APIGW --> PG["PostgreSQL<br/>(Audit, users, creds)<br/>:15432"]
```

---

## Why AgentRaaS vs. DIY idempotency keys?

If you're only calling Stripe by hand from your own backend, its native
`Idempotency-Key` header is genuinely enough — you don't need this. The
honest case for AgentRaaS is narrower and specific:

- **Not every provider has native idempotency.** Stripe does. Twilio,
  Slack, most SaaS/CRM APIs, and literally any custom internal endpoint
  don't — you'd be building the same dedup logic yourself, per provider,
  by hand.
- **No-code tools can't set the header at all.** n8n, Make, and Zapier
  give you a URL field, not a place to compute and attach an idempotency
  key — so