SDK examples and private repositories

Use the SDK in an existing application or script, or keep Agent definitions, Skill packages, and prompt files in your own private Git repository. Erstan does not need access to that repository. There is no required manifest, directory layout, test runner, CI pipeline, or deployment framework.

These source links currently require access to the private beta SDK repository. See the SDK quickstart for package availability. The examples are optional, not an additional service or CLI.

Choose a sample

Sample	What it demonstrates
Run an Agent	Call a published Agent from plain JavaScript and handle its result or pause.
Human review	Inspect a pending approval and submit the user’s explicit decision for the exact interaction.
Skill package round trip	Convert complete Skill JSON/ZIP packages offline with `@erstan/skill-package`, retaining related files and actions.
Agents in Git	Export content and guards, validate, save a draft, optionally preview it, and publish separately.

Each sample has its own prerequisites and instructions. Only the Skill package round trip is entirely offline. Runs and previews execute real hosted tools and can incur cost or external effects.

Keep human decisions explicit

For an approval interface, present the interaction to the user first. Pass their decision and the exact interaction they saw to a function such as this:

/** @param {import('@erstan/sdk').ErstanClient} client */
export async function submitApproval(client, { runId, interactionId, action }) {
  if (!['approve', 'reject'].includes(action)) {
    throw new Error('An explicit approve or reject decision is required.');
  }
  const run = await client.runs.get(runId);
  const pending = run.pendingInteraction;
  if (run.interruptDisposition !== 'actionable'
      || pending?.type !== 'approval'
      || pending.interactionId !== interactionId) {
    throw new Error('The interaction changed; show the current one to the user.');
  }
  return client.runs.decideApproval(runId, { interactionId, action });
}

The server rechecks the interaction at write time. Do not retry an uncertain decision blindly; inspect the run first. User-input waits instead use runs.reply with their exact interaction ID. Use the creating API key throughout. See the SDK reference for waiting and continuation.

Keep Agents and Skills in Git

The Agents-in-Git sample uses ordinary JavaScript files. You can copy only the parts you need and use any Git host. A typical optional flow is:

Export current authoring content with its resource ID, workspace ID, and opaque revision. Review exports for sensitive content before committing.
Edit Agent fields or the complete Skill package. Keep related files, action metadata, and unknown fields intact. Prompts can be ordinary text files your code reads into Agent instructions or Skills; there is no separate hosted Prompt synchronization API.
Check client.context.get() against the intended workspace and capabilities. Validate the candidate, then save only when you intend a remote draft update. Keep the server-returned content and revision together.
Preview only if useful and explicitly intended. Preview executes the saved remote draft, not unsaved files. Exact Skill selections are top-level { skillId, version } entries, subject to edit access and Agent policy.
Publish the exact approved content separately. Publish required Skills first; no implicit dependency publication or atomic multi-resource deployment exists.

A 412 means another author changed the resource: compare and reconcile, not overwrite. Never attach a newly fetched revision to stale local edits. Historical versions are read-only. Reuse one idempotency key only for the same mutation intent; recover or reconcile lost responses before a new mutation. If the remote write succeeded but a local file save failed, do not repeat the remote write under a fresh key. Two Git branches sharing a remote draft are not isolated environments. Target QA and production explicitly with the same SDK package and the appropriate credentials and resource identities. Do not treat a Git merge as permission to publish or to run an Agent.

Testing is optional

The sample includes one opt-in node:test preview assertion. It is skipped unless deliberately enabled, and is an example rather than an SDK dependency or publication gate. Importing the SDK or sample helpers does not run an Agent. Choose synthetic input and inspect possible tool effects before enabling a hosted test. Never provide Erstan credentials to unreviewed pull-request code. For application-only tests, the SDK’s fetch option allows a fake transport. That can test your code’s handling of responses and errors, but it does not simulate Agent execution or prove that a hosted integration works.

Developer API

JavaScript SDK (beta)

Partners

API Reference

SDK examples and private repositories

Choose a sample

Keep human decisions explicit

Keep Agents and Skills in Git

Testing is optional

​Choose a sample

​Keep human decisions explicit

​Keep Agents and Skills in Git

​Testing is optional

Choose a sample

Keep human decisions explicit

Keep Agents and Skills in Git

Testing is optional