API & SDK Overview
The embed SDK lets you run Atanzo AI guided-task and coaching experiences inside your own web application — with your own UI, your own branding, and full control over the integration.
The @atanzoai/embed-* packages are a set of TypeScript libraries that let you embed Atanzo AI guided-task and coaching experiences directly into your own web applications, without sending users to the Atanzo console. You bring the shell; the SDK wires up the session, voice channel, agent events, and optional video transport.
Console, or Build Your Own?
Before reaching for the SDK, decide which surface actually fits what you're building:
- Use the Atanzo Console if you want the fastest path to a working guided-task or coaching experience and don't need a custom UI. The console already gives you agent creation, plan authoring, session running, and reporting — no code required. Most internal teams and anyone evaluating Atanzo should start here.
- Use the Embed SDK if you're building a custom application, embedding Atanzo inside an existing product, shipping a partner-facing integration, or wiring the agent into a native app shell. The SDK is the right call whenever you need your own UI, your own branding, or programmatic control over session state — the console's UI is not a layer you can reuse or theme.
Both paths run the same agents, knowledge bases, and LLM reasoning underneath — the choice is purely about who owns the UI.
SDK vs Console — When to Use Each
| Scenario | Use |
|---|---|
| You want to manage agents, build guided tasks, and run them for your team | Atanzo Console |
| You want to embed a guided-task or coaching experience inside your own product | Embed SDK |
| You want to customise the UI, branding, or interaction flow end-to-end | Embed SDK |
| You need headless data — plan state, glanceable events, credits — for a custom HUD | Embed SDK |
Both approaches use the same underlying agents, knowledge bases, and LLM reasoning. The SDK does not provide a separate tier of capability — it surfaces the same session that the console would run, but gives you programmatic control over every layer.
Package Map
| Package | Version | Purpose |
|---|---|---|
@atanzoai/embed-core | 0.1.1 | Session bootstrap, transport-agnostic event bus, typed schema, protocol version gate |
@atanzoai/embed-voice | 0.1.0 | LiveKit room join, mic publish, agent audio playback, mute, speaking indicators |
@atanzoai/embed-video | 0.1.0 | Camera publish, device selection, FPS override, onFrame hook |
@atanzoai/embed-plan | 0.1.0 | Plan and step-index state machine |
@atanzoai/embed-glance | 0.1.0 | Headless glanceable event stream |
@atanzoai/embed-knowledge | 0.1.0 | KnowledgeSource[] stream from the active session |
@atanzoai/embed-credits | 0.1.0 | Credits HUD values |
@atanzoai/embed-react | 0.1.1 | React hooks: useSession, usePlan, useAgentStatus, useGlanceable, useCredits |
You do not need to install every package. A typical voice-only integration uses embed-core and embed-voice. Add embed-video if you need camera input. Add embed-react if you are building in React and want hooks instead of imperative event listeners.
The SDK is at
0.1.x. All packages are pre-1.0 — method names, event shapes, and hook signatures may still change between minor versions. Pin exact versions in production and check release notes before upgrading.
Voice must be attached before video
attachVideo() depends on the LiveKit room that attachVoice() creates. Call attachVoice(session) first; calling attachVideo(session) before it throws:
attachVoice must be called before attachVideo
If you only need camera input without publishing a microphone track, you still need to call attachVoice() first to establish the room — you can mute the mic immediately after.
Architecture Overview
Every session follows four steps:
Customer app / microsite
→ createSession(credential) ← bootstrap from your backend token endpoint
→ attachVoice(session) ← connect LiveKit room, wire data channel
→ session.on("plan", ...) ← receive agent events
→ session.send({ type: ... }) ← send commands back to agent
The key architectural principle is that your backend holds the secrets, not the browser. Your server calls the Atanzo token endpoint with your API credentials and an agentId, and receives back a short-lived SessionCredential (a LiveKit URL and token). That credential is what you pass to createSession() in the browser. No API keys, no agent configuration, and no access tokens ever touch client-side code.
This also means all session parameters — agent selection, interaction mode, language, credit caps — are baked in server-side when the credential is minted. The browser can only do what the credential allows.
Protocol Version Gate
The SDK enforces a protocolVersion check at startup. If the protocolVersion field in the credential is lower than the SDK's current minimum (currently 1), createSession() throws an error with an upgrade message. If you see this error, your backend token endpoint is returning a credential from an older API version — update your backend integration to request a current credential.
In This Section
- Getting a Session Credential — Backend token endpoint, all session parameters, and calling
createSession() - Voice and Video Transports —
attachVoice,attachVideo, mute, speaking indicators, camera options - Plan State, Glanceable, Knowledge, Credits — Consuming agent events and state streams
Where to Go Next
- API Authentication — OAuth2 grant types, tokens, and scoping for calling the Atanzo API directly
- Coaching Presets — Running the branded coaching experiences (golf, present, rehab, and others) through the SDK
- Metrics and Reports — Consuming live metrics snapshots and end-of-session reports