AuctraDeveloper & SDK integration
Auctra SDK: evaluateAction quickstart
Install @auctra/sdk, register an agent with a sponsor, and run your first pre-action evaluation in minutes—free on Auctra Builder with seven-day audit.
May 30, 2026 · 5 min read · Markdown version
Install and configure
Add @auctra/sdk to your project and set AUCTRA_API_KEY from the Auctra console. Use environment-specific keys for staging and production.
Import Auctra, create a client with your API key, and call evaluateAction with agentId, actionType, and an optional payload. The client returns allowed, blocked, or require_approval with an action_request_id.
Minimal example
Before executing a refund tool, call auctra.evaluateAction({ agentId, actionType: 'refund_issue', payload: { amount, currency: 'USD', target } }, { idempotencyKey }). Branch on result.decision before calling your payment API.
Register the agent and sponsor in console first; create a delegation covering refund_issue with a test limit. Builder free tier is sufficient for quickstart validation.
Error handling
Treat network errors on monetary paths as fail-closed in your application. Catch AuctraApiError to log status, code, requestId, and structured details.
Pass idempotencyKey as the second evaluateAction option and reuse it when retrying the same logical action. The SDK retries only reads and idempotent evaluations; it never retries non-idempotent writes.
Next steps
Add LangChain or MCP wrappers from the integration guide. Promote to Team when you need ninety-day audit and accountability reports.
Auctra ties sponsors, expiring delegations, and pre-action evaluation into one accountability chain your security and finance teams can audit.
Key takeaways
- Authority is enforced before side effects — use API keys and evaluateAction together.
- Every production agent needs a named sponsor and bounded delegation visible in the console.
- Blocked and approval-required outcomes are evidence, not failures — review them in API keys.
Implementation checklist
- Sign up at console.auctra.tech and open API keys (/console/api-keys).
- Register one agent with a named human sponsor accountable for its actions.
- Create a narrow delegation aligned with this article's workflow (Auctra SDK).
- Call evaluateAction from your agent or SDK before the consequential tool executes.
- Confirm sponsor, delegator, decision, and outcome appear in Audit or API keys.
People also ask
- How do I call evaluateAction?
- Install @auctra/sdk, authenticate with your API key, and submit structured action intent before downstream execution.
- Is there a free tier for the Auctra SDK?
- Yes. Builder plan is free and includes SDK access with seven-day audit retention.
- What languages does the Auctra SDK support?
- TypeScript/JavaScript is primary; REST API works from any language.
Try in Auctra Console
Maps to: API keys
Pilot sdk quickstart in Auctra Console
Use API keys to apply this guide — register an agent, delegate authority, evaluate one real action, and inspect the audit trail. Free on Builder.
- Create a free account: https://console.auctra.tech/auth/signup?utm_source=blog&utm_medium=cta&utm_campaign=auctra-sdk-evaluate-action-quickstart
- In API keys (https://console.auctra.tech/console/api-keys), undefined for one production workflow.
- Install @auctra/sdk (npm install @auctra/sdk), create an API key in API keys, and wrap your integration's tool calls with evaluateAction.
- Integrate evaluateAction (SDK or REST) before money, data, or infrastructure changes execute.
- Open Audit to verify sponsor, delegator, reviewer, and decision are recorded.
Part of guide
Developer & SDK integration
evaluateAction patterns, LangChain and MCP integration, idempotency, and shipping authority checks before production traffic.
Browse full guide →Related guides
Make authority executable.
Evaluate agent actions against bounded, expiring delegation before they reach the real world. Start free on Builder — upgrade when audit retention and accountability matter.