SERVER SDK

CREATE A SESSION

import { AStackSDK } from '@aether-stack-dev/developer-sdk';

const sdk = new AStackSDK({
  apiKey: process.env.ASTACK_API_KEY!,
  apiEndpoint: process.env.ASTACK_API_ENDPOINT!,
  provisioningTimeoutMs: 300_000,
});

// Resolve userId through your application's authentication system.
const userId = 'authenticated-app-user';
const result = await sdk.createSession(userId, { idempotencyKey: 'stable-request-id' });
const browserConnection = {
  sessionId: result.session.id,
  sessionToken: result.token,
  gatewayUrl: result.credentials.gatewayUrl,
  gatewayTransport: result.credentials.gatewayTransport,
  gatewayWsUrl: result.credentials.gatewayWsUrl,
  rendererPlayerUrl: result.credentials.rendererPlayerUrl,
  expiresAt: result.credentials.expiresAt,
};

Creation requires a key with session_create permission. The SDK waits through HTTP 202 provisioning responses. Reuse the same idempotency key when retrying a logical creation request.

SERVER-SIDE AGENT CONFIGURATION — UNRELEASED

The source SDK adds agentConfig at creation. This requires the matching server and gateway release; published SDK 0.5.0 does not include it yet. Keep private prompts and context on your backend.

const result = await sdk.createSession(userId, {
  idempotencyKey: 'stable-request-id',
  agentConfig: {
    systemPrompt: 'Follow our support policy.',
    priorContext: [{ role: 'user', content: 'Backend customer context' }],
    voice: 'server-voice',
    permittedOverrides: ['voice'],
  },
});

Configuration is pinned by default, including when omitted. Browser values only take effect for permittedOverrides fields: systemPrompt, priorContext, voice, contextPairs and configOverrides. Set mode: 'browser' explicitly to permit all of them. Prompts are excluded from credentials and session responses. Idempotent retries must keep the same configuration or receive HTTP 409. Per-session character selection is not supported.

These settings target self-hosted inference. The existing Deepgram BYOK mode supports only systemPrompt; unsupported configuration is rejected.

SESSION MANAGEMENT

Developer SDK 0.5.0 supports customer-owned session reads, lists and termination through the deployed session API. See the migration guide when upgrading from 0.4.0.

const status = await sdk.getSession(result.session.id);
const customerSessions = await sdk.listSessions(50, 0);
await sdk.terminateSession(result.session.id);
await sdk.destroy();

These operations require session_manage permission and apply to the customer identified by the backend key. Enforce your own end-user access separately. GET/list omit internal allocation metadata and credentials. DELETE finalizes billing and releases the runtime; retry it if release returns 503. Aborting creation only stops waiting.