AgentRaaS wrap

agentraas (Python SDK)

The reliability layer for what AI agents do. Every action your agent takes (a charge, an email, a CRM update, a tool call) runs once even when it is retried, can be checked against rules before it runs, and is recorded. This package brings that to your code:

• @exactly_once and protect_tool (LangChain/LangGraph, CrewAI): a retry, yours, your framework's or a flaky network's, never becomes a duplicate charge or message. No server needed.
• agentraas wrap: the same for any MCP server's write tools.
• agentraas scan: lists which tools in your MCP servers can move money, delete data, run code or send messages, without calling any of them.
• agentraas chaos: finds the calls in your agent that would double up under retries, before production does.
• Client: points your calls at an AgentRaaS server for action policies, human approval, spend caps, circuit breaking and an audit trail.

Works against any AgentRaaS deployment: self-hosted (./install.sh, free and unlimited on every tier) or AgentRaaS Cloud.

Install

pip install agentraas

Library mode: no server needed

Wrap any function that has a side effect (charging a card, sending an email, creating a CRM record) so retries and concurrent duplicates run it exactly once. Nothing to deploy: state lives in a local SQLite file by default, or in your own Redis.

from agentraas.local import exactly_once, RedisStore

@exactly_once() # SQLite file, one machine def charge(customer, amount): return stripe.Charge.create(customer=customer, amount=amount).id

charge("cus_1", 4200) # runs for real charge("cus_1", 4200) # retry: returns the cached id, no second charge

Across machines, with your own idempotency key and window:

@exactly_once(store=RedisStore("redis://localhost:6379/0"), key=lambda order: order["id"], ttl=3600) async def ship(order): ...

• If the function raises, nothing is cached and a retry runs it again. That includes the case where the provider did the work but the response was lost, so give the function an idempotency_key parameter and send it to the provider (e.g. Stripe's Idempotency-Key header). The decorator fills it with the same value on every retry:

  @exactly_once()

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

- A duplicate that arrives while the first call is still running waits for

its result (up to wait=30 seconds, then InFlightError).

• Results must be JSON-serializable (return ids or dicts, not SDK objects).
• RedisStore needs pip install redis.

When you want a dashboard, audit trail, human approval or circuit breaking on top, point the same calls at an AgentRaaS server with the Client below.

LangChain / LangGraph: exactly-once tool calls

pip install "agentraas[langchain]", then wrap the tools that have side effects. Works with LangChain agents, create_react_agent and ToolNode.

from agentraas.langchain import protect_tool

tools = [protect_tool(charge_card), protect_tool(send_email), search] agent = create_react_agent(model, tools)

When the model calls a protected tool again with the same arguments, or the graph re-runs the tool node after a crash or retry, the stored result comes back instead of a second charge. Takes the same store=, key= and ttl= options as @exactly_once above (e.g. store=RedisStore(...) for several workers, key=lambda order_id, **_: order_id). Tool results must be JSON-serializable.

CrewAI: exactly-once tool calls

pip install "agentraas[crewai]" (CrewAI needs Python 3.10+), then wrap the tools that have side effects, either BaseTool subclasses or @tool functions:

from agentraas.crewai import protect_tool

agent = Agent(role="Billing", goal="...", backstory="...", tools=[protect_tool(ChargeCardTool()), protect_tool(send_email)])

When the agent calls a protected tool again with the same arguments, or a crew is kicked off again after a crash, the stored result comes back instead of a second charge. Same store=, key= and ttl= options as above. The original tool object is left unchanged.

MCP wrap: exactly-once tool calls for any MCP server

Put agentraas wrap -- in front of an MCP server's command. Everything passes through unchanged, except that an identical call to a write tool (same tool, same arguments) inside the dedup window gets the first call's result back instead of running again. An agent that retries or loops can't send the same email or open the same issue twice. Every tool call is appended to an audit log.

Claude Desktop / Cursor config:

{

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

• Read-only tools are never deduplicated, so lookups stay fresh. The server's readOnlyHint annotation decides, falling back to names like get_*, list_*, search_*. Override with --dedupe TOOL / --no-dedupe TOOL.
• A failed call (JSON-RPC error or isError: true) is not cached, so a retry runs for real.
• Default window: 10 minutes (--ttl 600). State lives in ~/.agentraas/mcp-dedup.db, the log in ~/.agentraas/mcp-audit.jsonl (--db, --log).
• A deduplicated result carries _meta: {"agentraas/deduplicated": true}.

MCP safety scan: which tools can act on the real world

agentraas scan                                    # every server in your Claude Desktop, Cursor, Claude Code configs

agentraas scan -- npx -y @modelcontextprotocol/server-github agentraas scan --config .mcp.json --fail-on high # CI: exit 1 on a high-risk tool

Starts each stdio server the way your client does, sends only initialize and tools/list, and sorts the tools: moves money, deletes, runs code, sends (high), writes (medium), reads (low), from their readOnlyHint/destructiveHint annotations and the words in their names. Only scan configs you trust: it runs their commands. --json for machine-readable output. https://agentraas.io/mcp-scan

GitHub Actions:

- uses: agentraas/agentraas/src/scan-action@main

with: config: .mcp.json # or command: "npx -y @modelcontextprotocol/server-github"; fail-on: high | medium | none

Chaos tester: find the calls your agent would run twice

agentraas-chaos sits between your code and an API. The first time each distinct write request (POST/PUT/PATCH/DELETE) arrives, it lets the request execute and then drops the response, the network failure that turns a retry into a double charge. Then it reports every action that executed more than once.

pip install agentraas

Safe: a built-in mock answers every call, nothing real is touched

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

Against a real API: use TEST-mode keys

agentraas-chaos --upstream https://api.stripe.com -- pytest

Your command gets AGENTRAAS_CHAOS_URL (e.g. http://127.0.0.1:8787); use it as the API base URL. Without a command it runs until Ctrl-C, so you can point an n8n workflow or any other tool at it by hand.

agentraas-chaos: 6 write requests, 3 responses dropped after execution

DUPLICATES: 1 action(s) executed more than once

2x POST /v1/charges (body sha256 623f14d1b00d) ... Protected by an idempotency key: 2 retries

It exits with code 1 when it finds a duplicate, so it can fail CI. --fault error-after-commit returns a 502 instead of dropping the connection. A retry that repeats an Idempotency-Key it has already seen is counted as protected, not executed again.

In GitHub Actions:

- uses: actions/setup-python@v5

with: { python-version: "3.12" }

• uses: agentraas/agentraas/src/chaos-action@main with: run: python my_agent.py

Keep rules in Git: agentraas apply

Describe a server's dedup rules, validation rules, action policies and spend caps in YAML, review them like code, and apply them from CI:

pip install "agentraas[apply]"

# agentraas.yaml

apiVersion: agentraas.io/v1alpha1 kind: DedupRule metadata: {name: charge-once, org: org_acme} spec: {service: stripe, action: charges.create, fields: [customer, amount], ttlSeconds: 300}

---

apiVersion: agentraas.io/v1alpha1 kind: SpendCap metadata: {org: org_acme} spec: {service: stripe, action: refunds.create, window: day, maxCalls: 100, onExceed: block}

export AGENTRAAS_URL=https://agentraas.example.com AGENTRAAS_EMAIL=ci@acme.com AGENTRAAS_PASSWORD=...

agentraas apply -f agentraas.yaml --dry-run # print the plan agentraas apply -f agentraas.yaml # create what's missing, replace what changed agentraas apply -f agentraas.yaml --prune # also delete rules the file doesn't list

Kinds: DedupRule, ValidationRule, ActionPolicy, SpendCap. Spec keys are the API's fields in camelCase. Running it twice changes nothing.

Local tunnel: test webhooks against your laptop

agentraas tunnel prints a public URL and replays every request sent to it against a local port, so you can point Stripe, GitHub or n8n webhooks at code you haven't deployed. Needs a free AgentRaaS account (an agent API key).

pip install "agentraas[tunnel]"

agentraas tunnel --port 3000 --org org_acme --agent agent_1 --key ar_live_...

One tunnel per org, 2-hour sessions, 30-second local response timeout.

Send one action from the shell: agentraas call

Every command also runs under the short name agtrs. call sends one action through an AgentRaaS server and prints the answer as JSON: the same dedup, policies, approvals and audit as the Client. Handy for scripts and for checking a rule by hand.

export AGENTRAAS_KEY=ar_live_... AGENTRAAS_ORG=org_acme AGENTRAAS_AGENT=agent_1

export AGENTRAAS_URL=https://agentraas.io # default http://localhost:13000 agtrs call stripe charge.create '{"amount": 4999, "currency": "usd"}' echo '{"text": "hi"}' | agtrs call slack message.post -

--key, --org, --agent, --url and --idempotency-key override the environment. A rejected call prints the error and its hints and exits 1.

Approve held calls from the shell

The same list as the dashboard's Waiting for approval, for any org you can write to. Logs in like apply (AGENTRAAS_EMAIL / AGENTRAAS_PASSWORD against AGENTRAAS_URL, default https://agentraas.io).

agtrs approvals                  # req id, service, action, agent, payload

agtrs approve req_abc123 # runs the call; asks first (--yes to skip) agtrs deny req_abc123

approve exits 1 if the call ran and failed (it is then in Failed requests). Without a terminal it refuses unless --yes is passed, so a script never approves by accident.

Read the audit log from the shell

Every call in the orgs you belong to, newest first, with the same login as approvals:

agtrs audit                      # last 50: time, status, service action, agent, org, duration, req id, error

agtrs audit -n 200 --json # adds run/step ids, dedup hash, redacted payload preview (max 1,000) agtrs audit --csv > audit.csv # the dashboard's CSV export (newest 10,000)

Failed calls from the shell

Calls that failed and were kept (the dashboard's Failed requests), with the same login as approvals:

agtrs dlq                        # id, time, service action, agent, org, req id, error

agtrs dlq replay 42 # sends the call again with the same idempotency key; asks first (--yes to skip) agtrs dlq dismiss 42 # drop it without sending

replay exits 1 if the service fails again; the entry stays in the list.

Move dashboard rules into Git

agtrs rules prints the rules alr