# @equos/browser-sdk [Equos.ai](https://www.equos.ai) official Browser SDK for real-time conversations with Equos AI agents. ## Prerequisites - Go to [Equos Studio](https://studio.equos.ai). - Create an organization. - Create a Character. ## Installation ```bash npm install @equos/browser-sdk ``` ## Quick Start ```typescript import { EquosConversation, EquosEvent, EquosMode } from '@equos/browser-sdk'; // Create a conversation (wsUrl and token come from your backend via @equos/node-sdk) const conversation = new EquosConversation({ config: { wsUrl: 'wss://your-livekit-server.example.com', token: 'your-consumer-access-token', agentIdentity: 'character-livekit-identity', // optional, filters tracks to this participant }, }); // Attach a video element to render the agent's audio + video const videoEl = document.querySelector('video'); conversation.attach(videoEl); // Listen to events conversation.on(EquosEvent.Utterance, (msg) => { console.log(`${msg.utterance.author}: ${msg.utterance.content}`); }); conversation.on(EquosEvent.AgentConnected, () => { console.log('Agent joined the room'); }); // Connect await conversation.connect(); // Send a text message to the agent conversation.sendText('Hello!'); // Disconnect when done await conversation.disconnect(); ``` ## Obtaining Connection Credentials > **WARNING:** `@equos/node-sdk` must only be used server-side (Node.js backend, API route, serverless function). Never expose your API key in client-side code — it would allow anyone to create conversations and consume credits on your behalf. Use `@equos/node-sdk` on your backend to create a conversation, then pass the connection credentials to the browser: ```typescript import { EquosClient } from '@equos/node-sdk'; const client = EquosClient.create('your-api-key', { endpoint: 'https://api.equos.ai', }); const response = await client.conversations.startConversation({ createEquosConversationRequest: { name: 'my-conversation', characterId: 'your-character-id', consumer: { name: 'User', identity: 'user-1', }, }, }); // Pass these to the browser SDK const { serverUrl, character } = response.conversation; const { consumerAccessToken } = response; const agentIdentity = character.livekitIdentity; ``` ## API ### `new EquosConversation(options)` | Option | Type | Default | Description | |--------|------|---------|-------------| | `config.wsUrl` | `string` | *required* | LiveKit WebSocket endpoint | | `config.token` | `string` | *required* | Room access token | | `config.agentIdentity` | `string?` | `undefined` | Agent participant identity (if omitted, all remote participants are treated as agents) | | `autoPublishMic` | `boolean` | `true` | Automatically enable microphone on connect | | `mode` | `EquosMode` | `'video'` | Initial conversation mode | ### Methods | Method | Description | |--------|-------------| | `connect()` | Connect to the LiveKit room | | `disconnect()` | Disconnect and clean up | | `sendText(text)` | Send a text message to the agent | | `sendContext(content)` | Inject context into the agent's prompt | | `setMode(mode)` | Switch conversation mode (`'text'`, `'audio'`, `'video'`) | | `setMicrophoneEnabled(enabled)` | Toggle microphone | | `setCameraEnabled(enabled)` | Toggle camera | | `setScreenShareEnabled(enabled)` | Toggle screen sharing | | `attach(element)` | Attach agent tracks to a `