Quickstart

This walkthrough connects a TypeScript application and requests a decision for a refund. It makes no provider call.

Connect the agent

In Agents, select Add agent, then API or SDK. Name the agent, choose TypeScript, and create its key.

Store these values in the service that dispatches agent actions:

• ACTERA_API_KEY: the one-time connection key.
• ACTERA_AGENT_ID: the exact agent ID in the setup example.

Install the SDK

Use Node.js 22 or later and an ES module project. Install the public npm package:

npm install --save-exact @actera-ai/sdk@0.0.3

The npm scope is @actera-ai. This guide is checked against version 0.0.3. The SDK is an alpha release; pin an exact version and review release notes before upgrading. Keep the connection key on a trusted server, never in browser code.

Request a decision

import { ActeraClient, fromApiKey } from '@actera-ai/sdk'

const client = new ActeraClient({
  credentials: fromApiKey(process.env.ACTERA_API_KEY!),
})
const agent = client.agent({ agentId: process.env.ACTERA_AGENT_ID! })

const decision = await agent.authorizeAction({
  action: {
    type: 'refund.create',
    attributes: { amount_minor: 8000, currency: 'GBP', customer_id: 'cus_123' },
  },
  context: { customer: { fraud_flagged: false } },
  mode: 'ENFORCING',
  idempotencyKey: 'refund-request-01842',
})

console.log({ decisionId: decision.id, effect: decision.effect })

The SDK connects to Actera’s production API by default; no URL configuration is needed. The request represents an £80 refund. The key binds it to the agent and workspace. An API error must stop this flow; do not treat a missing decision as Allow.

The first request appears in Decisions and completes the connection step. New agents default to Allow when no rule matches, so an initial Allow does not demonstrate policy coverage.

Define and verify authority

Create and test a policy for refund.create. For example, allow low-value refunds, require approval above a selected threshold, and block flagged customers. Use integer GBP minor units consistently.

Publish the policy, assign it on the agent’s page, review When no policy matches, and save.

Send new requests with distinct idempotency keys to exercise each outcome. Inspect the recorded policy version and reason in Decisions. Reusing a resolved request’s key returns its original result, so it will not test a newly published version.

Integrate the real action

Before connecting a refund provider, implement all three branches:

• Allow: dispatch the recorded action with a stable provider idempotency key, then report its result.
• Require approval: retain the operation and pause. Resume only after the appropriate approval.
• Block: stop without calling the provider.

The TypeScript integration covers outcome reporting and error handling. Use the MCP continuation when a tool call needs a durable approval and resume flow.

Actera’s request idempotency prevents duplicate decisions. Your application must also prevent duplicate provider calls.