Atoms Agent SDK

Connect to your Atoms voice agent with a few lines of code. The SDK handles microphone capture, audio playback, and WebSocket communication — you just listen for events.

Installation

npm install @smallest-ai/agent-sdk

Or use the CDN in a browser:

<script src="https://cdn.jsdelivr.net/npm/@smallest-ai/agent-sdk/dist/agent-sdk.browser.js"></script>

Quick Start

npm / Bundler

import { AtomsAgent } from "@smallest-ai/agent-sdk";

const agent = new AtomsAgent({
  apiKey: "sk_...",
  agentId: "your_agent_id",
});

agent.on("agent_start_talking", () => console.log("Agent speaking..."));
agent.on("agent_stop_talking", () => console.log("Agent stopped"));

await agent.connect();
// Microphone is automatically captured.
// Speak and the agent will respond through your speakers.

// When done:
agent.disconnect();

Browser (CDN)

<script src="https://cdn.jsdelivr.net/npm/@smallest-ai/agent-sdk/dist/agent-sdk.browser.js"></script>
<script>
  const agent = new AtomsSdk.AtomsAgent({
    apiKey: "sk_...",
    agentId: "your_agent_id",
  });

  agent.on("agent_start_talking", () => console.log("Agent speaking..."));
  agent.on("agent_stop_talking", () => console.log("Agent stopped"));

  agent.connect();
</script>

Configuration

const agent = new AtomsAgent({
  apiKey: "sk_...",       // Required — your API key
  agentId: "...",         // Required — agent to connect to
});

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | — | Your Atoms API key | | agentId | string | — | The agent ID to connect to |

Methods

connect()

Connect to the agent and start a session. If autoCaptureMic is true, the microphone starts immediately.

await agent.connect();

disconnect()

End the session and clean up all resources (microphone, audio playback, WebSocket).

agent.disconnect();

mute()

Stop sending microphone audio to the agent. The connection stays open.

agent.mute();

unmute()

Resume sending microphone audio.

agent.unmute();

isConnected

Returns true if connected to the agent.

if (agent.isConnected) { ... }

isMuted

Returns true if the microphone is muted.

if (agent.isMuted) { ... }

Events

Listen for events using agent.on(eventName, callback).

session_started

Fired when the session is created and ready.

agent.on("session_started", (event) => {
  console.log("Session ID:", event.session_id);
  console.log("Call ID:", event.call_id);
});

session_ended

Fired when the session ends. After this event, the agent is disconnected.

agent.on("session_ended", (event) => {
  console.log("Ended:", event.reason);
  // reason: "client_requested", "agent_disconnected", "websocket_closed", etc.
});

agent_start_talking

Fired when the agent begins speaking.

agent.on("agent_start_talking", () => {
  console.log("Agent is speaking...");
});

agent_stop_talking

Fired when the agent finishes speaking.

agent.on("agent_stop_talking", () => {
  console.log("Agent stopped speaking.");
});

error

Fired when an error occurs.

agent.on("error", (event) => {
  console.error(`Error [${event.code}]: ${event.message}`);
});

Examples

Voice Agent

The user speaks into the microphone, the agent responds with audio.

const agent = new AtomsAgent({
  apiKey: "sk_...",
  agentId: "...",
});

agent.on("session_started", () => console.log("Ready — speak now"));
agent.on("agent_start_talking", () => console.log("Agent speaking..."));
agent.on("agent_stop_talking", () => console.log("Agent stopped"));
agent.on("session_ended", (e) => console.log("Ended:", e.reason));
agent.on("error", (e) => console.error(e.message));

await agent.connect();

Mute / Unmute

await agent.connect();

agent.mute();   // Stop sending mic audio
agent.unmute(); // Resume

UI Integration

const agent = new AtomsAgent({
  apiKey: "sk_...",
  agentId: "...",
});

agent.on("session_started", () => showStatus("Connected"));
agent.on("agent_start_talking", () => showStatus("Agent speaking..."));
agent.on("agent_stop_talking", () => showStatus("Listening..."));
agent.on("error", (e) => showStatus(`Error: ${e.message}`));
agent.on("session_ended", () => showStatus("Disconnected"));

connectButton.onclick = () => agent.connect();
disconnectButton.onclick = () => agent.disconnect();
muteButton.onclick = () => {
  agent.isMuted ? agent.unmute() : agent.mute();
};

Audio Format

All audio is handled internally by the SDK. If you're building a custom integration without the SDK, the raw WebSocket protocol uses:

| Property | Value | |----------|-------| | Encoding | PCM 16-bit signed, little-endian | | Sample rate | 24,000 Hz | | Channels | 1 (mono) | | Transport | Base64-encoded inside JSON |

Error Handling

If the session fails to create (invalid API key, no credits, agent not found), the WebSocket closes with code 4000 and the error as the close reason:

agent.on("error", (e) => {
  if (e.code === "400") {
    // Credits exhausted, agent not found, etc.
  }
});

agent.on("session_ended", (e) => {
  // e.reason contains the close reason
});

Browser Support

The SDK uses standard Web APIs:

• WebSocket — for server communication
• getUserMedia — for microphone access
• AudioContext — for audio playback
• ScriptProcessorNode — for audio capture

Supported in all modern browsers (Chrome, Firefox, Safari, Edge).

Limits

| Limit | Value | |-------|-------| | Max session duration | 15 minutes | | Audio format | PCM 16-bit, 24kHz, mono |