The embed SDK lets you run Bourne AI guided-task and coaching experiences inside your own web application — with your own UI, your own branding, and full control over the integration. COMMENT-> SEEMS LIKE WE NEED ANOTHER ARTICLE(S) THAT ARE ACTUAL TECHNICAL DOCUMENTATION FOR THE API AND THE SDK. WHAT METHODS, WHAT COMPONENTS ETC.

API & SDK Overview

The @picoagent/embed-* packages are a set of TypeScript libraries that let you embed Bourne AI guided-task and coaching experiences directly into your own web applications, without sending users to the Bourne console. You bring the shell; the SDK wires up the session, voice channel, agent events, and optional video transport.

SDK vs Console — When to Use Each

ScenarioUse
You want to manage agents, build guided tasks, and run them for your teamBourne Console
You want to embed a guided-task or coaching experience inside your own productEmbed SDK
You want to customise the UI, branding, or interaction flow end-to-endEmbed SDK
You need headless data — plan state, glanceable events, credits — for a custom HUDEmbed 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

PackagePurpose
@picoagent/embed-coreSession bootstrap, transport-agnostic event bus, typed schema, protocol version gate
@picoagent/embed-voiceLiveKit room join, mic publish, agent audio playback, mute, speaking indicators
@picoagent/embed-videoCamera publish, device selection, FPS override, onFrame hook
@picoagent/embed-planPlan and step-index state machine
@picoagent/embed-glanceHeadless glanceable event stream
@picoagent/embed-knowledgeKnowledgeSource[] stream from the active session
@picoagent/embed-creditsCredits HUD values
@picoagent/embed-reactReact 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.

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 Bourne 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