Production and teams

Actaro receipts are useful for debugging, agent feedback, and audit trails. They can also contain action inputs and execution outputs, so production usage needs an explicit data policy.

Persist receipts intentionally

The default client uses an in-memory store. Use a dedicated store when receipts must survive a process restart:

import { createActaro, fileStore } from "actaro-sdk";

const actaro = createActaro({
  store: fileStore("./data/receipts.jsonl"),
});

fileStore() is a simple append-only JSONL store for local or small deployments. For a shared service, implement the asynchronous ReceiptStore interface with the database or durable store already used by the team.

Choose and document:

• retention and deletion rules;
• who can read receipt evidence;
• whether receipts are part of an audit record;
• how backups and encryption are handled.

Redact sensitive data

Configure recursive redaction before receipts are saved:

const actaro = createActaro({
  redaction: {
    fields: ["password", "apiKey", /token/i],
  },
});

Redaction is a safety aid, not a substitute for data minimization or access control. Verification evidence should contain the smallest useful proof, such as a resource ID and state, rather than a full API response.

Make verification reliable

The verifier should use a read path that is independent enough to detect a successful-looking but ineffective tool call. It should:

• distinguish verified, pending, and failed;
• return stable evidence that helps operators investigate;
• account for eventual consistency with a bounded retry policy;
• fail clearly when it lacks permission to read the resulting state.

Configure retry and timeout limits globally, then override them only for actions with different consistency requirements:

const actaro = createActaro({
  verification: {
    retries: 3,
    delayMs: 500,
    timeoutMs: 10_000,
  },
});

Use idempotency at side-effect boundaries

Set idempotencyKey(input) for payments, provisioning, messages, or any operation where repeating the same request could create a second real-world effect. The key should identify the intended operation, not the current attempt.

Actaro deduplicates concurrent requests and can retrieve a persisted receipt for a matching key. This protects the boundary between agent retries and external APIs; it does not replace the external API's own idempotency guarantees.

Observe without leaking secrets

Hooks can connect receipts to application logs or metrics:

const actaro = createActaro({
  hooks: {
    verificationAttempt: ({ action, attempt }) => {
      metrics.increment("actaro.verification_attempt", {
        action,
        attempt: String(attempt),
      });
    },
    receiptCreated: (receipt) => {
      metrics.increment(`actaro.receipt.${receipt.status}`, {
        action: receipt.action.name,
      });
    },
  },
});

Do not log raw inputs, outputs, or evidence from hooks unless the data policy explicitly allows it. Prefer identifiers, status, duration, and attempt count.