@auctra/sdk

Official TypeScript SDK for Auctra — authority infrastructure for AI agents.

Evaluate every agent action against delegated authority and org policies before execution.

| Resource | URL | | -------------------------- | ------------------------------------------------------------- | | Console | https://console.auctra.tech | | Sign up (free Builder) | https://console.auctra.tech/auth/signup | | Docs | https://auctra.tech/docs | | OpenAPI 3.1 | https://console.auctra.tech/v1/openapi.json | | API base URL | https://console.auctra.tech (default — no baseUrl needed) |

Install

npm install @auctra/sdk

Both ESM (import) and CommonJS (require) entry points are included.

Quick start — evaluateAction

Copy-paste this before any consequential agent side effect (payments, refunds, prod changes, CRM writes):

import { Auctra } from "@auctra/sdk";

const auctra = new Auctra({
  apiKey: process.env.AUCTRA_API_KEY!,
  timeoutMs: 10_000,
  maxRetries: 2,
});

const decision = await auctra.evaluateAction(
  {
    agentId: "your-agent-uuid",
    actionType: "send_payment",
    payload: { amount: 1200, currency: "USD" },
  },
  { idempotencyKey: crypto.randomUUID() },
);

if (decision.decision === "allowed") {
  // proceed with action
} else if (decision.decision === "require_approval") {
  // pause for human review in console.auctra.tech/console/reviews
  console.log(decision.reason, decision.action_request_id);
} else {
  throw new Error(decision.reason);
}

Trust infrastructure (0.3.5+)

Declare why an action is happening and trace it back to human-approved intent:

const intent = await auctra.createIntent({
  title: "Renew SaaS contracts under $500/month for Q3",
  description: "Procurement agent may renew eligible vendor subscriptions.",
});

const decision = await auctra.evaluateAction({
  agentId: "your-agent-uuid",
  actionType: "send_payment",
  claimedIntentId: intent.intent.id,
  intentAnchorToken: intent.intent.anchor_token,
  action: {
    target: "vendor:slack",
    description: "Renew Slack Team plan",
    riskLevel: "medium",
  },
  payload: { amount: 420, currency: "USD" },
});

console.log(decision.intelligence?.trust_summary);

Production control behavior

• Anchored intents require the matching intentAnchorToken; token possession never bypasses expiry, risk, action-type, target, or resource bounds.
• Count and monetary velocity limits are reserved atomically before a decision. Reuse the same idempotency key for retries of the same business action.
• Custom action types use lowercase namespaced IDs such as healthcare.ehr.modify_prescription and recursively validated JSON payload schemas. Breaking schemas should use a new namespaced action ID.
• Proposed policies can be replayed against up to 10,000 recorded actions in the console before publication.
• Restricting an agent quarantines its delegations; reactivation can restore only those quarantined grants. Emergency fleet control is available in the console.

Get an API key

1. Sign up and create an organization
2. Register an agent and delegate scoped authority
3. Open API Keys → Create API key
4. Use a key with write permission for evaluateAction

API

| Method | Description | | ------------------------------------------- | --------------------------------------------------------------- | | evaluateAction(input, options) | Idempotently check authority + trust trace before an agent acts | | listIntents() | List human-approved intents | | createIntent(input) | Declare a new intent | | updateIntent(id, input) | Update intent metadata or lifecycle status | | updateIntentStatus(id, status) | Change intent lifecycle status | | getIntent(id) | Get intent detail and linked actions | | getAuthorityGraph() | Fetch authority graph nodes and edges | | createAuthorityEdge(input) | Add a validated authority edge | | getActionEvaluation(actionRequestId) | Get decision record for an action | | getRootIntentChain(actionRequestId) | Get root human intent chain (trust trace) | | listAgents() | List registered agents | | createAgent(input) | Register a new agent | | updateAgentStatus(id, input) | Restrict, suspend, reactivate, or mark an agent compromised | | deleteAgent(id) | Remove an agent with no evaluated actions | | getAgent(id) | Get one registered agent | | listDelegations() | List authority delegations | | getDelegation(id) | Get one authority delegation | | createDelegation(input) | Grant bounded authority | | revokeDelegation(id) | Revoke a delegation | | listActionRequests() | List recent evaluations | | approveActionRequest(id, approverUserId) | Approve as an accountable reviewer | | rejectActionRequest(id, approverUserId) | Reject as an accountable reviewer | | escalateActionRequest(id, approverUserId) | Escalate as an accountable reviewer | | listPolicies() | List org policies | | createPolicy(input) | Create an org policy | | listAuditEvents() | List audit ledger events | | listApiKeys() | List API key metadata |

REST API (curl)

curl -X POST https://console.auctra.tech/v1/action-requests/evaluate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "your-agent-uuid",
    "action_type": "send_payment",
    "payload": { "amount": 100, "currency": "USD" }
  }'

The SDK applies bounded retries only to reads and idempotent evaluations. API failures throw AuctraApiError with status, optional structured details, and the server requestId.

The machine-readable OpenAPI 3.1 contract is available at https://console.auctra.tech/v1/openapi.json.

Integration guides (blog)

Stack-specific walkthroughs with console steps:

| Stack | Guide | | ----------------- | ---------------------------------------------------------------- | | LangChain + MCP | https://auctra.tech/blog/langchain-mcp-authority-integration | | OpenAI Agents SDK | https://auctra.tech/blog/openai-agents-sdk-authority-integration | | Vercel AI SDK | https://auctra.tech/blog/vercel-ai-sdk-evaluate-action-hook | | Stripe payments | https://auctra.tech/blog/stripe-agent-payments-authority-layer |

License

MIT