Smallest AI

https://docs.smallest.ai/llms.txt
Admin
Smallest AI is a platform for building, deploying, and managing AI voice agents with advanced...
Tokens:578,067
Snippets:5,463
Trust Score:8.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://docs.smallest.ai/models/integrations/telephony/plivo

Install the required dependencies for the example code. Run this command in your project directory.

```bash
pip install -r requirements.txt
```

--------------------------------

### Install and start vLLM server

Source: https://docs.smallest.ai/voice-agents/developer-guide/build/agent-crews/llm/byom

Install vLLM and start an OpenAI-compatible inference server on port 8000 with the specified model. This setup is required before using the vLLM usage snippet.

```bash
pip install vllm

python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Llama-3-8B-Instruct \
    --port 8000
```

--------------------------------

### Install and start Ollama server

Source: https://docs.smallest.ai/voice-agents/developer-guide/build/agent-crews/llm/byom

Install Ollama, pull a model, and start the local server on port 11434. This setup is required before using the Ollama usage snippet.

```bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Pull a model
ollama pull llama3

# Start the server (runs on port 11434)
ollama serve
```

--------------------------------

### Download and set up the getting_started example

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/quickstart

Downloads the getting_started example folder from the cookbook, extracts it into the current directory, and installs its dependencies. Use this for local development of a single-node crew; no .env is needed because the code reads SMALLEST_API_KEY from the shell.

```bash
curl -sL https://github.com/smallest-inc/cookbook/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=2 cookbook-main/voice-agents/getting_started
cd getting_started
pip install -r requirements.txt
```

--------------------------------

### Complete Setup Example with CrewSession and AtomsCrewApp

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/agent-crew-core-concepts/sessions

Full example showing graph building, event hooks, and lifecycle management. It initializes nodes, builds a graph, registers an interrupt hook, and runs the app.

```python
from smallestai.atoms.crew.session import CrewSession
from smallestai.atoms.crew.server import AtomsCrewApp

async def setup(session: CrewSession):
    # 1. Initialize Nodes
    agent = SalesAgent()
    tracker = StatsTracker()
    
    # 2. Build Graph
    session.add_node(tracker)
    session.add_node(agent)
    session.add_edge(tracker, agent)  # Events go Tracker -> Agent
    
    # 3. Register Hooks
    @session.on_event("system.control.interrupt")
    async def on_interrupt(session, event):
        print("User interrupted the agent!")

    # 4. Launch
    await session.start()
    await session.wait_until_complete()

if __name__ == "__main__":
    app = AtomsCrewApp(setup_handler=setup)
    app.run()
```

--------------------------------

### Download and set up the background_agent example

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/quickstart

Downloads the background_agent example folder from the cookbook, extracts it, and installs its dependencies. Use this for a multi-node crew with background processing; the folder contains app.py, support_agent.py, and sentiment_analyzer.py.

```bash
curl -sL https://github.com/smallest-inc/cookbook/archive/refs/heads/main.tar.gz \
  | tar -xz --strip-components=2 cookbook-main/voice-agents/background_agent
cd background_agent
pip install -r requirements.txt
```

--------------------------------

### Run a voice agent example locally

Source: https://docs.smallest.ai/voice-agents/developer-guide/examples/examples

Commands to clone the cookbook, install dependencies, set environment variables, run the example, and test with the CLI. Requires an OpenAI API key.

```bash
# Clone the cookbook
git clone https://github.com/smallest-inc/cookbook
cd cookbook/voice-agents/<example>

# Install dependencies
pip install -e .

# Set environment variables
export OPENAI_API_KEY="your-key"

# Run locally
python app.py

# Test with CLI (in another terminal)
smallestai agent-crew chat
```

--------------------------------

### Install smallest-self-host Helm chart and monitor pods

Source: https://docs.smallest.ai/models/self-host/kubernetes-setup/quick-start

Installs the smallest-self-host Helm chart into the 'smallest' namespace using a custom values.yaml, then monitors pod startup with kubectl get pods -w. The table lists expected startup times: Redis ~30s, License Proxy ~1m, Lightning ASR 2-10m (first run downloads model), API Server ~30s. Model downloads are cached when using shared storage (EFS), so subsequent starts complete in under a minute.

```bash
helm install smallest-self-host smallest-self-host/smallest-self-host \
  -f values.yaml \
  --namespace smallest
```

```bash
kubectl get pods -w
```

--------------------------------

### Minimal agent setup

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/agent-crew-core-concepts/graphs

A minimal agent only needs to add a node and start the session. The framework automatically connects it to Root and Sink.

```python
async def setup(session: CrewSession):
    session.add_node(SalesAgent())
    await session.start()
    await session.wait_until_complete()
```

--------------------------------

### Install dependencies with pip

Source: https://docs.smallest.ai/models/documentation/speech-to-text-pulse/pre-recorded/code-examples

Install the required Python packages for the speech-to-text examples. pydub requires ffmpeg on PATH for non-WAV input formats.

```bash
pip install requests pydub
```

--------------------------------

### Quickstart: AtomsAgent with event listeners and connect()

Source: https://docs.smallest.ai/voice-agents/platform/agent-sdk/web-socket-sdk

Create an AtomsAgent with your API key and agent ID, attach event listeners, and connect. Microphone capture starts automatically; call agent.disconnect() when done. Do not put a raw API key in a browser; use a short-lived access token from POST /conversation/register-call instead.

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

const agent = new AtomsAgent({
  apiKey:  "sk_...",   // Smallest API key
  agentId: "...",      // Agent ID
});

agent.on("session_started", (e) => {
  console.log("Session started:", e.session_id, e.call_id);
});
agent.on("agent_start_talking", () => console.log("Agent speaking"));
agent.on("agent_stop_talking",  () => console.log("Agent stopped"));
agent.on("error",               (e) => console.error(`[${e.code}] ${e.message}`));

await agent.connect();
// Microphone capture starts automatically. Speak, and the agent replies
// through the default audio output. Call agent.disconnect() when done.
```

--------------------------------

### Install Pipecat with all required extras

Source: https://docs.smallest.ai/voice-agents/integrations/agent-framework/pipecat

Installs Pipecat with all extras needed to run the full voice agent example: daily (Daily transport), openai (OpenAI LLM), silero (Silero VAD), and runner (Pipecat development runner).

```bash
pip install "pipecat-ai[smallest,daily,openai,silero,runner]"
```

--------------------------------

### Build and run the agent

Source: https://docs.smallest.ai/models/integrations/agent-framework/ten-framework

Builds and runs the TEN Framework agent using Docker Compose, then installs and runs the voice assistant example inside the container.

```bash
docker compose up -d
docker exec ten_agent_dev bash -c "cd /app/agents/examples/voice-assistant && task install"
docker exec -d ten_agent_dev bash -c "cd /app/agents/examples/voice-assistant && task run"
```

--------------------------------

### Run and test commands for working sample

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/overview

These shell commands set the required environment variables, install dependencies, start the WebSocket server, and then run the agent-crew chat client in a second terminal. The server listens on `ws://localhost:8080/ws`. The `SMALLEST_API_KEY` and `OPENAI_API_KEY` (or your runtime's key) must be set before running.

```bash
export SMALLEST_API_KEY=sk_...
export OPENAI_API_KEY=sk-...              # or your runtime's key
pip install -r requirements.txt
python server.py                          # ws://localhost:8080/ws
# second terminal:
smallestai agent-crew chat
```

--------------------------------

### Single-File App.tsx Quickstart

Source: https://docs.smallest.ai/voice-agents/platform/agent-sdk/mobile-integrations/react-native

Complete App.tsx example for Expo dev builds (not Expo Go) that handles permission, WebSocket connection, microphone capture, and scheduled PCM playback. Uses react-native-audio-api and react-native-permissions.

```typescript
import { useEffect, useRef, useState } from 'react';
import { View, Text, Button, StyleSheet, Platform } from 'react-native';
import {
  AudioContext,
  AudioManager,
  AudioRecorder,
} from 'react-native-audio-api';
import { PERMISSIONS, request, RESULTS } from 'react-native-permissions';
import { Buffer } from 'buffer';

const API_KEY      = 'sk_...';
const AGENT_ID     = '...';
const SAMPLE_RATE  = 24000;
const CHUNK_FRAMES = 480;  // 20 ms at 24 kHz: small enough for low latency

async function ensureMicPermission(): Promise<boolean> {
  const perm = Platform.OS === 'ios'
    ? PERMISSIONS.IOS.MICROPHONE
    : PERMISSIONS.ANDROID.RECORD_AUDIO;
  return (await request(perm)) === RESULTS.GRANTED;
}

function float32ToInt16LE(float32: Float32Array): Uint8Array {
  const out = new Uint8Array(float32.length * 2);
  const view = new DataView(out.buffer);
  for (let i = 0; i < float32.length; i++) {
    const s = Math.max(-1, Math.min(1, float32[i]));
    view.setInt16(i * 2, s < 0 ? s * 0x8000 : s * 0x7fff, true);
  }
  return out;
}

export default function App() {
  const wsRef       = useRef<WebSocket | null>(null);
  const recorderRef = useRef<AudioRecorder | null>(null);
  const audioCtxRef = useRef<AudioContext | null>(null);
  const nextPlayRef = useRef<number>(0);
  const [status, setStatus] = useState<'idle' | 'connecting' | 'connected' | 'error'>('idle');

  async function start() {
    if (!(await ensureMicPermission())) { setStatus('error'); return; }

    AudioManager.setAudioSessionOptions({
      iosCategory: 'playAndRecord',
      iosMode:     'voiceChat',
      iosOptions:  ['allowBluetoothHFP', 'defaultToSpeaker'],
    });
    await AudioManager.setAudioSessionActivity(true);

    const url =
      'wss://api.smallest.ai/atoms/v1/agent/connect' +
      `?token=${encodeURIComponent(API_KEY)}` +
      `&agent_id=${encodeURIComponent(AGENT_ID)}` +
      `&mode=webcall&sample_rate=${SAMPLE_RATE}`;

    setStatus('connecting');
    const ws = new WebSocket(url);
    wsRef.current = ws;

    ws.onopen    = () => startMic(ws);
    ws.onmessage = (e) => handleServerEvent(e.data as string);
    ws.onerror   = () => setStatus('error');
    ws.onclose   = () => {
      recorderRef.current?.stop();
      recorderRef.current = null;
      setStatus('idle');
    };

    const ctx = new AudioContext({ sampleRate: SAMPLE_RATE });
    audioCtxRef.current = ctx;
    nextPlayRef.current = ctx.currentTime;
  }

  function stop() { wsRef.current?.close(1000, 'client end'); }
  useEffect(() => () => { wsRef.current?.close(); }, []);

  // ---- mic capture ------------------------------------------------
  function startMic(ws: WebSocket) {
    const recorder = new AudioRecorder();
    recorderRef.current = recorder;

    recorder.onAudioReady(
      { sampleRate: SAMPLE_RATE, bufferLength: CHUNK_FRAMES, channelCount: 1 },
      ({ buffer }) => {
        if (ws.readyState !== WebSocket.OPEN) return;
        const float32 = buffer.getChannelData(0);
        const int16   = float32ToInt16LE(float32);
        ws.send(JSON.stringify({
          type:  'input_audio_buffer.append',
          audio: Buffer.from(int16).toString('base64'),
        }));
      },
    );
    recorder.onError((err) => console.error('mic error:', err.message));
    recorder.start();
  }
```

--------------------------------

### Proper session setup with wait_until_complete

Source: https://docs.smallest.ai/voice-agents/developer-guide/operate/testing-debugging/common-issues

Use this setup pattern to prevent sessions from ending early. It ensures the session is started and then waits until all processing is complete before returning. Missing the wait_until_complete call is a common cause of premature session termination.

```python
async def setup(session: CrewSession):
    agent = MyAgent()
    session.add_node(agent)
    
    await session.start()
    await session.wait_until_complete()  # Do not forget this
```

--------------------------------

### Install smallestai-vercel-provider and ai

Source: https://docs.smallest.ai/models/integrations/sdks-libraries/vercel-ai-sdk

Install the provider and the AI SDK. Requires ai@^7.

```bash
npm install smallestai-vercel-provider ai
```

--------------------------------

### sse_init event example

Source: https://docs.smallest.ai/voice-agents/developer-guide/operate/analytics/sse-for-live-transcripts

Example of the sse_init event, sent immediately when the SSE connection is established.

```json
{
  "event_type": "sse_init",
  "event_time": "2026-03-02T10:00:00.000Z"
}
```

--------------------------------

### Clone and run the Hydra reference client

Source: https://docs.smallest.ai/models/documentation/speech-to-speech-hydra/quickstart

Clones the hydra_agents repository, installs dependencies, and starts the development server. After running, open http://localhost:3000, paste your API key, select an agent preset, and click Connect.

```bash
git clone https://github.com/smallest-inc/hydra_agents.git
cd hydra_agents && npm install && npm run dev
```

--------------------------------

### Install NVIDIA Container Toolkit

Source: https://docs.smallest.ai/models/self-host/docker-setup/stt-deployment/prerequisites/software-requirements

Installs the NVIDIA Container Toolkit on Ubuntu. Adds the NVIDIA repository, installs the toolkit, and restarts Docker to enable GPU access.

```bash
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | \
  sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

sudo systemctl restart docker
```

--------------------------------

### connect()

Source: https://docs.smallest.ai/voice-agents/platform/agent-sdk/web-socket-sdk

Opens the WebSocket and starts the session. If `autoCaptureMic` is `true`, microphone capture starts on connect.

```APIDOC
## connect()

### Description
Opens the WebSocket and starts the session. If `autoCaptureMic` is `true`, microphone capture starts on connect.

### Method
connect

### Returns
`Promise<void>`

### Parameters
None

### Example
```javascript
await agent.connect();
```

```

--------------------------------

### Install websocket-client

Source: https://docs.smallest.ai/models/model-cards/text-to-speech/tts-evaluation-script

Install the required websocket-client package before running the evaluation script.

```bash
pip install websocket-client
```

--------------------------------

### Install Node.js on Mac (Homebrew)

Source: https://docs.smallest.ai/voice-agents/mcp/getting-started/quick-start

Install Homebrew, configure the shell for Apple Silicon Macs, install Node.js via Homebrew, and verify the installation. The Homebrew installer prompts for your Mac password; the shellenv commands are required on M1/M2/M3/M4 Macs. After installing, `node --version` should print a version like v22.x.x.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

```bash
echo >> ~/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"
```

```bash
brew install node
```

```bash
node --version
```

--------------------------------

### Install Docker on Ubuntu

Source: https://docs.smallest.ai/models/self-host/docker-setup/stt-deployment/prerequisites/software-requirements

Installs Docker Engine and Docker Compose on Ubuntu. Adds the Docker repository, installs the required packages, and adds the current user to the docker group.

```bash
sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg

sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo \
  "deb=[arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo usermod -aG docker $USER
newgrp docker
```

--------------------------------

### Install Node.js ws library

Source: https://docs.smallest.ai/models/documentation/speech-to-text-pulse/realtime-web-socket/code-examples

Install the required Node.js library for WebSocket communication.

```bash
npm install ws
```

--------------------------------

### Run setup-irsa.sh

Source: https://docs.smallest.ai/models/self-host/kubernetes-setup/aws/iam-irsa

Make the setup script executable and run it.

```bash
chmod +x setup-irsa.sh
./setup-irsa.sh
```

--------------------------------

### Install and use Python SDK

Source: https://docs.smallest.ai/models/self-host/api-reference/authentication

Installs the Python SDK and initializes the client with the API URL and license key. The client.transcribe_url method transcribes an audio file from a URL and prints the result text.

```bash
pip install smallest-client
```

```python
from smallest import Client

client = Client(
    api_url="http://localhost:7100",
    license_key="your-license-key-here"
)

result = client.transcribe_url("https://example.com/audio.wav")
print(result.text)
```

--------------------------------

### Install Pipecat with Smallest AI and required extras

Source: https://docs.smallest.ai/models/integrations/agent-framework/pipecat

Install Pipecat with Smallest AI support. The 'smallest' extra installs both TTS and STT services. For the full voice agent example, also install 'daily', 'openai', 'silero', and 'runner' extras.

```bash
pip install "pipecat-ai[smallest]"
```

```bash
pip install "pipecat-ai[smallest,daily,openai,silero,runner]"
```

--------------------------------

### Install Docker on CentOS/RHEL

Source: https://docs.smallest.ai/models/self-host/docker-setup/stt-deployment/prerequisites/software-requirements

Installs Docker Engine and Docker Compose on CentOS/RHEL. Adds the Docker repository, installs the required packages, starts and enables the Docker service, and adds the current user to the docker group.

```bash
sudo yum install -y yum-utils
sudo yum-config-manager --add-repo \
  https://download.docker.com/linux/centos/docker-ce.repo

sudo yum install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin

sudo systemctl start docker
sudo systemctl enable docker

sudo usermod -aG docker $USER
newgrp docker
```

--------------------------------

### Install Node.js on Linux (NodeSource)

Source: https://docs.smallest.ai/voice-agents/mcp/getting-started/quick-start

Install Node.js 22 on Linux using the NodeSource setup script and apt. Requires Node.js 18+; verify with `node --version`.

```bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
```

--------------------------------

### Install and use JavaScript SDK

Source: https://docs.smallest.ai/models/self-host/api-reference/authentication

Installs the JavaScript SDK and initializes the client with the API URL and license key. The transcribeUrl method transcribes an audio file from a URL and logs the result text.

```bash
npm install @smallest/client
```

```javascript
import { SmallestClient } from '@smallest/client';

const client = new SmallestClient({
  apiUrl: 'http://localhost:7100',
  licenseKey: 'your-license-key-here'
});

const result = await client.transcribeUrl('https://example.com/audio.wav');
console.log(result.text);
```

--------------------------------

### Instructions / Rules Example

Source: https://docs.smallest.ai/voice-agents/developer-guide/build/agent-crews/llm/prompts

Use this to define the agent's general behavior. Instructions should be actionable, specific, and prioritized, and are best written as bullet points.

```text
## Instructions

- Always verify the customer's identity before discussing account details
- If the customer is frustrated, acknowledge briefly and focus on solving
- Never quote exact prices—direct to the pricing page
```

--------------------------------

### Successful Startup Log

Source: https://docs.smallest.ai/models/self-host/troubleshooting/logs-analysis

Sample log showing a successful API server startup, including connection to Lightning ASR and license validation.

```log
INFO: Starting API Server v1.0.0
INFO: Connecting to Lightning ASR at http://lightning-asr:2269
INFO: Connected to Lightning ASR (2 replicas)
INFO: Connecting to License Proxy at http://license-proxy:3369
INFO: License validated
INFO: API server listening on port 7100
```

--------------------------------

### Complete .env File Example

Source: https://docs.smallest.ai/models/self-host/docker-setup/tts-deployment/configuration

Complete .env file example for configuring the TTS deployment. It includes the license key, API server and TTS ports, Redis connection settings, GPU device ID, and default voice parameters.

```bash
LICENSE_KEY=your-license-key-here

API_SERVER_PORT=7100
TTS_PORT=8876

REDIS_HOST=redis
REDIS_PORT=6379

GPU_DEVICE_ID=0

DEFAULT_VOICE=default
VOICE_SPEED=1.0

```

--------------------------------

### Create a Knowledge Base with KB.create()

Source: https://docs.smallest.ai/voice-agents/developer-guide/build/knowledge-base/usage

Initializes the KB manager and SmallestAI client, then creates a knowledge base with a name and optional description. The response contains the KB ID in the 'data' field, which is used for all subsequent operations.

```python
from smallestai.atoms.helpers import KB
from smallestai import SmallestAI

# Initialize separate managers
kb = KB()
client = SmallestAI()

# Create KB
response = kb.create(
    name="Product Documentation",
    description="Technical specs and troubleshooting guides"
)

kb_id = response["data"]
```

--------------------------------

### Enforce type safety with Pydantic (bad vs good)

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/agent-crew-core-concepts/events

Compares bad and good practices for type safety. The bad example accesses dict keys blindly, while the good example uses isinstance with the Pydantic model to get autocompletion and safety.

```python
# Bad: Accessing dict keys blindly
if event.get("type") == "message":
    print(event["content"])
    
# Good: Using the model
if isinstance(event, SDKSystemLLMRequestEvent):
    print(event.content)  # IDE autocompletes this!
```

--------------------------------

### HPA event showing failed metric retrieval

Source: https://docs.smallest.ai/models/self-host/kubernetes-setup/autoscaling/hpa-configuration

Example event output showing a failure to get the metric, which explains why the HPA is not scaling.

```text
Events:
  Warning  FailedGetPodsMetric  1m  horizontal-pod-autoscaler  unable to get metric asr_active_requests
```

--------------------------------

### requirements.txt for working sample

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/overview

This is the `requirements.txt` file for the working sample. It specifies the minimum version of the `smallestai` package required to run the example.

```text
smallestai>=5.3.0
```

--------------------------------

### Conversation Flow Example

Source: https://docs.smallest.ai/voice-agents/developer-guide/build/agent-crews/llm/prompts

Use this to describe the conversation flow as a flexible guide, not a rigid script. It outlines opening, issue identification, troubleshooting, and closing steps.

```text
## Conversation Flow

1. **Opening**: Greet and ask how you can help.

2. **Identify the issue**: Listen. If billing → billing flow. If technical → troubleshooting.

3. **Troubleshooting**:
   - Ask clarifying questions
   - If solvable with basic steps, guide them through
   - If issue persists, offer to schedule repair
   
4. **Closing**: Summarize, confirm next steps, thank them.
```

--------------------------------

### Run the FastAPI Application

Source: https://docs.smallest.ai/models/integrations/telephony/plivo

Start the FastAPI server that handles streaming of audio. Make sure to update the ngrok URL and paths in the script before running.

```bash
python plivo_example/plivo_app.py
```

--------------------------------

### AtomsAgent class skeleton for iOS voice agent

Source: https://docs.smallest.ai/voice-agents/platform/agent-sdk/mobile-integrations/i-os-swift

Defines the AtomsAgent class that manages the full session: audio session configuration, WebSocket connection, playback setup, and microphone tap. The start() method orchestrates the setup steps, and stop() tears down the audio engine and cancels the WebSocket.

```swift
import AVFoundation
import Foundation

final class AtomsAgent: NSObject {
    private let apiKey:  String
    private let agentId: String
    private let sampleRate: Double = 24_000
    private var webSocketTask: URLSessionWebSocketTask?
    private let audioEngine = AVAudioEngine()
    private var playerNode: AVAudioPlayerNode?
    private var playerFormat: AVAudioFormat?

    init(apiKey: String, agentId: String) {
        self.apiKey  = apiKey
        self.agentId = agentId
    }

    func start() async throws {
        try configureAudioSession()
        connectWebSocket()
        try setupPlayback()
        try startMicrophoneTap()
    }

    func stop() {
        audioEngine.stop()
        webSocketTask?.cancel(with: .goingAway, reason: nil)
    }
}
```

--------------------------------

### Working sample: assistant.py and server.py

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/overview

These two Python files form the working sample: `assistant.py` defines an `OutputCrewNode` that streams responses from an OpenAI-compatible client, and `server.py` sets up a WebSocket app that greets users on join. The `assistant.py` node uses `OpenAIClient` with `model="gpt-4o-mini"` and reads the API key from `OPENAI_API_KEY`; the `base_url` line is commented out but can be enabled to bring your own LLM runtime. The `server.py` app registers an event handler that speaks a greeting when a `SDKSystemUserJoinedEvent` is received.

```python
import os
from smallestai.atoms.crew.nodes import OutputCrewNode
from smallestai.atoms.crew.clients.openai import OpenAIClient


class Assistant(OutputCrewNode):
    def __init__(self):
        super().__init__(name="assistant")
        self.llm = OpenAIClient(
            model="gpt-4o-mini",
            api_key=os.getenv("OPENAI_API_KEY"),
            # base_url="https://your-runtime.example.com/v1",  # bring your own LLM
        )
        self.context.messages.append(
            {"role": "system", "content": "You are a friendly, concise voice assistant."}
        )

    async def generate_response(self):
        response = await self.llm.chat(messages=self.context.messages, stream=True)
        full = ""
        async for chunk in response:
            if chunk.content:
                full += chunk.content
                yield chunk.content
        self.context.messages.append({"role": "assistant", "content": full})
```

```python
from smallestai.atoms.crew import AtomsCrewApp
from smallestai.atoms.crew.events import SDKSystemUserJoinedEvent
from assistant import Assistant


async def setup_session(session):
    agent = Assistant()
    session.add_node(agent)
    await session.start()

    @session.on_event("on_event_received")
    async def on_event(event):
        if isinstance(event, SDKSystemUserJoinedEvent):
            await agent.speak("Hi! How can I help you today?")

    await session.wait_until_complete()


AtomsCrewApp(setup_handler=setup_session).run()
```

--------------------------------

### LiveKit Agents: install smallestai plugin and create AgentSession

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/build-with-a-coding-agent

Install the official LiveKit plugin for Smallest AI, then create an AgentSession with Smallest STT and TTS services. The TTS model is set to lightning_v3.1; the LLM argument is left as a placeholder. This pair is the full STT+TTS setup for LiveKit Agents.

```bash
pip install "livekit-agents[smallestai]"
```

```python
from livekit.plugins import smallestai
session = AgentSession(stt=smallestai.STT(), tts=smallestai.TTS(model="lightning_v3.1"), llm=...)
```

--------------------------------

### Lightning TTS startup logs

Source: https://docs.smallest.ai/models/self-host/docker-setup/tts-deployment/services-overview

Example log output from Lightning TTS startup, showing successful GPU detection, model loading, warmup, and server readiness.

```text
✓ GPU detected: NVIDIA A10 (24GB)
✓ Model loaded successfully
✓ Warmup completed in 3.2s
✓ Server ready on port 8876
```

--------------------------------

### Verify webhook signature with HMAC-SHA256 (Python Flask and Node Express)

Source: https://docs.smallest.ai/voice-agents/platform/create-agent/developer/webhooks

Verify the X-Signature header on incoming webhook requests using HMAC-SHA256. The Python example uses Flask and hmac.compare_digest; the Node example uses Express and crypto.timingSafeEqual. Both require the raw request body bytes and the signing secret from the dashboard or GET /webhook.

```python
import hmac, hashlib
from flask import Flask, request, abort

SIGNING_SECRET = "..."  # from the dashboard or GET /webhook

app = Flask(__name__)

@app.post("/webhook")
def receive():
    provided = request.headers.get("X-Signature", "")
    expected = hmac.new(
        SIGNING_SECRET.encode(),
        request.get_data(),  # raw bytes, not request.json
        hashlib.sha256,
    ).hexdigest()
    if not hmac.compare_digest(provided, expected):
        abort(401)
    # trust request.now
    ...
    return "", 200
```

```javascript
import crypto from "node:crypto";
import express from "express";

const app = express();
const SIGNING_SECRET = process.env.WEBHOOK_SECRET;

// Capture raw body so the HMAC matches byte-for-byte.
app.use(express.json({ verify: (req, _res, buf) => { req.rawBody = buf; } }));

app.post("/webhook", (req, res) => {
  const provided = req.header("X-Signature") ?? "";
  const expected = crypto
    .createHmac("sha256", SIGNING_SECRET)
    .update(req.rawBody)
    .digest("hex");

  const a = Buffer.from(provided, "hex");
  const b = Buffer.from(expected, "hex");
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.status(401).end();
  }
  // trust req.body now
  res.status(200).end();
});
```

--------------------------------

### Install @smallest-ai/agent-sdk (npm, pnpm, yarn, CDN)

Source: https://docs.smallest.ai/voice-agents/platform/agent-sdk/browser-voice-cookbook

Install the Agent Web SDK with npm, pnpm, or yarn, or load it from the CDN. When loaded via CDN, the SDK is exposed on window.AtomsSdk.

```bash
npm install @smallest-ai/agent-sdk
```

```bash
pnpm add @smallest-ai/agent-sdk
```

```bash
yarn add @smallest-ai/agent-sdk
```

```html
<script src="https://cdn.jsdelivr.net/npm/@smallest-ai/agent-sdk/dist/agent-sdk.browser.js"></script>
<!-- Loaded via CDN, the SDK is exposed on window.AtomsSdk -->
```

--------------------------------

### Response conversation_id example

Source: https://docs.smallest.ai/voice-agents/developer-guide/build/calling/outbound-calls

Shows the expected value of the conversation_id field in the response object after starting an outbound call. Use this ID to track the call and retrieve transcripts and analytics later.

```python
# response.data.conversation_id = "CALL-1767900635803-8a3bee"
```

--------------------------------

### Start agent server with python agent.py

Source: https://docs.smallest.ai/voice-agents/developer-guide/operate/testing-debugging/common-issues

Run the agent server. Ensure this command is executed before attempting to connect.

```bash
python agent.py
```

--------------------------------

### Router pattern with RouterNode and CrewSession setup

Source: https://docs.smallest.ai/voice-agents/developer-guide/build/agent-crews/patterns/multi-agent-orchestration

Defines a router node that classifies user intent by keywords and routes events to sales, support, or billing agents. The setup function creates the agents, adds them to a CrewSession, connects the router to each specialist with edges, and starts the graph. Use together to implement the router pattern for multi-agent orchestration.

```python
from smallestai.atoms.crew.nodes import CrewNode, OutputCrewNode


class RouterNode(CrewNode):
    """Routes conversations to the appropriate specialist."""
    
    def __init__(self, sales_agent, support_agent, billing_agent):
        super().__init__(name="router")
        self.sales = sales_agent
        self.support = support_agent
        self.billing = billing_agent

    async def process_event(self, event):
        # Simple keyword-based routing
        if hasattr(event, "content"):
            content = event.content.lower()
            
            if any(word in content for word in ["buy", "price", "demo"]):
                event.metadata["route"] = "sales"
            elif any(word in content for word in ["broken", "help", "issue"]):
                event.metadata["route"] = "support"
            elif any(word in content for word in ["invoice", "payment", "bill"]):
                event.metadata["route"] = "billing"
            else:
                event.metadata["route"] = "support"  # Default
        
        await self.send_event(event)


class SalesAgent(OutputCrewNode):
    """Handles sales inquiries."""
    
    def __init__(self):
        super().__init__(name="sales-agent")
    
    async def process_event(self, event):
        if event.metadata.get("route") == "sales":
            await super().process_event(event)
        else:
            await self.send_event(event)


class SupportAgent(OutputCrewNode):
    """Handles support requests."""
    
    def __init__(self):
        super().__init__(name="support-agent")
    
    async def process_event(self, event):
        if event.metadata.get("route") == "support":
            await super().process_event(event)
        else:
            await self.send_event(event)

```

```python
async def setup(session: CrewSession):
    # Create agents
    sales = SalesAgent()
    support = SupportAgent()
    billing = BillingAgent()
    router = RouterNode(sales, support, billing)
    
    # Add to session
    session.add_node(router)
    session.add_node(sales)
    session.add_node(support)
    session.add_node(billing)
    
    # Connect the graph
    session.add_edge(router, sales)
    session.add_edge(router, support)
    session.add_edge(router, billing)
    
    await session.start()
    await session.wait_until_complete()
```

--------------------------------

### Authenticate requests with API key (cURL, Python, Node.js)

Source: https://docs.smallest.ai/voice-agents/platform/account/api-keys

Use the API key in the Authorization header for every request. The cURL example shows a GET request to the agents endpoint. The Python and Node.js examples demonstrate using the official SDKs, which read the SMALLEST_API_KEY environment variable automatically, with an option to pass the key explicitly.

```bash
curl -X GET "https://api.smallest.ai/atoms/v1/agent" \
  -H "Authorization: Bearer $SMALLEST_API_KEY"
```

```python
import os
from smallestai import SmallestAI

# Reads SMALLEST_API_KEY from environment automatically
client = SmallestAI()

# Or pass explicitly if you manage secrets differently
client = SmallestAI(api_key=os.environ["SMALLEST_API_KEY"])

agents = client.atoms.agents.list_agents()
```

```javascript
import { AtomsClient } from "@smallest/atoms";

// Reads SMALLEST_API_KEY from environment automatically
const client = new AtomsClient();

const agents = await client.agent.list();
```

--------------------------------

### Build a voice agent on Smallest AI (agent prompt)

Source: https://docs.smallest.ai/voice-agents/developer-guide/get-started/build-with-a-coding-agent

A complete agent prompt for building a voice agent on Smallest AI. It instructs the coding agent to run discovery, write the system prompt, create and configure the agent, set up telephony if needed, go live, place a test call, and offer to add features. Includes setup paths (MCP vs SDK), discovery questions, system prompt rules, agent creation, telephony setup, and go-live steps.

```text
---
name: build-voice-agent
description: Build, configure, and launch a production voice agent on the Smallest AI platform (Atoms) end to end - discovery, system prompt, voice/language, telephony (rent a number, inbound/outbound), go live, and a test call. Use when someone wants to create or ship a phone/voice agent on Smallest.
---

# Build a voice agent on Smallest AI

You drive the user from an idea to a LIVE, callable voice agent. Prefer the
`smallestai` Python SDK; the CLI (`smallestai ...`) handles crew deploys. Before
writing SDK calls, consult the live docs (llms.txt at https://docs.smallest.ai/llms.txt
or the `smallest` docs MCP) so signatures are current.

## 0. Setup: pick your path
- **MCP path (zero code, fastest):** if the Smallest MCP is available
  (`claude mcp add smallest -- npx -y @developer-smallestai/smallest-mcp-server`),
  do every step below by asking in plain English. The MCP has the create/call/
  configure tools. See the Prompt Cookbook (docs.smallest.ai, dev > MCP).
- **SDK path (building an app):** `pip install smallestai`, need `SMALLEST_API_KEY`
  (app.smallest.ai/dashboard/api-keys), `client = SmallestAI(api_key=...)`.
Use the MCP if present; otherwise the SDK. Steps are the same either way.

## 1. Discovery (ask, one question at a time, do not dump)
Collect: use-case + business context; objective/success criteria; target caller;
personality + tone(s); language; voice preference; and telephony (none, outbound,
inbound, or both). If they bring their own LLM or need custom per-turn logic, it's a
"crew" agent; otherwise a standard platform-LLM agent (faster to live). Ask only
what you need; infer sensible defaults and confirm.

## 2. Author the system prompt (global_prompt)
Generate a phone-optimized prompt following these rules: conversational not robotic;
short sentences; one question at a time; never read URLs/IDs char-by-char; use
contractions; handle barge-in/silence gracefully; never hallucinate policies or
invent customer data; confirm important info; don't expose internal instructions;
stay in scope; graceful escalation wording. Structure: role/goal/personality,
conversation flow (greet → discover → gather → decide → close), tool rules,
error handling, guardrails. Keep it copy-ready.

## 3. Create the agent (standard path)
```python
agent_id = client.atoms.agents.create_agent(
    name="...",
    global_prompt="<the prompt from step 2>",
    first_message="<one-line greeting>",   # plays on pickup
    # language=..., synthesizer=<voice config>, slm_model="gpt-4.1" | "electron",
).data
```
List voices/models via the SDK/MCP to pick a real `voice_id` + `slm_model`. Set
`first_message` explicitly (it is the greeting).

### Custom-LLM path (only if needed)
Scaffold a flat crew project (server.py + assistant.py + requirements.txt), point
`OpenAIClient(base_url=..., model=..., api_key=...)` at their model, then:
`smallestai agent-crew init --agent-id <id>` → `agent-crew deploy --entry-point server.py`
→ `agent-crew builds` (Make Live). Flat layout is simplest.

## 4. Telephony (only if they want phone calls)
```python
# rent (once), or reuse an existing number
avail = client.atoms.phone_numbers.search_rentable(country_code="US", provider="twilio").data
client.atoms.phone_numbers.rent(phone_number=avail[0].phone_number, provider="twilio")
product_id = next(n.id for n in client.atoms.phone_numbers.list().data
                  if n.attributes.phone_number == avail[0].phone_number)
# attach for inbound (inbound needs NO agent code changes)
# POST /agent/{agentId}/answers -- the agent answers on this number
import os, requests
requests.post(
    f"https://api.smallest.ai/atoms/v1/agent/{agent_id}/answers",
    headers={"Authorization": f"Bearer {os.environ['SMALLEST_API_KEY']}"},
    json={"sourceKind": "phoneNumber", "sourceId": product_id},
).raise_for_status()
# (legacy alias: update_agent(id=agent_id, telephony_product_id=[product_id]) still works during the migration window)
```

## 5. Go live + prove it, and TELL THEM THE NUMBER
- **Inbound:** print the rented number explicitly: "Your agent is live. Dial
  **<+E164 number>** to talk to it." (get it from `phone_numbers.list()`).
- **Outbound:** place a test call. `client.atoms.calls.start_outbound_call(agent_id=agent_id, phone_number="<their E164>", from_number=rented_e164)` where `rented_e164` is the E.164 you rented in step 4, then poll `client.atoms.calls.get(id=<conversation_id>)` for status + transcript and report it. (`from_product_id=product_id` still works as a legacy alias.)
- **Both:** give the number to dial AND offer a test outbound call.
Confirm the greeting plays and the agent stays on-goal.
```

--------------------------------

### Verify installation with kubectl get pods,svc

Source: https://docs.smallest.ai/models/self-host/kubernetes-setup/quick-start

Verifies the installation by listing all pods and services. All pods should show 'Running' status. The services table lists expected endpoints: api-server (port 7100, REST API), lightning-asr-internal (port 2269, ASR inference), license-proxy (port 3369, license validation), and redis-master (port 6379, request queue).

```bash
kubectl get pods,svc
```

--------------------------------

### Create Environment File with License Key

Source: https://docs.smallest.ai/models/self-host/docker-setup/stt-deployment/quick-start

Creates a .env file with a placeholder license key. Replace 'your-license-key-here' with the actual license key from Smallest.ai. Never commit this file to version control.

```bash
cat > .env << 'EOF'
LICENSE_KEY=your-license-key-here
EOF
```

--------------------------------

### Get Current Post-Call Configuration

Source: https://docs.smallest.ai/voice-agents/developer-guide/operate/analytics/post-call-analytics

Retrieves the current post-call configuration for a given configuration ID and prints the configured disposition metrics with their types. Use this to verify or inspect the existing analytics setup before making changes.

```python
config = call.get_post_call_config("696e655577e1d88ff54b4fbf")

print("Configured metrics:")
for metric in config["data"].get("dispositionMetrics", []):
    print(f"  {metric['identifier']}: {metric['dispositionMetricType']}")
```

--------------------------------

### Install SDK and Set API Key

Source: https://docs.smallest.ai/models/documentation/voice-cloning/instant-clone-python-sdk

Install the Smallest AI Python SDK and set the SMALLEST_API_KEY environment variable, which the SDK reads automatically.

```bash
pip install smallestai
```

```bash
export SMALLEST_API_KEY=YOUR_API_KEY
```

--------------------------------

### Build TTS into your app with Python SDK (smallestai)

Source: https://docs.smallest.ai/models/documentation/text-to-speech-lightning/quickstart

Python SDK example using client.waves.synthesize_tts, which returns audio byte chunks you can join and save. Requires pip install smallestai and SMALLEST_API_KEY. The SDK also offers synthesize_sse_tts for SSE streaming.

```python
# Requires: pip install smallestai
from smallestai import SmallestAI

client = SmallestAI()  # reads SMALLEST_API_KEY from the environment

audio_chunks = client.waves.synthesize_tts(
    text="Modern problems require modern solutions.",
    voice_id="meher",
    model="lightning_v3.1_pro",
    sample_rate=24000,
    speed=1.0,
    output_format="wav",
)

with open("output.wav", "wb") as f:
    f.write(b"".join(audio_chunks))
print("Saved output.wav")
```

--------------------------------

### Complete IRSA setup script (setup-irsa.sh)

Source: https://docs.smallest.ai/models/self-host/kubernetes-setup/aws/iam-irsa

Complete script to set up all IRSA roles. It associates the OIDC provider, creates the cluster autoscaler policy, and creates the service account. Run after making it executable.

```bash
#!/bin/bash

CLUSTER_NAME="smallest-cluster"
REGION="us-east-1"
ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)

echo "Setting up IRSA for cluster: $CLUSTER_NAME"
echo "AWS Account: $ACCOUNT_ID"
echo "Region: $REGION"

eksctl utils associate-iam-oidc-provider \
  --cluster $CLUSTER_NAME \
  --region $REGION \
  --approve

echo "Creating Cluster Autoscaler policy..."
cat > cluster-autoscaler-policy.json <<EOF
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "autoscaling:DescribeAutoScalingGroups",
        "autoscaling:DescribeAutoScalingInstances",
        "autoscaling:DescribeLaunchConfigurations",
        "autoscaling:DescribeScalingActivities",
        "autoscaling:DescribeTags",
        "autoscaling:SetDesiredCapacity",
        "autoscaling:TerminateInstanceInAutoScalingGroup",
        "ec2:DescribeInstanceTypes",
        "ec2:DescribeLaunchTemplateVersions"
      ],
      "Resource": ["*"]
    }
  ]
}
EOF

aws iam create-policy \
  --policy-name AmazonEKSClusterAutoscalerPolicy \
  --policy-document file://cluster-autoscaler-policy.json

eksctl create iamserviceaccount \
  --cluster=$CLUSTER_NAME \
  --region=$REGION \
  --namespace=kube-system \
  --name=cluster-autoscaler \
  --attach-policy-arn=arn:aws:iam::${ACCOUNT_ID}:policy/AmazonEKSClusterAutoscalerPolicy \
  --override-existing-serviceaccounts \
  --approve

echo "IRSA setup complete!"
echo ""
echo "Update your values.yaml with:"
echo "cluster-autoscaler:"
echo "  rbac:"
echo "    serviceAccount:"
echo "      name: cluster-autoscaler"
echo "      annotations:"
echo "        eks.amazonaws.com/role-arn: arn:aws:iam::${ACCOUNT_ID}:role/eksctl-${CLUSTER_NAME}-addon-iamserviceaccount-..."
```

--------------------------------

### CPS limits response JSON

Source: https://docs.smallest.ai/voice-agents/platform/create-agent/cps

Example response from the GET CPS limits endpoint. Shows provider CPS limits, trunk details, and total CPS. Note that cpsLimit: null with isUnlimited: false means no reservation, and isUnlimited: true means unlimited reservation.

```json
{
  "status": true,
  "data": {
    "providers": {
      "plivo": { "cpsLimit": 5, "isUnlimited": false },
      "twilio": { "cpsLimit": 1, "isUnlimited": false }
    },
    "trunks": [
      {
        "terminationUrl": "43.205.53.11:5091",
        "cpsLimit": 1,
        "numbers": [
          {
            "trunkId": "6a1b2c3d4e5f60718293a4b5",
            "phoneNumber": "+919240923804",
            "name": "68c8f7c3a0a8ef01e4fb72fd-919240923804-vqrtq8foxf",
            "isActive": true
          }
        ]
      }
    ],
    "totalCps": 1
  }
}
```

--------------------------------

### Run Pipecat voice-smallest.py example

Source: https://docs.smallest.ai/voice-agents/integrations/agent-framework/pipecat

Clone the Pipecat repository, navigate to the examples/voice directory, and run the example in either server mode (-t daily) or direct mode (-d). Server mode opens a browser at http://localhost:7860 and creates a Daily room automatically; direct mode prints the room URL in the terminal.

```bash
git clone https://github.com/pipecat-ai/pipecat.git
cd pipecat/examples/voice
```

```bash
python voice-smallest.py -t daily
```

```bash
python voice-smallest.py -d
```

--------------------------------

### Install Agno

Source: https://docs.smallest.ai/voice-agents/integrations/agent-framework/agno

Installs the Agno framework. The Smallest AI toolkit uses Agno's built-in HTTP client, so no extra packages are required.

```bash
pip install agno
```

--------------------------------

### Create Project Directory

Source: https://docs.smallest.ai/models/self-host/docker-setup/stt-deployment/quick-start

Creates and navigates into the project directory for the Smallest Self-Host deployment.

```bash
mkdir -p ~/smallest-self-host
cd ~/smallest-self-host
```
Tokens:
Raw