### Manual Setup

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/backend-python/README.md

Commands for manually creating a virtual environment, installing dependencies, and starting the server.

```bash
# Create virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start server
python main.py
```

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

### Setup Web Agent Environment

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/README.md

Commands to navigate to the Python backend directory, configure the API key, and start the service.

```bash
cd web/xai/backend-python
# Create .env file:
echo "XAI_API_KEY=your_xai_api_key_here" > .env
./start.sh
```

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

### Setup Telephony Agent Environment

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/README.md

Commands to navigate to the telephony directory, install dependencies, and start the development server.

```bash
cd telephony/xai
# Create .env file with your credentials
npm install && npm run dev
```

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

### Manual Setup Commands

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/backend-nodejs/README.md

Commands for manual dependency installation and build management.

```bash
# Install dependencies
npm install

# Development mode (with auto-reload)
npm run dev

# Build TypeScript
npm run build

# Production mode
npm start
```

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

### Start the Server

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/README.md

Commands to initialize the server environment and start the service.

```bash
cd server
# Create .env file with your XAI_API_KEY
echo "XAI_API_KEY=your_key_here" > .env
./start.sh
```

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

### Initialize and Run ChatAppWithTools

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/multi_turn_conversation/guide.ipynb

Example of configuring the chat application with a system prompt and starting the conversation loop.

```python
SYSTEM_PROMPT = """
You are Grok, a customer service assistant created by xAI for a food delivery app similar to Deliveroo.
Your role is to assist users with questions about their orders.
You have the ability to create support tickets for users that are facing issues which you are unable to resolve, make sure to ask for the user's name and issue before creating the ticket.
Respond in a clear, friendly, and professional tone. Never stray off topic and focus exclusively on answering customer service queries.
"""

chat = ChatAppWithTools(
    x_ai_api_key=XAI_API_KEY,
    tools=TOOLS,
    executables=EXECUTABLES,
    arguments=ARGUMENTS,
    system_prompt=SYSTEM_PROMPT,
)
chat.converse()
```

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

### Start the WebRTC Server

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/client/README.md

Navigate to the server directory and execute the start script.

```bash
cd ../server
./start.sh
```

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

### Start the Client Application

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/client/README.md

Launch the development server for the client application.

```bash
./start.sh
```

```bash
npm run dev
```

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

### Start Frontend

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/client/README.md

Command to launch the frontend development server.

```bash
./start.sh
```

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

### Install Required Dependencies

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/multimodal/object_detection/guide.ipynb

Install the necessary Python packages to run the object detection examples.

```python
%pip install --quiet IPython openai pydantic tqdm python-dotenv opencv-python
```

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

### Initialize and Run XAI Native Telephony Server

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/README.md

Commands to install dependencies, configure environment variables, and start the development server for the XAI native telephony integration.

```bash
cd xai
npm install

# Configure environment
cp .env.example .env
# Edit .env with your keys

# Start server
npm run dev

# Expose to internet (for Twilio)
ngrok http 3000

# Configure Twilio webhook with ngrok URL
# Call your Twilio number!
```

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

### Start Server Commands

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/server/README.md

Commands to launch the server for production or development.

```bash
./start.sh
```

```bash
npm run build
npm start
```

```bash
npm run dev
```

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

### Initialize environment variables

Source: https://github.com/xai-org/xai-cookbook/blob/main/README.md

Copy the example environment file to create a local configuration.

```bash
cp .env.example .env
```

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

### Start Node.js Backend

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/openai/README.md

Commands to initialize and start the Node.js-based backend service.

```bash
cd backend-nodejs
./start.sh
```

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

### Start Python Backend

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/openai/README.md

Commands to initialize and start the Python-based backend service.

```bash
cd backend-python
./start.sh
```

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

### Start Telephony Agent

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/README.md

Commands to install dependencies and start the Twilio-integrated telephony agent.

```bash
cd telephony/xai
npm install
# Configure .env with API keys and Twilio credentials
npm run dev
```

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

### Install dependencies

Source: https://github.com/xai-org/xai-cookbook/blob/main/README.md

Install project dependencies using uv.

```bash
uv sync
```

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

### Environment Variable Setup

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/README.md

Commands to initialize the environment configuration file.

```bash
cd xai
cp .env.example .env

# Edit .env with:
XAI_API_KEY=your_xai_api_key_here
HOSTNAME=your-ngrok-domain.ngrok.app
```

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

### Server Configuration

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/README.md

Example environment variables for the server configuration file.

```bash
# Required
XAI_API_KEY=your_xai_api_key_here

# Optional
PORT=8000
VOICE=ara
INSTRUCTIONS="You are a helpful voice assistant. You are speaking to a user in real-time over audio. Keep your responses conversational and concise since they will be spoken aloud."
API_URL=wss://api.x.ai/v1/realtime
```

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

### Install Dependencies

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/hyper_personalized_marketing/guide.ipynb

Install the necessary Python packages for the project.

```bash
%pip install --quiet openai python-dotenv tqdm pandas aiofiles
```

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

### Configure Environment

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/backend-python/README.md

Prepare the environment variables by copying the example file and adding the XAI API key.

```bash
cp .env.example .env
# Edit .env and add your XAI_API_KEY
```

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

### Install Dependencies

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/function_calling_101/guide.ipynb

Install the required openai and pydantic libraries.

```python
!pip install openai pydantic --quiet
```

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

### Run the Application

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/xai/README.md

Starts the Express server to handle Twilio webhooks and media streams.

```bash
npm run dev
```

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

### Install Dependencies

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/xai/README.md

Installs the required Node.js packages for the application.

```bash
npm install
```

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

### Start Web Agent Backend and Frontend

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/README.md

Commands to initialize the web agent backend and frontend services.

```bash
# Backend (choose one)
cd web/xai/backend-python && ./start.sh
# or
cd web/xai/backend-nodejs && ./start.sh

# Frontend (in another terminal)
cd web/client && ./start.sh

# Open http://localhost:5173
```

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

### Start Frontend and Backend

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/openai/README.md

Commands to launch both the backend and frontend services in separate terminals.

```bash
# Terminal 1: Start backend
cd backend-python  # or backend-nodejs
./start.sh

# Terminal 2: Start frontend
cd ../client
./start.sh
```

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

### Start XAI Backends

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/README.md

Commands to initialize the Python or Node.js backend services on port 8000.

```bash
cd xai/backend-python
./start.sh
```

```bash
cd xai/backend-nodejs
./start.sh
```

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

### Install pre-commit hooks

Source: https://github.com/xai-org/xai-cookbook/blob/main/README.md

Set up pre-commit hooks to ensure code quality and security.

```bash
uv run pre-commit install
```

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

### Start WebRTC Agent Server and Client

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/README.md

Commands to initialize the WebRTC relay server and client application.

```bash
# Server
cd webrtc/server && ./start.sh

# Client (in another terminal)
cd webrtc/client && ./start.sh

# Open http://localhost:5173
```

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

### Install Required Python Dependencies

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/sentiment_analysis_on_x/guide.ipynb

Install the necessary libraries for interacting with the X API, xAI API, and handling asynchronous requests.

```python
%pip install -q openai tweepy python-dotenv aiohttp async_lru oauthlib
```

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

### Install Required Dependencies

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/multi_turn_conversation/guide.ipynb

Install the necessary Python packages for interacting with the xAI API and managing environment variables.

```python
%pip install --quiet openai python-dotenv pydantic
```

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

### Launch Jupyter Notebooks

Source: https://github.com/xai-org/xai-cookbook/blob/main/README.md

Start the Jupyter server to interact with the notebooks.

```bash
uv run jupyter notebook examples/
```

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

### Start Backend Servers

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/client/README.md

Commands to launch either the Python or Node.js backend server on port 8000.

```bash
# XAI Python
cd ../xai/backend-python && ./start.sh

# XAI Node.js
cd ../xai/backend-nodejs && ./start.sh
```

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

### Exposing Local Server with ngrok

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/README.md

Commands to install and run ngrok to expose the local development server to the internet.

```bash
# Install ngrok
brew install ngrok  # macOS
# or download from ngrok.com

# Start your server first
npm run dev

# In another terminal, expose it
ngrok http 3000

# Copy the HTTPS URL (e.g., https://abc123.ngrok.io)
```

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

### Local Development Workflow

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/README.md

Commands to start the local server and expose it to the internet via ngrok for Twilio integration.

```bash
# Start server
npm run dev

# Use ngrok for external access
ngrok http 3000

# Call your Twilio number
```

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

### Initialize and Run the Chat Application

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/multi_turn_conversation/guide.ipynb

Configures the ChatApp with a system prompt and starts the interactive conversation loop.

```python
SYSTEM_PROMPT = """
You are Grok, a customer service assistant created by xAI for a food delivery app similar to Deliveroo. 
Your role is to assist users with questions about their orders. 
Respond in a clear, friendly, and professional tone. Never stray off topic and focus exclusively on answering customer service queries.
"""

app = ChatApp(
    x_ai_api_key=XAI_API_KEY,
    system_prompt=SYSTEM_PROMPT,
)
app.converse()
```

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

### Create Session Response

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/backend-python/README.md

Example JSON response from the POST /sessions endpoint.

```json
{
  "session_id": "uuid",
  "websocket_url": "/ws/{session_id}"
}
```

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

### Enable Debug Logging

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/README.md

Sets the application log level to debug before starting the development server.

```bash
# Set log level
LOG_LEVEL=debug npm run dev
```

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

### Test Server Endpoints

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/backend-python/README.md

Example curl commands to verify server health and session management.

```bash
# Health check
curl http://localhost:8000/health

# Create session
curl -X POST http://localhost:8000/sessions

# List sessions
curl http://localhost:8000/sessions
```

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

### Start Ngrok Tunnel

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/xai/README.md

Exposes the local server to the internet for Twilio webhook communication.

```bash
ngrok http 3000
```

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

### Start Stream Filtering

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/sentiment_analysis_on_x/guide.ipynb

Initiates the stream filter with specific expansions and fields, wrapped in an asyncio timeout.

```python
import asyncio

await asyncio.wait_for(
    stream.filter(
        expansions=["author_id"],
        tweet_fields=["created_at", "author_id", "text"],
        user_fields=["name", "username", "verified", "public_metrics"],
    ),
    timeout=30,
)
```

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

### GET /

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/README.md

Retrieves service information.

```APIDOC
## GET /

### Description
Retrieves basic service information.

### Method
GET

### Endpoint
/
```

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

### GET /sessions

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/README.md

Lists all active sessions.

```APIDOC
## GET /sessions

### Description
Retrieves a list of all currently active sessions.

### Method
GET

### Endpoint
/sessions
```

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

### GET /health

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/README.md

Performs a health check on the service.

```APIDOC
## GET /health

### Description
Performs a health check and returns the status of the service.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- **status** (string) - The health status of the service
- **provider** (string) - The provider name
- **timestamp** (string) - The current server timestamp
- **sessions_active** (integer) - The number of currently active sessions
```

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

### Initialize Grok Client

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/hyper_personalized_marketing/guide.ipynb

Set up the AsyncOpenAI client to interact with the xAI API.

```python
import os

from dotenv import load_dotenv
from openai import AsyncOpenAI

load_dotenv()

GROK_2_IMAGE = "grok-2-image"

GROK_4 = "grok-4"

grok_client = AsyncOpenAI(
    base_url="https://api.x.ai/v1", api_key=os.getenv("XAI_API_KEY")
)
```

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

### GET /sessions/:sessionId/stats

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/server/README.md

Retrieves WebRTC statistics for a specific session.

```APIDOC
## GET /sessions/:sessionId/stats

### Description
Retrieves WebRTC statistics for a specific session.

### Method
GET

### Endpoint
/sessions/:sessionId/stats

### Parameters
#### Path Parameters
- **sessionId** (string) - Required - The ID of the session

### Response
#### Success Response (200)
- **session_id** (string) - The ID of the session
- **stats** (object) - WebRTC connection statistics
```

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

### Clone Repository

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/xai/README.md

Initializes the project directory from the source repository.

```bash
# Clone the repository
git clone <your-repo-url>
cd examples/agent/telephony/xai
```

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

### Initialize Grok Client

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/multimodal/object_detection/guide.ipynb

Set up the OpenAI-compatible client to interact with the Grok API.

```python
from openai import OpenAI

GROK_VISION_MODEL = "grok-2-vision-latest"
GROK_MODEL = "grok-4"

grok_client = OpenAI(base_url=BASE_URL, api_key=XAI_API_KEY)
```

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

### Clone the repository

Source: https://github.com/xai-org/xai-cookbook/blob/main/README.md

Initial step to download the project source code.

```bash
git clone https://github.com/xai-org/xai-cookbook.git
cd xai-cookbook
```

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

### Initialize chat application with tools

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/multi_turn_conversation/guide.ipynb

Configures the system prompt and initializes the chat application with the updated toolset.

```python
SYSTEM_PROMPT = """
You are Grok, a customer service assistant created by xAI for a food delivery app similar to Deliveroo.
Your role is to assist users with questions about their orders, create support tickets for unresolved issues, and analyze receipt images when provided.
Respond in a clear, friendly, and professional tone. Never stray off topic and focus exclusively on answering customer service queries."
"""

chat = ChatAppWithTools(
    x_ai_api_key=XAI_API_KEY,
    tools=TOOLS,
    executables=EXECUTABLES,
    arguments=ARGUMENTS,
    system_prompt=SYSTEM_PROMPT,
)
chat.converse()
```

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

### REST API Responses

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/server/README.md

Example JSON responses for various REST API endpoints.

```json
{
  "service": "XAI Voice WebRTC Server",
  "provider": "XAI",
  "protocol": "WebRTC",
  "version": "1.0.0",
  "status": "running",
  "endpoints": {
    "health": "/health",
    "sessions": "/sessions",
    "signaling": "/signaling/{session_id}"
  }
}
```

```json
{
  "status": "healthy",
  "provider": "XAI",
  "protocol": "WebRTC",
  "timestamp": "2025-11-10T12:00:00.000Z",
  "sessions_active": 0,
  "peer_connections_active": 0,
  "config": {
    "api_key_configured": true,
    "api_url": "wss://api.x.ai/v1/realtime",
    "port": 8000,
    "voice": "ara"
  }
}
```

```json
{
  "session_id": "session_1699632000000_abc123",
  "signaling_url": "/signaling/session_1699632000000_abc123",
  "created_at": "2025-11-10T12:00:00.000Z"
}
```

```json
{
  "sessions": [
    {
      "id": "session_1699632000000_abc123",
      "created_at": "2025-11-10T12:00:00.000Z",
      "status": "active",
      "webrtc_stats": {
        "bitrate": {
          "audio_in": 0,
          "audio_out": 0
        },
        "jitter": 0,
        "packetLoss": 0,
        "connectionState": "connected",
        "iceConnectionState": "connected",
        "lastUpdated": "2025-11-10T12:00:05.000Z"
      }
    }
  ],
  "count": 1
}
```

```json
{
  "message": "Session deleted",
  "session_id": "session_1699632000000_abc123"
}
```

```json
{
  "session_id": "session_1699632000000_abc123",
  "stats": {
    "bitrate": {
      "audio_in": 32000,
      "audio_out": 64000
    },
    "jitter": 0.015,
    "packetLoss": 2,
    "connectionState": "connected",
    "iceConnectionState": "connected",
    "lastUpdated": "2025-11-10T12:00:10.000Z"
  }
}
```

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

### Initialize API Environment

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/multi_turn_conversation/guide.ipynb

Load the API key from a .env file and verify its existence before proceeding with API calls.

```python
import os

from dotenv import load_dotenv

load_dotenv()

XAI_API_KEY = os.getenv("XAI_API_KEY")
if not XAI_API_KEY:
    raise ValueError("XAI_API_KEY is not set")
```

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

### Initialize xAI Client

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/function_calling_101/guide.ipynb

Configure the OpenAI client to point to the xAI API base URL.

```python
from openai import OpenAI

XAI_API_KEY = "" # paste your API key here

client = OpenAI(
    base_url="https://api.x.ai/v1",
    api_key=XAI_API_KEY
)
```

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

### Initialize and Configure Stream

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/sentiment_analysis_on_x/guide.ipynb

Loads environment variables and initializes the XStream client with authentication credentials.

```python
import os

from dotenv import load_dotenv

load_dotenv()

x_api_key = os.getenv("X_API_KEY")
if x_api_key is None:
    raise ValueError("X_API_KEY is not set")

x_api_secret = os.getenv("X_API_SECRET")
if x_api_secret is None:
    raise ValueError("X_API_SECRET is not set")

stream = XStream(x_api_key, x_api_secret)

# Uncomment to add the rule to the stream, if not already added
# await stream.add_rules(StreamRule(value=GENERAL_BTC_RULE["value"], tag=GENERAL_BTC_RULE["tag"]))

# Uncomment to check existing rules
# rules = await stream.get_rules()
# print(rules)
```

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

### Initiate Outbound Call

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/xai/README.md

Triggers the agent to start an outbound call to the configured target number.

```bash
npm run outbound
```

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

### WebSocket Client Messages

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/xai/backend-python/README.md

Example JSON messages sent from the client to the server over the WebSocket connection.

```json
{"type": "input_audio_buffer.append", "audio": "base64_pcm16_native_rate"}
{"type": "input_audio_buffer.commit"}
{"type": "response.create"}
```

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

### Configure Environment Variables

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/xai/README.md

Sets the necessary API keys and host configuration for the application.

```bash
XAI_API_KEY=your-xai-api-key
```

```bash
HOSTNAME=your-ngrok-domain.ngrok.app
```

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

### Configure Tool Definitions and Executables

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/multi_turn_conversation/guide.ipynb

Sets up the tool schema, executable mapping, and argument type definitions for the Grok API.

```python
from typing import Callable, Type

TOOLS = [
    {
        "type": "function",
        "function": {
            "name": "create_customer_ticket",
            "description": "Create a customer ticket",
            "parameters": CreateCustomerTicketRequest.model_json_schema(),
        },
    }
]

EXECUTABLES: dict[str, Callable] = {
    "create_customer_ticket": create_customer_ticket,
}

ARGUMENTS: dict[str, Type[BaseModel]] = {
    "create_customer_ticket": CreateCustomerTicketRequest,
}
```

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

### Initialize Grok Client

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/sentiment_analysis_on_x/guide.ipynb

Retrieves the API key from environment variables and instantiates the analyzer.

```python
xai_api_key = os.getenv("XAI_API_KEY")
if xai_api_key is None:
    raise ValueError("XAI_API_KEY is not set")

grok_client = GrokSentimentAnalyzer(xai_api_key)
```

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

### Development and Build Scripts

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/server/README.md

Commands for managing dependencies, building the project, and running the server in various modes.

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Run compiled JavaScript
npm start

# Development mode (ts-node, no build)
npm run dev

# Watch mode (recompile on changes)
npm run watch
```

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

### Batch Process Marketing Pieces

Source: https://github.com/xai-org/xai-cookbook/blob/main/examples/hyper_personalized_marketing/guide.ipynb

Uses tqdm_asyncio to concurrently generate marketing pieces for a list of customers.

```python
marketing_pieces: list[str] = await tqdm_asyncio.gather(
    *[
        generate_marketing_piece(grok_client, customer)
        for customer in updated_customers
    ]
)
```

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

### Client Development Commands

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/README.md

Command for running the client development server.

```bash
cd client
npm run dev  # Vite dev server with HMR
```

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

### Server Development Commands

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/README.md

Commands for running the server in development mode.

```bash
cd server
npm run dev  # Run with ts-node (no build step)
npm run watch  # Watch mode for TypeScript
```

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

### Testing the Voice Agent

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/telephony/README.md

Instruction for verifying the agent deployment.

```bash
# Call your Twilio number
# You should hear the AI agent!
```

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

### Project Directory Structure

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/server/README.md

Overview of the server project file organization.

```text
server/
├── src/
│   ├── index.ts              # Main server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── session-manager.ts    # Session lifecycle management
│   ├── rtc-peer.ts           # WebRTC peer connection manager
│   ├── xai-client.ts         # XAI API WebSocket client
│   └── audio-processor.ts    # Audio format utilities
├── dist/                     # Compiled JavaScript (generated)
├── package.json              # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
├── start.sh                  # Startup script
└── README.md                 # This file
```

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

### Project Development Scripts

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/client/README.md

Standard npm commands for managing dependencies, running the development server, building for production, and linting.

```bash
# Install dependencies
npm install

# Development server with HMR
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Lint code
npm run lint
```

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

### Manual Development Commands

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/client/README.md

Standard npm commands for managing the development and production lifecycle of the project.

```bash
# Install dependencies
npm install

# Start development server
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview
```

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

### Frontend Environment Configuration

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/README.md

Required environment variable for the frontend to locate the backend.

```bash
# Backend URL (same for all backends)
VITE_API_BASE_URL=http://localhost:8000
```

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

### Backend Environment Configuration

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/web/README.md

Required environment variables for backend services.

```bash
# API key
XAI_API_KEY=your_key

# API endpoint
API_URL=wss://api.x.ai/v1/realtime

# Server configuration (same for all)
PORT=8000
VOICE=ara
INSTRUCTIONS="You are a helpful voice assistant. You are speaking to a user in real-time over audio. Keep your responses conversational and concise since they will be spoken aloud."
```

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

### Configure Git LFS

Source: https://github.com/xai-org/xai-cookbook/blob/main/README.md

Initialize Git LFS for tracking large files.

```bash
git lfs install
```

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

### Configure Backend API URL

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/client/README.md

Set the VITE_API_BASE_URL environment variable in a .env file to point to the backend server.

```bash
# Backend server URL (optional)
# Default: http://localhost:8000
VITE_API_BASE_URL=http://localhost:8000
```

```bash
VITE_API_BASE_URL=http://localhost:8001
```

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

### Enable TURN Server Support

Source: https://github.com/xai-org/xai-cookbook/blob/main/voice-examples/agent/webrtc/server/README.md

Toggle for enabling TURN servers in src/rtc-peer.ts to support restrictive networks.

```javascript
// Set to true to enable TURN servers (for restrictive networks)
const ENABLE_TURN = false;  // Default: false
```