Action Integrity

Quickstart: SDK

Protect your first action with integrity.execute() from @audon/sdk, in TypeScript.

Protect one refund end to end: create an agent, connect Stripe, and call integrity.execute() from your agent’s code. About ten minutes. To give the agent MCP tools instead, see the Action Gateway.

1. Create an agent and an agent key

In the app, open Agents → New agent. Give it a name and slug (customer-support-agent), an owner and the actions it may run (refund.create). Then create a key on the agent. The secret (aa_agent_…) is shown once; store it where your agent runs.

2. Connect Stripe in execute mode

Under Integrations, add a Stripe connector with a restricted key (rk_…) that has only the write permissions the action needs (for refunds: read on Charges and Refunds, write on Refunds). Execute mode needs a signed-in person. See connectors.

Remove the agent’s direct access

From now on the agent reaches Stripe through Audon only. Remove any Stripe secret key from its environment, or the controls can be bypassed.

3. Install the SDK

Not on npm yet

@audon/sdk isn’t published to npm yet, so npm install won’t find it. Until it is, call the REST API (shown below), which is all the SDK does: everything on this page applies the same way. Ask us for the package if you want the typed client now.

bashInstall (once published)

npm install @audon/sdk

4. Execute an action

tsrefund.ts

import { Audon, idempotencyKey } from '@audon/sdk';

const audon = new Audon({ apiKey: process.env.AUDON_AGENT_KEY!, baseUrl: 'https://audon.ai' });

const result = await audon.integrity.execute({
  agent: 'customer-support-agent',     // optional: must match the key's agent
  action: 'refund.create',
  resource: 'ch_3QmX…',               // Stripe charge or payment intent
  amount: 45000,                       // minor units: USD 450.00
  currency: 'USD',
  idempotencyKey: idempotencyKey('refund', 'order_8812', 'ticket_5602'),
  reason: 'Customer reports the order never arrived',
});

switch (result.decision) {
  case 'allowed':          /* result.outcome: completed | failed | unknown | executing */ break;
  case 'denied':           /* tell the customer result.decision_reason; don't try another way */ break;
  case 'pending_approval': /* a person must approve: await audon.integrity.waitForOutcome(result.id) */ break;
  case 'would_deny':       /* monitoring: it ran, but would be blocked once you enforce */ break;
}

The same call over HTTP:

bashPOST /v1/integrity/actions

curl -X POST https://audon.ai/v1/integrity/actions \
  -H "Authorization: Bearer $AUDON_AGENT_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order_8812-ticket_5602" \
  -d '{ "action_type": "refund.create", "resource": "ch_3QmX…", "amount_minor": 45000, "currency": "USD" }'

Rules of the road

One idempotency key per intent. Reuse it on every retry of the same intent; a retry with the same key returns the original result (replayed: true) and never executes twice.
Decision and outcome are separate. decision says whether Audon allowed it; outcome says what actually happened at the provider.
Unknown is not failure. Don’t retry with a new key. Poll status(id) or waitForOutcome(id); call retry(id) only when retry_safe is true.
Amounts are integers in minor units of the currency (cents for USD, yen for JPY).
Retries in the client: network errors and HTTP 408, 429, 502, 503 and 504 are retried (honouring Retry-After) up to maxRetries (default 2), always with the same key.

Methods

Method	What it does
`integrity.execute(input)`	`POST /v1/integrity/actions` with `Idempotency-Key`
`integrity.status(actionId)`	`GET /v1/integrity/actions/{id}/status` (this agent’s actions only)
`integrity.retry(actionId)`	`POST /v1/integrity/actions/{id}/retry`, only when `retry_safe`
`integrity.waitForOutcome(id, opts)`	Polls until completed, failed or not executed
`idempotencyKey(...parts)`	A deterministic key from the parts of one intent

Errors are thrown as AudonError with code (unauthenticated, insufficient_scope, validation_failed, idempotency_conflict, entitlement_required, rate_limited, network_error, …), status, details and requestId. A denial is a result, not an error.

Write your first rule in policies, and switch from monitoring to enforcing once the Would deny results look right (modes).