TypeScript

Use the TypeScript SDK in the service that can stop or dispatch an agent action. Follow the Quickstart to install and create a client bound to the configured agent.

Install and import

The public package is @actera-ai/sdk, published under the actera-ai npm account. Use Node.js 22 or later and ES module imports.

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

This guide is checked against 0.0.3. The SDK is an alpha release, so pin the version and review the release notes before upgrading.

Import	Purpose
@actera-ai/sdk	Agent decisions, status, readiness, and execution reports.
@actera-ai/sdk/execution	Managed execution and recovery errors.
@actera-ai/sdk/mcp	MCP interception and approval continuation.
@actera-ai/sdk/mcp/node	Node.js invocation context.

The SDK connects to https://app.actera.dev by default. Standard integrations only need the agent ID and connection key; no API URL setting is required.

Authorize before dispatch

agent.authorizeAction() returns the decision’s id, effect, status, and explanation. Use mode: 'ENFORCING' for requests whose result you will apply.

Only ALLOW permits immediate execution. REQUIRE_APPROVAL pauses the operation, and BLOCK stops it. Treat an unexpected effect or a failed API request as an error.

Keep policy explanations in operator-facing diagnostics. Return an appropriate business message to the customer, without exposing internal decision identifiers or policy details.

Report the outcome

After a plain authorization request, use recordDecisionReport() to report the result. Reuse the exact action type and attributes from authorization.

import type { Action, BoundAgentClient } from '@actera-ai/sdk'

async function reportConfirmedSuccess(
  agent: BoundAgentClient,
  decisionId: string,
  action: Action,
  operationId: string,
) {
  return agent.recordDecisionReport({
    decisionId,
    idempotencyKey: operationId + ':success',
    action,
    outcome: 'SUCCESS',
    details: { summary: 'Refund completion confirmed by the provider.' },
  })
}

Call this only after verifying the outcome appropriate to your provider. A successful HTTP response may acknowledge a queued operation rather than its completion.

If report delivery fails, persist the report and retry it with the same key and body. Keep this retry separate from provider dispatch so a reporting failure cannot repeat the refund.

Use FAILURE when you know the operation did not complete. Use UNKNOWN when you cannot determine the outcome. An interrupted or cancelled request can still have reached the provider. See Report a decision outcome for the effect on cumulative usage.

Approval and managed execution

For a plain request, save the operation and decision ID before returning a pending result. Use getDecisionStatus(decisionId) to follow its authorization state. An approved status does not execute or deduplicate your provider call.

For captured operations, ActeraExecution from @actera-ai/sdk/execution coordinates claims, dispatch, and reports. Persist its handle and recovery state. The MCP guide demonstrates a complete managed continuation.

If managed reporting fails, ExecutionReportError exposes the report to persist and retry through reportActionExecution(). Retrying a report must not redispatch the action.

Requests and failures

The SDK accepts signal and timeoutMs request options. It does not automatically retry requests. Use bounded retries for transient failures, preserving the original input and idempotency key.

ActeraHttpError exposes HTTP status and structured error information. Correct authentication, permissions, and invalid input before retrying. Honor Retry-After where provided.

ActeraUnavailableError represents connectivity failures, timeouts, or HTTP 502, 503, and 504 responses. Handle availability separately from invalid input and permission errors. Neither error grants authority to execute.

Use Monitoring deliberately during rollout. The SDK call itself returns an effect; your application is responsible for enforcing it and reporting execution. It does not intercept unrelated calls.