Skip to main content

Agent Runtime: Plan, Pause, Report and Contain

guard() answers one question: may this action run now? Agents that move money need a few more answers around it:

NeedFeature
"Will this be allowed? How much budget is left?"simulate() and getCapabilities()
"A human is deciding. Don't hold a process open for an hour."Pause and resume with a signed callback
"The payout failed at the bank. Give the budget back."reportOutcome()
"This session read an email. Don't let it pay anyone without a human."Session taint
"My agent uses MCP tools."The MCP proxy

All of these need serverPolicy: true (the server-side policy). They work with act-only agent keys.


Plan before acting​

simulate(): what would happen?​

A dry run of one action against the current policy, usage and session. Nothing is recorded, no budget is reserved, and nobody is asked to approve.

const plan = await auditail.simulate({ action: 'create_payout', payload: { amount: 4200, beneficiary: { id: 'ben_7' } }, agentId: 'payout-agent', sessionId });
// { dryRun: true, decision: 'require_approval', code: 'approval_required', reason: 'Needs approval: payouts over $1,000 need a human.', ... }
plan = auditail.simulate("create_payout", {"amount": 4200, "beneficiary": {"id": "ben_7"}}, agent_id="payout-agent", session_id=session_id)

decision is allow, deny, require_approval, or unavailable if Auditail couldn't be reached. A dry run never carries a receipt.

getCapabilities(): what may I do, and how much is left?​

const caps = await auditail.getCapabilities({ agentId: 'payout-agent', action: 'create_payout', payload: { currency: 'EUR' } });

It returns the listed actions with whether each is allowed, frozen or disabled, the conditions that deny or need a human, the approver count, first-time rules, and each limit with used and remaining. Pass action and payload to see the budget for one beneficiary or currency (limits with groupBy or when). Pass sessionId to see whether the session is tainted.

{
"policyVersion": 12, "mode": "enforce", "unlistedActions": "denied",
"actions": [{
"action": "create_payout", "allowed": true,
"needsApprovalWhen": ["payouts over $1,000 need a human"],
"limits": [{ "limit": "daily", "window": "24h", "kind": "sum", "field": "amount", "max": 25000, "used": 9400, "remaining": 15600, "onExceed": "deny" }]
}],
"note": "A preview, not a reservation: another action may use the remaining budget before yours runs. ..."
}

Both are predictions, not reservations. Another agent can use the budget between the preview and guard(), and guard() is what decides.

Capabilities show an agent your thresholds. That's usually what you want: an agent that knows the limit splits a job sensibly instead of probing. If you'd rather not, set "introspection": false at the top of the policy, and /v1/capabilities returns 403 introspection_disabled. Dry runs still work, since they reveal no more than trying.


Pause and resume​

A human may take minutes or hours to decide. Long-running workflow engines don't want a process waiting that long, so guard() can return right away and Auditail calls you back.

const r = await auditail.guard({
action: 'create_payout', payload, agentId: 'payout-agent',
wait: false, // return now with pending: true
correlationId: workflowId, // your id, echoed in the approval and the callback
callbackUrl: 'https://your-app.example/hooks/auditail',
});
if (r.pending) { /* suspend: r.approval.id is the approval to resume */ }

When a human decides (approve, deny) or the request expires, Auditail POSTs to callbackUrl:

{ "type": "approval.decided", "createdAt": "...", "correlationId": "wf-123",
"approval": { "id": "apr_...", "status": "approved", "decidedBy": "Priya", "receipt": "atr1....", "correlationId": "wf-123", ... } }
  • It's signed like webhooks: X-Auditail-Signature: sha256=HMAC-SHA256(secret, "<X-Auditail-Timestamp>.<body>"). Verify the signature before you resume anything. An approver creates the secret once with PUT /v1/settings {"rotateSecret": true}; a callbackUrl is refused until one exists.
  • Failed deliveries are retried about once a minute, up to 5 attempts in total. Treat the callback as a wake-up call, not the only path: on wake-up, call resume(approvalId), which reads the current state once without waiting.
  • callbackUrl must be HTTPS and can't point at private addresses.
const res = await auditail.resume(approvalId);
// { status: 'approved', approved: true, pending: false, code: 'approved_by_human', receipt: 'atr1....', approval: {...} }

resume() returns pending: true if nobody has decided yet, and status: 'unavailable' (treat it as denied) if Auditail can't be reached.

Retries are safe: idempotency keys​

With serverPolicy, every guard() call sends an idempotency key, so a network retry inside the SDK can't open a second approval or count usage twice. Pass your own idempotencyKey to make retries across process restarts safe, for example the workflow's activity id. Rules:

  • The same key returns the original decision (header Idempotent-Replay: true).
  • The same key with a different action, agent or payload is refused (422 idempotency_mismatch). Use a new key per action.
  • Keys are kept for 7 days. Failed requests (for example 503 under contention) don't use up the key.

Temporal​

Workflow code can't make network calls, so guard() runs in an activity and the callback becomes a signal.

// workflows.ts
import { proxyActivities, defineSignal, setHandler, condition, workflowInfo } from '@temporalio/workflow';
const { requestPayout, resumeApproval, executePayout } = proxyActivities<typeof activities>({ startToCloseTimeout: '1 minute' });
export const approvalDecided = defineSignal<[string]>('approvalDecided');

export async function payoutWorkflow(payout: Payout) {
let decided = false;
setHandler(approvalDecided, () => { decided = true; });
const r = await requestPayout(payout, workflowInfo().workflowId); // guard({ wait: false, correlationId, callbackUrl, idempotencyKey })
let receipt = r.receipt;
if (r.pending) {
await condition(() => decided, '24 hours');
const res = await resumeApproval(r.approvalId); // auditail.resume()
if (!res.approved) return { status: 'not_approved', reason: res.reason };
receipt = res.receipt;
}
return executePayout(payout, receipt);
}

// your callback handler: verify the signature, then
await temporalClient.workflow.getHandle(body.correlationId).signal(approvalDecided, body.approval.id);

In the requestPayout activity, build idempotencyKey from the workflow id and the activity id (both stay the same across Temporal's activity retries), so a retried activity doesn't open a new approval.

Inngest​

export const payout = inngest.createFunction({ id: 'payout' }, { event: 'app/payout.requested' }, async ({ event, step }) => {
const r = await step.run('guard', () => auditail.guard({ action: 'create_payout', payload: event.data, agentId: 'payout-agent',
wait: false, correlationId: event.id, callbackUrl: CALLBACK_URL, idempotencyKey: `payout-${event.id}` }));
let receipt = r.receipt;
if (r.pending) {
const decided = await step.waitForEvent('wait-for-approval', {
event: 'auditail/approval.decided', timeout: '24h', if: `async.data.correlationId == "${event.id}"`,
});
const res = await step.run('resume', () => auditail.resume(r.approval!.id));
if (!decided || !res.approved) return { status: 'not_approved' };
receipt = res.receipt;
}
await step.run('execute', () => executePayout(event.data, receipt));
});

// your callback handler: verify the signature, then
await inngest.send({ name: 'auditail/approval.decided', data: { correlationId: body.correlationId, approvalId: body.approval.id } });

LangGraph​

LangGraph pauses a graph with interrupt() and resumes it with Command(resume=...) on the same thread (a checkpointer is required).

from langgraph.types import interrupt, Command

def pay(state):
r = auditail.guard("create_payout", state["payout"], agent_id="payout-agent", wait=False,
session_id=state["thread_id"], correlation_id=state["thread_id"], callback_url=CALLBACK_URL,
idempotency_key=f"{state['thread_id']}-pay")
if r.pending:
approval_id = interrupt({"waiting_for": r.approval.id}) # the graph stops here
res = auditail.resume(approval_id)
if not res["approved"]:
return {"result": f"not approved: {res['reason']}"}
return {"result": execute_payout(state["payout"], res["receipt"])}
if not r.approved:
return {"result": f"blocked: {r.reason}"}
return {"result": execute_payout(state["payout"], r.receipt)}

# your callback handler: verify the signature, then
graph.invoke(Command(resume=body["approval"]["id"]), config={"configurable": {"thread_id": body["correlationId"]}})

The node runs again from the top when resumed, which is why the idempotency key matters: the second guard() returns the original decision instead of opening a new approval.


Report what happened​

An approval says a payout may run. It doesn't say whether the money moved. Record the outcome against the decision (its auditId, or the receipt):

await auditail.reportOutcome({ receipt }, { status: 'settled', externalTxId: 'po_8812' });
await auditail.reportOutcome({ auditId: r.auditId }, { status: 'failed', externalTxId: 'po_8812', reason: 'IBAN rejected by bank' });
// a refund decision that reverses an earlier payout:
await auditail.reportOutcome({ auditId: refund.auditId }, { status: 'settled', compensates: original.auditId });
auditail.report_outcome("settled", receipt=receipt, external_tx_id="po_8812")

status is settled, failed, reversed, refunded or voided. Each outcome is an event in the hash-chained log, and GET /v1/outcomes?auditId= lists the outcomes of a decision together with any that compensate it.

Who is believed. A failed or voided outcome gives the amount back to your limits, since the money never moved. Only trusted reports do that:

  • a report made with an approver token (for example from your back office or settlement job),
  • a signed event from a connected payment provider: Airwallex payout.transfer.paid / payout.transfer.failed, Modern Treasury completed / failed / returned are recorded automatically.

A report made with an agent key is recorded but changes nothing. Otherwise an agent could report "failed" to free its budget and pay again. settled, reversed and refunded never change usage. The same report twice is recorded once (duplicate: true).


Session taint after untrusted content​

Provenance (source, fieldSources) covers data you can point at in the payload. Prompt injection is often less direct: the agent reads an email, then three steps later "decides" to pay someone. Session taint covers that. Once a session has read untrusted content, money-moving actions in the same session need a human.

const sessionId = conversation.id;
const email = await readInbox();
await auditail.markUntrusted(sessionId, 'inbound_email', `message ${email.id}`); // in your tool code, not the model
// ... later, in the same session:
await auditail.guard({ action: 'create_payout', payload, agentId: 'payout-agent', sessionId });
// -> needs approval, code "tainted_session": "this session read untrusted data (inbound_email: message 1882) since ..."
auditail.mark_untrusted(session_id, "inbound_email", f"message {email.id}")
auditail.guard("create_payout", payload, agent_id="payout-agent", session_id=session_id)
  • A guard() call with a sessionId and an untrusted source or fieldSources value also taints its session, after the decision. Dry runs never taint.
  • Per action, taintedSession in the policy sets what happens: "require_approval", "deny" or "allow". It defaults to the action's untrustedSource, then to "require_approval". Actions without sessionId aren't affected.
  • Taint lasts 24 hours from the last untrusted read. Only an approver can clear it early: POST /v1/sessions/{id}/clear. Tainting and clearing are both in the audit log.
  • GET /v1/sessions/{id} shows the state and the sources that tainted it.

Limits, plainly. Auditail can't see inside the model. Taint is only as complete as your calls to markUntrusted() (or the MCP proxy's untrusted tools), and it's deliberately coarse: after one untrusted read, every money-moving action in the session needs a human, whether or not it used that content. Start a new session for work that shouldn't inherit it.


MCP proxy​

If your agent calls tools over the Model Context Protocol, auditail-mcp-proxy sits between the MCP client and the server and decides every tools/call before it reaches the server. No change to the server is needed.

AUDITAIL_API_KEY=atl_live_... npx -p auditail-sdk auditail-mcp-proxy --config auditail-mcp.json -- npx -y @acme/payments-mcp

In an MCP client's config (Claude Desktop, Cursor and others), replace the server's command with the proxy:

{
"mcpServers": {
"payments": {
"command": "npx",
"args": ["-y", "-p", "auditail-sdk", "auditail-mcp-proxy", "--config", "/path/auditail-mcp.json", "--", "npx", "-y", "@acme/payments-mcp"],
"env": { "AUDITAIL_API_KEY": "atl_live_...", "PAYMENTS_API_KEY": "..." }
}
}
}

auditail-mcp.json:

{
"agentId": "claude-payments",
"tools": {
"create_payout": { "action": "create_payout", "payload": { "amount": "amount", "currency": "currency", "beneficiary.id": "recipient_id" } },
"get_balance": { "mode": "allow" },
"read_inbox": { "mode": "allow", "untrusted": "inbound_email" },
"fetch_url": { "mode": "allow", "untrusted": "web" },
"delete_account": { "mode": "deny" }
},
"unlisted": "guard"
}
FieldMeaning
tools.<name>.modeguard (default): ask Auditail. allow: pass without a decision, for read-only tools. deny: always block.
tools.<name>.actionThe action name in your policy. Default mcp.<tool name>.
tools.<name>.payloadMap policy fields to argument paths. Default: the arguments as they are. The arguments sent to the server are never changed.
tools.<name>.untrustedThis tool returns outside content. Calling it taints the session with this source name.
unlistedTools not in tools: guard (default, so your policy's defaultAction applies), allow or deny.
waittrue holds the tool call until a human decides. Default false.
injectReceiptAdd the signed receipt to the forwarded call as params._meta["io.auditail/receipt"], so a server can check it. Default true.

What the agent sees when a call isn't allowed is a normal tool error (isError: true) with the reason and what to do next, so it can tell the user. When a call needs a human, the agent is told to ask the user and call the tool again with the same arguments. That second call resumes the same approval instead of opening another, and runs the tool once approved.

How it works:

  • Only tools/call requests are inspected. Everything else, including initialize, tools/list, notifications and requests from the server to the client (older protocol versions), passes through unchanged in both directions. It works with initialization-based protocol versions and with the stateless revision.
  • The proxy is one session for taint: one id per proxy process, or set --session / AUDITAIL_SESSION_ID. Many MCP clients keep one server process across conversations, so taint can carry over between them for up to 24 hours. That's conservative; clear it as an approver if needed.
  • If Auditail can't be reached, the call is blocked (fail closed). If an untrusted tool's taint can't be recorded, that tool is blocked too, so the content never reaches the agent unrecorded.
  • Logs go to stderr. stdout carries only protocol messages.

Your own MCP server or client. Use the same logic in-process, for example in a Streamable HTTP server:

import { Auditail } from 'auditail-sdk';
import { McpGuard } from 'auditail-sdk/dist/mcp';

const guard = new McpGuard(new Auditail({ apiKey, serverPolicy: true }), { agentId: 'my-agent', sessionId, tools: { /* as above */ } });
const v = await guard.check(request.params); // before running a tools/call
if (!v.forward) return v.result; // the error result to send back
// run the tool with v.params

Limits, plainly. The proxy covers tool calls that go through it. A model with another route to the same API (a second MCP server, its own HTTP tool) isn't covered, so keep payment credentials out of reach of anything that isn't proxied, or check receipts where the payment executes. The bundled proxy speaks stdio. For a remote HTTP MCP server, run it through a stdio bridge such as mcp-remote behind the proxy, or use McpGuard in your own server.