# Embedding

Drive zot from another program.

Two ways to drive zot from another program. Both share the same event schema, so transcripts captured by one can be replayed through the other.

## Go, in-process

Import `github.com/patriceckhart/zot/packages/agent/sdk`. One `Runtime` per project; `Prompt(ctx, text, images)` returns a channel of `Event`. Example in `examples/sdk/`.

## Any language, out-of-process

Spawn `zot rpc` as a subprocess and exchange NDJSON over its stdin/stdout. Reference clients for Python, Node, shell, and Go live under `examples/rpc/`.

## Extension prompt hooks in RPC

RPC mode supports the `before_agent_start` extension hook. Subscribed extensions receive the complete assembled system prompt before the first model call and can replace it exactly. This uses the extension subprocess protocol, not a new RPC client command. Ordinary follow-up prompts reuse the result; an accepted `clear` or model change invalidates it for the next prompt. Failures keep the current prompt and surface as `ext_notify` warnings. See [Extensions](/docs/extensions) for lifecycle, privacy, and response limits.

## RPC state changes while busy

`clear`, `set_model`, and `set_reasoning` require an idle agent. During prompt preparation, including extension hooks, model/tool execution, or compaction, they return `success:false` with an `agent is busy` error and leave state unchanged. These commands are not queued.

Wait for the active operation to finish, or send `abort`, wait for completion, and retry. The RPC read loop remains responsive to `abort` while an extension hook or provider is busy.

## Packaged SDKs

For the two most common app targets, drop-in packages wrap the RPC handshake so you do not manage the child process by hand:

- [Node.js SDK](/docs/node-sdk) - a TypeScript client (`@patriceckhart/zot-sdk-javascript`) that runs `zot rpc` for you in any Node-compatible server runtime.
- [Swift bridge](/docs/swift-bridge) - zot's Go agent core compiled into an Apple `xcframework` for native, on-device chat in iOS and macOS apps.