### Install Dependencies

Source: https://github.com/bhavesh-songara/csa/blob/prod/README.md

Install all necessary project dependencies using npm. This command should be run after cloning the repository.

```bash
npm install
```

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

### Start Development Server

Source: https://github.com/bhavesh-songara/csa/blob/prod/README.md

Run this command to start the local development server for the CSA application. Access the application at http://localhost:3000.

```bash
npm run dev
```

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

### Environment Configuration

Source: https://github.com/bhavesh-songara/csa/blob/prod/README.md

Copy the example environment file to create your own .env file. This file will store your sensitive API keys and database credentials.

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

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

### Use Webcam Hook

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Hook for capturing video from the user's webcam. Provides functions to start and stop the camera stream.

```typescript
import { useWebcam } from "@/hooks/stream/use-webcam";

function WebcamComponent() {
  const { stream, isStreaming, start, stop } = useWebcam();
  const videoRef = useRef<HTMLVideoElement>(null);

  useEffect(() => {
    if (videoRef.current && stream) {
      videoRef.current.srcObject = stream;
    }
  }, [stream]);

  return (
    <div>
      <video ref={videoRef} autoPlay playsInline muted />
      <button onClick={isStreaming ? stop : start}>
        {isStreaming ? "Stop Camera" : "Start Camera"}
      </button>
    </div>
  );
}
```

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

### Clone CSA Repository

Source: https://github.com/bhavesh-songara/csa/blob/prod/README.md

Use this command to clone the CSA project repository from GitHub. Ensure you have Git installed.

```bash
git clone https://github.com/your-username/csa.git
cd csa
```

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

### Capture Microphone Input with AudioRecorder

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Use the AudioRecorder class to capture microphone audio, convert it to PCM16 format, and emit base64-encoded chunks for the Gemini API. Requires user gesture to start recording.

```typescript
import { AudioRecorder } from "@/lib/audio/audio-recorder";

const recorder = new AudioRecorder(16000); // 16kHz sample rate

// Handle recorded audio data
recorder.on("data", (base64AudioChunk: string) => {
  // Send to Gemini API
  client.sendRealtimeInput([
    { mimeType: "audio/pcm;rate=16000", data: base64AudioChunk }
  ]);
});

// Handle volume changes for UI feedback
recorder.on("volume", (volume: number) => {
  console.log("Input volume:", volume); // 0-1 range
});

// Start recording (requires user gesture for getUserMedia)
await recorder.start();

// Stop recording when done
recorder.stop();
```

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

### Get Single Agent API

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Retrieves details of a specific agent by its MongoDB ObjectId. Returns the complete agent configuration including name, description, and instructions.

```APIDOC
## GET /api/agent/{agentId}

### Description
Retrieves details of a specific agent by its MongoDB ObjectId.

### Method
GET

### Endpoint
/api/agent/{agentId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The MongoDB ObjectId of the agent to retrieve.

### Response
#### Success Response (200 OK)
- **agent** (object) - The agent configuration object.
  - **_id** (string) - The unique MongoDB identifier for the agent.
  - **name** (string) - The name of the agent.
  - **description** (string) - The description of the agent.
  - **instructions** (string) - The behavioral instructions for the agent.
  - **isDeleted** (boolean) - Indicates if the agent has been soft-deleted.
  - **createdAt** (string) - The timestamp when the agent was created.
  - **updatedAt** (string) - The timestamp when the agent was last updated.

#### Error Response (404 Not Found)
- **message** (string) - Error message indicating the agent was not found.

#### Response Example (Success)
```json
{
  "agent": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "Support Bot",
    "description": "Technical support specialist",
    "instructions": "You are a friendly technical support agent...",
    "isDeleted": false,
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  }
}
```

#### Response Example (Not Found)
```json
{
  "message": "Agent not found"
}
```
```

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

### Get All Agents API

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Retrieves a list of all active (non-deleted) AI agents configured in the system. Returns an array of agent objects with their MongoDB IDs, names, descriptions, and instructions.

```APIDOC
## GET /api/agent

### Description
Retrieves a list of all active AI agents configured in the system.

### Method
GET

### Endpoint
/api/agent

### Response
#### Success Response (200 OK)
- **data** (array) - An array of agent objects.
  - **_id** (string) - The unique MongoDB identifier for the agent.
  - **name** (string) - The name of the agent.
  - **description** (string) - The description of the agent.
  - **instructions** (string) - The behavioral instructions for the agent.
  - **isDeleted** (boolean) - Indicates if the agent has been soft-deleted.
  - **createdAt** (string) - The timestamp when the agent was created.
  - **updatedAt** (string) - The timestamp when the agent was last updated.

#### Response Example
```json
{
  "data": [
    {
      "_id": "507f1f77bcf86cd799439011",
      "name": "Support Bot",
      "description": "Technical support specialist",
      "instructions": "You are a friendly technical support agent...",
      "isDeleted": false,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}
```
```

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

### Establish WebSocket Connection and Handle Events

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Initializes the MultimodalLiveClient, configures the session with model and speech settings, and sets up event listeners for connection status, audio, content, and other events. Connects to the Gemini API and sends an initial text message.

```typescript
import { MultimodalLiveClient } from "@/lib/multimodal-live-client";
import { LiveConfig } from "@/constants/multimodal-live-types";

// Initialize the client with your Gemini API key
const client = new MultimodalLiveClient({
  apiKey: process.env.NEXT_PUBLIC_GEMINI_API_KEY,
  // Optional custom URL (defaults to Google's WebSocket endpoint)
  // url: "wss://generativelanguage.googleapis.com/ws/google.ai.generativelanguage.v1alpha.GenerativeService.BidiGenerateContent"
});

// Configure the live session
const config: LiveConfig = {
  model: "models/gemini-2.0-flash-exp",
  systemInstruction: {
    parts: [{ text: "You are a friendly customer service agent. Help users with their questions." }]
  },
  generationConfig: {
    speechConfig: {
      voiceConfig: {
        prebuiltVoiceConfig: {
          voiceName: "Aoede" // Options: "Puck", "Charon", "Kore", "Fenrir", "Aoede"
        }
      }
    }
  }
};

// Connect and set up event listeners
client.on("open", () => console.log("Connected to Gemini API"));
client.on("setupcomplete", () => console.log("Session setup complete"));
client.on("audio", (data: ArrayBuffer) => {
  // Handle incoming audio from AI (PCM16 format)
  console.log("Received audio:", data.byteLength, "bytes");
});
client.on("content", (content) => {
  // Handle text or other content from AI
  console.log("Received content:", content);
});
client.on("turncomplete", () => console.log("AI finished speaking"));
client.on("interrupted", () => console.log("AI was interrupted"));
client.on("close", (event) => console.log("Connection closed:", event.reason));

// Establish the connection
await client.connect(config);

// Send text message to the AI
client.send({ text: "Hello, I need help with my order" });

// Disconnect when done
client.disconnect();

```

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

### Environment Configuration - .env

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Configuration for required environment variables for MongoDB connection and Google Gemini API access.

```bash
# .env file configuration
NEXT_PUBLIC_GEMINI_API_KEY=your_gemini_api_key_here
MONGODB_USERNAME=your_mongodb_username
MONGODB_PASSWORD=your_mongodb_password
MONGODB_HOST=your_mongodb_host.mongodb.net
```

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

### Provide LiveAPI Context with LiveAPIProvider

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Wrap your application with LiveAPIProvider to make the Gemini Live API connection accessible throughout the component tree. It requires an API key for initialization.

```typescript
import { LiveAPIProvider, useLiveAPIContext } from "@/contexts/LiveAPIContext";

// Wrap your app or route with the provider
function App() {
  return (
    <LiveAPIProvider apiKey={process.env.NEXT_PUBLIC_GEMINI_API_KEY}>
      <CustomerSupportPage />
    </LiveAPIProvider>
  );
}

// Access the Live API in any child component
function CustomerSupportPage() {
  const { client, connected, connect, disconnect, volume } = useLiveAPIContext();

  const handleStartSession = async () => {
    try {
      await connect();
      console.log("Session started");
    } catch (error) {
      console.error("Failed to connect:", error);
    }
  };

  return (
    <div>
      <h1>Customer Support</h1>
      <button onClick={connected ? disconnect : handleStartSession}>
        {connected ? "End Session" : "Start Session"}
      </button>
      {connected && <AudioVisualizer volume={volume} />}
    </div>
  );
}
```

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

### Create AI Agent

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Use this endpoint to create a new AI customer service agent. Provide a name, description, and custom instructions for the agent's behavior. The agent configuration is stored in MongoDB.

```bash
curl -X POST http://localhost:3000/api/agent \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "description": "Technical support specialist",
    "instructions": "You are a friendly technical support agent. Help users troubleshoot software issues, guide them through solutions step by step, and always maintain a helpful tone."
  }'
```

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

### Create Agent API

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Creates a new AI customer service agent with custom name, description, and behavioral instructions. The agent configuration is stored in MongoDB and can be used to establish live voice/video sessions.

```APIDOC
## POST /api/agent

### Description
Creates a new AI customer service agent with custom name, description, and behavioral instructions.

### Method
POST

### Endpoint
/api/agent

### Parameters
#### Request Body
- **name** (string) - Required - The name of the agent.
- **description** (string) - Required - A brief description of the agent's role.
- **instructions** (string) - Required - The behavioral instructions for the agent.

### Request Example
```json
{
  "name": "Support Bot",
  "description": "Technical support specialist",
  "instructions": "You are a friendly technical support agent. Help users troubleshoot software issues, guide them through solutions step by step, and always maintain a helpful tone."
}
```

### Response
#### Success Response (201 Created)
- **message** (string) - Confirmation message indicating successful agent creation.

#### Response Example
```json
{
  "message": "Agent created successfully"
}
```
```

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

### Handle Tool/Function Calls from AI

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Configures the client with tools for the AI to use and sets up an event listener to handle 'toolcall' events. It processes function calls, performs actions (like looking up order status), and sends responses back to the AI.

```typescript
import { MultimodalLiveClient } from "@/lib/multimodal-live-client";
import { ToolCall, LiveFunctionResponse } from "@/constants/multimodal-live-types";

const client = new MultimodalLiveClient({
  apiKey: process.env.NEXT_PUBLIC_GEMINI_API_KEY
});

// Configure with tools
const config = {
  model: "models/gemini-2.0-flash-exp",
  tools: [
    {
      functionDeclarations: [
        {
          name: "lookup_order",
          description: "Look up order status by order ID",
          parameters: {
            type: "object",
            properties: {
              order_id: { type: "string", description: "The order ID" }
            },
            required: ["order_id"]
          }
        }
      ]
    }
  ]
};

// Handle tool calls from the AI
client.on("toolcall", async (toolCall: ToolCall) => {
  const responses: LiveFunctionResponse[] = [];

  for (const call of toolCall.functionCalls) {
    if (call.name === "lookup_order") {
      const orderId = call.args.order_id;
      // Perform the actual lookup
      const orderStatus = await getOrderStatus(orderId);

      responses.push({
        id: call.id,
        response: { status: orderStatus, orderId }
      });
    }
  }

  // Send the function responses back to the AI
  client.sendToolResponse({ functionResponses: responses });
});

// Handle tool call cancellations
client.on("toolcallcancellation", (cancellation) => {
  console.log("Tool calls cancelled:", cancellation.ids);
});

await client.connect(config);

```

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

### Environment Configuration - src/config/index.ts

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Configuration loading logic that merges common, environment-specific (development, production, local), and JSON configurations.

```typescript
// src/config/index.ts - Configuration loading
import commonConfig from "./common.json";
import developmentConfig from "./development.json";
import productionConfig from "./production.json";
import localConfig from "./local.json";

const env = process.env.NODE_ENV || "development";

const configs = {
  development: { ...commonConfig, ...developmentConfig },
  production: { ...commonConfig, ...productionConfig },
  local: { ...commonConfig, ...localConfig }
};

export default configs[env as keyof typeof configs];
```

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

### Fetch All Agents

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Retrieve a list of all active AI agents. This endpoint returns an array of agent objects, including their IDs, names, descriptions, and instructions.

```bash
curl -X GET http://localhost:3000/api/agent
```

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

### Use Screen Capture Hook

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Hook for capturing the user's screen using the Screen Capture API. Use to initiate and stop screen sharing streams.

```typescript
import { useScreenCapture } from "@/hooks/stream/use-screen-capture";

function ScreenShareComponent() {
  const { stream, isStreaming, start, stop } = useScreenCapture();

  const handleToggle = async () => {
    if (isStreaming) {
      stop();
    } else {
      const mediaStream = await start();
      // Use the stream with a video element or canvas
      videoRef.current.srcObject = mediaStream;
    }
  };

  return (
    <div>
      <video ref={videoRef} autoPlay playsInline />
      <button onClick={handleToggle}>
        {isStreaming ? "Stop Sharing" : "Share Screen"}
      </button>
    </div>
  );
}
```

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

### Agent Service - Fetch All Agents

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Client-side service for fetching all agent data using React Query. Handles loading and error states.

```typescript
import { AgentService } from "@/services/AgentService";
import { useQuery } from "@tanstack/react-query";

// Fetch all agents
function AgentList() {
  const { data, isLoading, error } = useQuery({
    queryKey: [AgentService.BASE],
    queryFn: () => AgentService.getAllAgents()
  });

  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error loading agents</div>;

  return (
    <ul>
      {data?.data.map((agent) => (
        <li key={agent._id}>{agent.name}</li>
      ))}
    </ul>
  );
}
```

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

### Send Realtime Audio and Video Input

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Sends real-time audio (PCM16 at 16kHz) and video (JPEG) data to the Gemini API. Ensure data is base64 encoded. Can send audio, video, or both simultaneously.

```typescript
import { MultimodalLiveClient } from "@/lib/multimodal-live-client";

const client = new MultimodalLiveClient({
  apiKey: process.env.NEXT_PUBLIC_GEMINI_API_KEY
});

// After connecting...

// Send audio chunk (base64 encoded PCM16 at 16kHz)
client.sendRealtimeInput([
  {
    mimeType: "audio/pcm;rate=16000",
    data: base64AudioChunk // Base64 encoded audio data
  }
]);

// Send video frame (base64 encoded JPEG)
client.sendRealtimeInput([
  {
    mimeType: "image/jpeg",
    data: base64ImageData // Base64 encoded JPEG image
  }
]);

// Send both audio and video together
client.sendRealtimeInput([
  { mimeType: "audio/pcm;rate=16000", data: base64Audio },
  { mimeType: "image/jpeg", data: base64Image }
]);

```

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

### Use useLiveAPI Hook for Gemini Live API

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Use this hook to manage Gemini Live API connections, state, and configuration within React components. It requires an API key for initialization.

```typescript
import { useLiveAPI, UseLiveAPIResults } from "@/hooks/use-live-api";

function CustomerSupportChat() {
  const {
    client,        // MultimodalLiveClient instance
    connected,     // boolean - connection status
    connect,       // () => Promise<void> - establish connection
    disconnect,    // () => Promise<void> - close connection
    config,        // LiveConfig - current configuration
    setConfig,     // update configuration
    volume         // number - current output audio volume (0-1)
  }: UseLiveAPIResults = useLiveAPI({
    apiKey: process.env.NEXT_PUBLIC_GEMINI_API_KEY
  });

  // Update configuration before connecting
  useEffect(() => {
    setConfig({
      model: "models/gemini-2.0-flash-exp",
      systemInstruction: {
        parts: [{ text: "You are a helpful customer service agent." }]
      },
      generationConfig: {
        speechConfig: {
          voiceConfig: {
            prebuiltVoiceConfig: { voiceName: "Aoede" }
          }
        }
      }
    });
  }, []);

  return (
    <div>
      <p>Status: {connected ? "Connected" : "Disconnected"}</p>
      <p>Volume: {Math.round(volume * 100)}%</p>
      <button onClick={connected ? disconnect : connect}>
        {connected ? "End Call" : "Start Call"}
      </button>
    </div>
  );
}
```

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

### Play AI Audio Response with AudioStreamer

Source: https://context7.com/bhavesh-songara/csa/llms.txt

The AudioStreamer class plays PCM16 audio from the Gemini API, managing buffering and volume. It can also integrate with volume meter worklets for UI feedback. Requires user interaction to resume playback.

```typescript
import { AudioStreamer } from "@/lib/audio/audio-streamer";
import { audioContext } from "@/lib/audio/utils";
import VolMeterWorklet from "@/lib/worklets/vol-meter";

// Create audio context and streamer
const ctx = await audioContext({ id: "audio-out" });
const streamer = new AudioStreamer(ctx);

// Add volume meter for UI visualization
await streamer.addWorklet("vumeter-out", VolMeterWorklet, (event) => {
  console.log("Output volume:", event.data.volume);
});

// Handle incoming audio from Gemini API
client.on("audio", (data: ArrayBuffer) => {
  streamer.addPCM16(new Uint8Array(data));
});

// Handle interruptions (user starts speaking)
client.on("interrupted", () => {
  streamer.stop();
});

// Callback when audio playback completes
streamer.onComplete = () => {
  console.log("Finished playing AI response");
};

// Resume playback (call after user interaction)
await streamer.resume();

// Stop playback
streamer.stop();
```

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

### Fetch Single Agent

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Retrieve details for a specific AI agent using its MongoDB ObjectId. This endpoint returns the complete agent configuration or a 404 error if the agent is not found.

```bash
curl -X GET http://localhost:3000/api/agent/507f1f77bcf86cd799439011
```

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

### Update Agent Configuration

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Update an existing AI agent's configuration, including its name, description, and instructions. The agentId must be a valid 24-character hex MongoDB ObjectId.

```bash
curl -X PUT http://localhost:3000/api/agent/507f1f77bcf86cd799439011 \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Advanced Support Bot",
    "description": "Senior technical support specialist",
    "instructions": "You are an advanced technical support agent with expertise in troubleshooting complex software and hardware issues. Always provide detailed explanations."
  }'
```

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

### Agent Service - Fetch Specific Agent

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Client-side service for fetching a specific agent's data by ID using React Query. The query is enabled only when an agentId is provided.

```typescript
// Fetch a specific agent
function AgentDetail({ agentId }: { agentId: string }) {
  const { data, isLoading } = useQuery({
    queryKey: [AgentService.BASE, { agentId }],
    queryFn: () => AgentService.getAgent(agentId),
    enabled: !!agentId
  });

  if (isLoading) return <div>Loading...</div>;

  return (
    <div>
      <h2>{data?.agent.name}</h2>
      <p>{data?.agent.description}</p>
      <pre>{data?.agent.instructions}</pre>
    </div>
  );
}
```

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

### Use Agent Mutation Hook

Source: https://context7.com/bhavesh-songara/csa/llms.txt

React Query mutation hooks for agent management (create, update, delete). Handles cache invalidation and toast notifications automatically.

```typescript
import { useAgentMutation } from "@/hooks/mutations/useAgentMutation";

function AgentManagement() {
  const { addAgentMutation, updateAgentMutation, deleteAgentMutation } = useAgentMutation();

  // Create a new agent
  const handleCreate = async () => {
    await addAgentMutation.mutateAsync({
      name: "New Support Agent",
      description: "Handles general inquiries",
      instructions: "You are a helpful support agent. Answer questions politely and thoroughly."
    });
  };

  // Update an existing agent
  const handleUpdate = async (agentId: string) => {
    await updateAgentMutation.mutateAsync({
      agentId,
      name: "Updated Agent Name",
      description: "Updated description",
      instructions: "Updated instructions for the agent."
    });
  };

  // Delete an agent
  const handleDelete = async (agentId: string) => {
    await deleteAgentMutation.mutateAsync(agentId);
  };

  return (
    <div>
      <button
        onClick={handleCreate}
        disabled={addAgentMutation.isPending}
      >
        {addAgentMutation.isPending ? "Creating..." : "Create Agent"}
      </button>
    </div>
  );
}
```

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

### Update Agent API

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Updates an existing agent's configuration including name, description, and instructions. The agentId must be a valid 24-character hex MongoDB ObjectId.

```APIDOC
## PUT /api/agent/{agentId}

### Description
Updates an existing agent's configuration.

### Method
PUT

### Endpoint
/api/agent/{agentId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The MongoDB ObjectId of the agent to update.

#### Request Body
- **name** (string) - Optional - The new name for the agent.
- **description** (string) - Optional - The new description for the agent.
- **instructions** (string) - Optional - The new behavioral instructions for the agent.

### Request Example
```json
{
  "name": "Advanced Support Bot",
  "description": "Senior technical support specialist",
  "instructions": "You are an advanced technical support agent with expertise in troubleshooting complex software and hardware issues. Always provide detailed explanations."
}
```

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message indicating successful agent update.

#### Response Example
```json
{
  "message": "Agent updated successfully"
}
```
```

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

### Delete Agent (Soft Delete)

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Perform a soft delete on an agent by setting its `isDeleted` flag to true. The agent data is preserved but excluded from active agent queries.

```bash
curl -X DELETE http://localhost:3000/api/agent/507f1f77bcf86cd799439011
```

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

### Delete Agent API (Soft Delete)

Source: https://context7.com/bhavesh-songara/csa/llms.txt

Performs a soft delete on an agent by setting `isDeleted` to true. The agent data is preserved in the database but excluded from active agent queries.

```APIDOC
## DELETE /api/agent/{agentId}

### Description
Performs a soft delete on an agent.

### Method
DELETE

### Endpoint
/api/agent/{agentId}

### Parameters
#### Path Parameters
- **agentId** (string) - Required - The MongoDB ObjectId of the agent to delete.

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message indicating successful agent deletion.

#### Response Example
```json
{
  "message": "Agent deleted successfully"
}
```
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.