> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erstan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK examples and private repositories

> Small optional samples for runs, human review, complete Skill packages, and Agents in Git.

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.

<Info>
  These source links currently require access to the private beta SDK repository.
  See the [SDK quickstart](/developers/sdk-quickstart) for package availability.
  The examples are optional, not an additional service or CLI.
</Info>

## Choose a sample

| Sample                                                                                                                  | What it demonstrates                                                                                                |
| ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| [Run an Agent](https://github.com/erstanai/erstan-agent-toolkit/tree/main/examples/run-agent)                           | Call a published Agent from plain JavaScript and handle its result or pause.                                        |
| [Human review](https://github.com/erstanai/erstan-agent-toolkit/tree/main/examples/human-review)                        | Inspect a pending approval and submit the user's explicit decision for the exact interaction.                       |
| [Skill package round trip](https://github.com/erstanai/erstan-agent-toolkit/tree/main/examples/skill-package-roundtrip) | Convert complete Skill JSON/ZIP packages offline with `@erstan/skill-package`, retaining related files and actions. |
| [Agents in Git](https://github.com/erstanai/erstan-agent-toolkit/tree/main/examples/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:

```js theme={null}
/** @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](/developers/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:

1. Export current authoring content with its resource ID, workspace ID, and
   opaque revision. Review exports for sensitive content before committing.
2. 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.
3. 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.
4. 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.
5. 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.