JavaScript SDK quickstart

@erstan/sdk is the JavaScript ESM client for Erstan, with TypeScript declarations. Use Node.js 22 or later. Agents execute in Erstan with their saved connections, permissions, and approval policies; the SDK is not an offline Agent engine. You do not need a CLI, repository template, test runner, or backend checkout.

The SDK is currently an unpublished private beta (0.1.0-beta.1). It is not available from the public npm registry. Beta users need a reviewed package tarball from Erstan or access to the private SDK repository. Publishing these docs does not publish the package or enable authoring for your workspace.

Install the beta package

Install the reviewed archive into your existing Node.js project, using its actual local path:

npm install ./erstan-sdk-0.1.0-beta.1.tgz

Developers with access to the private SDK repository can follow its package build instructions to produce the archive. That repository and the sample links require beta access; without it, use the public REST quickstart. The SDK and the coding-agent plugin are independent. The plugin uses host-managed OAuth; the SDK uses a scoped API key in trusted application code. Neither installs or updates the other.

Configure a run

Create a key using API Keys. Starting and observing a run requires agents:run and runs:read; discovery also requires agents:list. The key creator must retain access to the Agent. Configure these values in your trusted local or server environment:

Variable	Value
`ERSTAN_API_KEY`	The scoped key; never commit it or expose it in browser code.
`ERSTAN_API_BASE`	`https://api.erstan.com` for production or `https://api-qa.erstan.com` for QA. Use an origin without `/v1`.
`ERSTAN_AGENT_ID`	An explicitly selected published Agent.
`ERSTAN_LANE_ID`	A chat lane from that Agent’s published lane details.
`ERSTAN_IDEMPOTENCY_KEY`	A stored key for this one logical launch; reuse only with identical intent on retry.

Use the same SDK package for either environment, with that environment’s credential and Agent IDs. Do not fall back from QA to production when a request fails. Keep secrets and sensitive results out of Git and unreviewed CI jobs.

Run a published Agent

Save this as run.mjs. The example deliberately selects a chat lane; structured lanes require an input object matching their own advertised schema.

import { ErstanClient, ErstanError } from '@erstan/sdk';

function required(name) {
  const value = process.env[name];
  if (!value) throw new Error(`Set ${name} before running this example.`);
  return value;
}

const client = new ErstanClient({
  apiKey: required('ERSTAN_API_KEY'),
  apiBase: required('ERSTAN_API_BASE'),
});

try {
  const result = await client.agents.runAndWait(required('ERSTAN_AGENT_ID'), {
    laneId: required('ERSTAN_LANE_ID'),
    input: { message: 'Hello from my application.' },
    idempotencyKey: required('ERSTAN_IDEMPOTENCY_KEY'),
  }, { waitTimeoutMs: 300_000 });

  console.log('Run:', result.run.runId, 'Outcome:', result.reason);
  if (result.reason === 'completed') {
    console.log(result.run.finalResponse);
  }
  // An interaction or other pause needs application/user handling, not a new run.
} catch (error) {
  if (error instanceof ErstanError && error.runId) {
    console.error('Resume observation of this accepted run:', error.runId);
  }
  throw error;
}

When you intend a live execution, run:

node run.mjs

A run can incur costs and external effects. Importing the SDK does not start work, but calling run or runAndWait does. The SDK never answers approval or user-input waits automatically. Do not start a replacement run just because observation timed out: the original run may still be executing.

runAndWait returns completed, failed, cancelled, interaction, waiting, or unknown_status as its reason. An Agent failure is a result, not necessarily an HTTP exception. Validate the shape of finalResponse before using it in application logic. Use runs.wait(runId) to resume observation with the exact key that started the run. A rotated or replacement key cannot read its runs. Continue with the SDK reference for methods, configuration, authoring, and recovery, or optional examples for human review and keeping Agent/Skill files in your own repository.

Developer API

JavaScript SDK (beta)

Partners

API Reference

JavaScript SDK quickstart

Install the beta package

Configure a run

Run a published Agent

​Install the beta package

​Configure a run

​Run a published Agent

Install the beta package

Configure a run

Run a published Agent