Agent Platform Web SDK Overview

The platform provides Web SDK to embed agent chat and voice interactions in web applications. The Web SDK (@koreai/artemis-web-sdk) provides a TypeScript/JavaScript library for embedding agent chat and voice interactions in web applications. The SDK supports vanilla JavaScript, React hooks, and a web component for drop-in integration. The browser-facing SDK does not send the public pk_* key directly to /ws/sdk. It first exchanges the key for a short-lived SDK session token on POST /api/v1/sdk/init, then authenticates SDK HTTP routes with X-SDK-Token and the SDK WebSocket with Sec-WebSocket-Protocol: sdk-auth,<token>.

Install Web SDK

npm i @koreai/artemis-web-sdk

The package includes the core AgentSDK constructor, chat and voice clients, React provider/hooks/components, custom elements, rich content renderers, attachment upload, feedback, auth challenge UI, and template utilities.

Quick Start

Vanilla JavaScript

import { AgentSDK } from '@koreai/artemis-web-sdk';

const sdk = new AgentSDK({
  projectId: 'your-project-id',
  apiKey: 'pk_your-public-key',
  endpoint: 'https://agents.kore.ai',
});

await sdk.connect();

// Send a chat message
const chat = sdk.chat();
chat.on('message', (msg) => console.log(msg.content));
await chat.send('Hello, I need help!');

React

import { AgentProvider, useChat, useVoice } from '@koreai/artemis-web-sdk/react';

function App() {
  return (
    <AgentProvider
      projectId="your-project-id"
      apiKey="pk_your-public-key"
      endpoint="https://agents.kore.ai"
    >
      <ChatWidget />
    </AgentProvider>
  );
}

function ChatWidget() {
  const { messages, isTyping, sendMessage, isConnected } = useChat();

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id}>
          <strong>{msg.role}:</strong> {msg.content}
        </div>
      ))}
      {isTyping && <div>Agent is typing...</div>}
      <button onClick={() => sendMessage('Hello!')} disabled={!isConnected}>
        Send
      </button>
    </div>
  );
}

Web Component

<script src="https://agents.kore.ai/sdk/agent-widget.js"></script>

<agent-widget project-id="your-project-id" api-key="pk_your-public-key" mode="chat"></agent-widget>

AgentSDK

The main SDK class. Creates and manages connections, chat clients, and voice clients.

Constructor

new AgentSDK(config: SDKConfig)

SDKConfig

Property	Type	Required	Default	Description
`projectId`	string	Yes	—	Project ID to connect to
`apiKey`	string	Yes	—	Public API key (starts with `pk_`)
`endpoint`	string	No	Same origin	Platform base URL
`debug`	boolean	No	`false`	Enable debug logging to console

Methods

Method	Returns	Description
`connect()`	`Promise<void>`	Establish WebSocket connection to the platform
`disconnect()`	`void`	Close the connection and clean up resources
`chat()`	`ChatClient`	Get the chat client instance (created on first call)
`voice()`	`VoiceClient`	Get the voice client instance (created on first call)
`isConnected()`	`boolean`	Check if the SDK is connected
`getSessionId()`	`string	null`	Get the current session ID

Static Methods

Method	Returns	Description
`AgentSDK.init(config)`	`AgentSDK`	Create and store an SDK instance globally (for web components)

Events

Event	Payload	Description
`connected`	`void`	WebSocket connection established
`disconnected`	`void`	WebSocket connection closed
`error`	`{ error: Error }`	Connection or runtime error
`sessionStart`	`{ sessionId: string }`	New session started
`sessionEnd`	`void`	Session ended

sdk.on('connected', () => {
  console.log('Connected to platform');
});

sdk.on('error', ({ error }) => {
  console.error('SDK error:', error.message);
});

sdk.on('sessionStart', ({ sessionId }) => {
  console.log('Session started:', sessionId);
});

ChatClient

Handles text messaging with streaming support. Obtained via sdk.chat().

Methods

Method	Returns	Description
`send(text, options?)`	`Promise<string>`	Send a message. Returns the message ID
`uploadAttachment(file)`	`Promise<string>`	Upload a file attachment. Returns the attachment ID
`getMessages()`	`Message[]`	Get all messages in the conversation
`getIsTyping()`	`boolean`	Check if the agent is currently responding
`clearMessages()`	`void`	Clear the local message history

send() Options

interface SendMessageOptions {
  /** Pre-uploaded attachment IDs to include with the message */
  attachmentIds?: string[];
  /** Optional per-message metadata for the current turn only */
  metadata?: Record<string, unknown>;
}

Example: send with attachments

const chat = sdk.chat();

// Upload a file first
const attachmentId = await chat.uploadAttachment(fileInput.files[0]);

// Send message with attachment
await chat.send('Please analyze this document', {
  attachmentIds: [attachmentId],
});

Example: send with per-message metadata

await chat.send('Look up this account', {
  metadata: {
    accountId: 'acct_123',
    context: { tier: 'gold' },
  },
});

Per-message metadata is validated server-side and is available only for that turn. Use session.messageMetadata as the canonical prompt/template path. message_metadata remains available as the tool-context alias for context_access.read.

Events

Event	Payload	Description
`message`	`Message`	New message received (user or assistant)
`messageChunk`	`{ messageId: string, chunk: string }`	Streaming text chunk from assistant
`typing`	`{ isTyping: boolean }`	Agent typing indicator changed
`messageSent`	`{ messageId: string }`	User message was sent
`attachmentUploaded`	`{ attachmentId: string, filename: string }`	File upload completed
`attachmentError`	`{ filename: string, error: string }`	File upload failed
`error`	`{ error: Error }`	Chat error

const chat = sdk.chat();

chat.on('message', (msg) => {
  if (msg.role === 'assistant') {
    console.log('Agent:', msg.content);
    if (msg.richContent?.markdown) {
      renderMarkdown(msg.richContent.markdown);
    }
    if (msg.actions) {
      renderActions(msg.actions);
    }
  }
});

chat.on('messageChunk', ({ messageId, chunk }) => {
  appendToMessage(messageId, chunk);
});

chat.on('typing', ({ isTyping }) => {
  showTypingIndicator(isTyping);
});

Message Type

interface Message {
  id: string;
  role: 'user' | 'assistant' | 'system';
  content: string;
  timestamp: Date;
  metadata?: Record<string, unknown>;
  richContent?: RichContent;
  actions?: ActionSet;
  attachments?: AttachmentRef[];
}

RichContent Type

Multi-format content variants delivered alongside the plain text response:

interface RichContent {
  markdown?: string;
  adaptive_card?: string;
  html?: string;
  slack?: string;
  ag_ui?: string;
  whatsapp?: string;
}

ActionSet Type

Interactive action elements the agent sends for user input:

interface ActionSet {
  elements: ActionElement[];
  submit_label?: string;
  submit_id?: string;
}

interface ActionElement {
  id: string;
  type: 'button' | 'select' | 'input';
  label: string;
  value?: string;
  description?: string;
  options?: Array<{ id: string; label: string; description?: string }>;
  input_type?: 'text' | 'number' | 'date' | 'time' | 'email';
  placeholder?: string;
  required?: boolean;
}

AttachmentRef Type

interface AttachmentRef {
  id: string;
  filename: string;
  mimeType: string;
  sizeBytes: number;
  category: 'image' | 'document' | 'audio' | 'video';
}

VoiceClient

Handles voice interactions via WebSocket audio pipeline with optional WebRTC. Obtained via sdk.voice(). The voice client supports two modes:

Pipeline mode: Client-side VAD (Voice Activity Detection) captures PCM16 audio, sends it via WebSocket for server-side STT/LLM/TTS processing, and plays back MP3 audio responses.
Realtime mode: Native audio I/O via realtime LLM providers with PCM16 streaming.

Methods

Method	Returns	Description
`start()`	`Promise<void>`	Start voice interaction (requests microphone permission)
`stop()`	`void`	Stop voice interaction and release audio resources
`toggleMute()`	`boolean`	Toggle microphone mute. Returns the new mute state
`getState()`	`VoiceState`	Get the current voice state
`getInfo()`	`VoiceInfo`	Get full voice status information

Static Methods

Method	Returns	Description
`VoiceClient.isSupported()`	`boolean`	Check if the browser supports voice features

Voice States

type VoiceState =
  | 'idle' // Not active
  | 'connecting' // Establishing connection
  | 'ready' // Connected, waiting for speech
  | 'listening' // Detecting speech
  | 'processing' // Processing user speech
  | 'speaking' // Playing agent response
  | 'error'; // Error state

VoiceInfo Type

interface VoiceInfo {
  state: VoiceState;
  isMuted: boolean;
  currentTranscript: string;
  hasMicPermission?: boolean;
}

VoiceClientOptions

interface VoiceClientOptions {
  enableBargeIn?: boolean; // Default: true
  sampleRate?: number; // Default: 16000
  deviceId?: string; // Specific audio input device
  vadConfig?: {
    positiveSpeechThreshold?: number;
    negativeSpeechThreshold?: number;
    redemptionMs?: number;
    minSpeechMs?: number;
    preSpeechPadMs?: number;
  };
}

Events

Event	Payload	Description
`stateChange`	`{ state: VoiceState, previousState: VoiceState }`	Voice state changed
`transcription`	`{ text: string, isFinal: boolean, confidence?: number }`	Speech-to-text result
`transcriptionFinal`	`{ text: string, confidence: number }`	Final transcription
`responseStart`	`{ messageId: string }`	Agent started speaking
`responseChunk`	`{ messageId: string, text: string }`	Agent speech text chunk
`responseEnd`	`{ messageId: string, text: string }`	Agent finished speaking
`speaking`	`{ isSpeaking: boolean }`	Audio playback state changed
`volumeChange`	`{ level: number }`	Microphone volume level (0-1)
`ready`	`void`	Voice client is ready
`error`	`{ error: Error }`	Voice error
`micPermissionDenied`	`void`	Microphone permission denied
`bargeIn`	`void`	User interrupted agent speech
`vadAvailable`	`{ available: boolean }`	VAD availability changed

Voice interaction example

const voice = sdk.voice();

voice.on('stateChange', ({ state }) => {
  updateUI(state);
});

voice.on('transcription', ({ text, isFinal }) => {
  updateTranscript(text, isFinal);
});

voice.on('responseEnd', ({ text }) => {
  console.log('Agent said:', text);
});

voice.on('error', ({ error }) => {
  console.error('Voice error:', error.message);
});

// Start listening
await voice.start();

// Mute/unmute
const isMuted = voice.toggleMute();

React Hooks

The React integration provides a context provider and hooks for state management.

AgentProvider

Wrap your application with AgentProvider to initialize the SDK:

import { AgentProvider } from '@koreai/artemis-web-sdk/react';

<AgentProvider
  projectId="your-project-id"
  apiKey="pk_your-public-key"
  endpoint="https://agents.kore.ai"
  debug={false}
>
  {children}
</AgentProvider>;

useAgent()

Access the full SDK context:

const {
  sdk, // AgentSDK | null
  isConnected, // boolean
  sessionId, // string | null
  error, // Error | null
  chat, // ChatClient | null
  messages, // Message[]
  isTyping, // boolean
  sendMessage, // (text: string) => Promise<void>
  voice, // VoiceClient | null
  voiceState, // VoiceState
  startVoice, // () => Promise<void>
  stopVoice, // () => void
  toggleMute, // () => boolean
  isMuted, // boolean
} = useAgent();

useChat()

Access chat-specific state:

const {
  messages, // Message[]
  isTyping, // boolean
  sendMessage, // (text: string) => Promise<void>
  isConnected, // boolean
} = useChat();

Example

import { useChat } from '@koreai/artemis-web-sdk/react';

function ChatView() {
  const { messages, isTyping, sendMessage, isConnected } = useChat();

  const handleSend = async (text: string) => {
    await sendMessage(text);
  };

  return (
    <div>
      {messages.map((msg) => (
        <div key={msg.id} className={msg.role}>
          {msg.content}
        </div>
      ))}
      {isTyping && <div>Agent is typing...</div>}
    </div>
  );
}

useVoice()

Access voice-specific state:

const {
  voiceState, // VoiceState
  startVoice, // () => Promise<void>
  stopVoice, // () => void
  toggleMute, // () => boolean
  isMuted, // boolean
  isConnected, // boolean
} = useVoice();

Example

import { useVoice } from '@koreai/artemis-web-sdk/react';

function VoiceControls() {
  const { voiceState, startVoice, stopVoice, toggleMute, isMuted } = useVoice();

  return (
    <div>
      <p>Status: {voiceState}</p>
      <button onClick={startVoice} disabled={voiceState !== 'idle'}>
        Start
      </button>
      <button onClick={stopVoice} disabled={voiceState === 'idle'}>
        Stop
      </button>
      <button onClick={toggleMute}>{isMuted ? 'Unmute' : 'Mute'}</button>
    </div>
  );
}

File Uploads

Upload files for agent processing:

const chat = sdk.chat();

// Upload a file
const file = new File(['content'], 'document.pdf', {
  type: 'application/pdf',
});
const attachmentId = await chat.uploadAttachment(file);

// Send message with attachment
await chat.send('Please analyze this document', {
  attachmentIds: [attachmentId],
});

Supported File Types

Images: jpeg, png, gif, webp, svg
Documents: pdf, docx, xlsx, pptx, txt, csv
Audio: mp3, wav, ogg, m4a
Video: mp4, webm

Upload Limits

Maximum file size: 25 MB per file
Maximum files per message: 10

Styling and Theming

Customize the web component appearance:

interface WidgetTheme {
  primaryColor?: string;
  textColor?: string;
  backgroundColor?: string;
  borderRadius?: number;
  fontFamily?: string;
  darkMode?: boolean;
}

Configure via attributes:

<agent-widget
  project-id="your-project-id"
  api-key="pk_your-public-key"
  mode="unified"
  position="bottom-right"
></agent-widget>

bottom-right (default)
bottom-left
top-right
top-left

chat — Text-only chat interface
voice — Voice-only interface
unified — Combined chat and voice interface

TypedEventEmitter

All SDK classes extend TypedEventEmitter for type-safe event handling:

// Subscribe to events
sdk.on('connected', callback);

// Subscribe once
sdk.once('connected', callback);

// Unsubscribe
sdk.off('connected', callback);

// Remove all listeners
sdk.removeAllListeners();

WebSocket Message Types

The SDK communicates with the platform over WebSocket. These types are used internally but documented for advanced use cases.

Server Message Types

Type	Description
`response_start`	Agent started generating a response
`response_chunk`	Incremental text from the agent
`response_end`	Agent finished responding (includes `fullText`, `richContent`, `actions`)
`error`	Error occurred during processing
`session_start`	New session established
`session_end`	Session ended

API Key Management

Public API keys (pk_ prefix) are scoped to a project and provide limited permissions for SDK usage. They are safe to expose in client-side code.

Creating an API Key

Go to Project > Settings > API Keys.
Click Create API key.
Set the allowed origins (for CORS protection).
Copy the key — it is displayed only once.

Origin Restrictions

Configure allowed origins to prevent unauthorized use of your API key:

{
  "allowedOrigins": ["https://your-app.example.com", "https://staging.your-app.example.com"]
}

The runtime validates the Origin header on every SDK request and rejects requests from unlisted origins.

Authentication and Verified Identity

Public API keys cover anonymous and low-assurance chat. For verified user identity, sensitive-data flows, and customer-issued tokens, configure SDK authentication end to end across Studio, the browser SDK, the customer backend, and the runtime. Learn more: SDK end-to-end auth setup guide.

​Install Web SDK

​Quick Start

​Vanilla JavaScript

​React

​Web Component

​AgentSDK

​Constructor

​Methods

​Static Methods

​Events

​ChatClient

​Methods

​send() Options

​Events

​Message Type

​RichContent Type

​ActionSet Type

​AttachmentRef Type

​VoiceClient

​Methods

​Static Methods

​Voice States

​VoiceInfo Type

​VoiceClientOptions

​Events

​React Hooks

​AgentProvider

​useAgent()

​useChat()

​useVoice()

​File Uploads

​Supported File Types

​Upload Limits

​Styling and Theming

​Widget Theming

​Widget Positions

​Widget Modes

​TypedEventEmitter

​WebSocket Message Types

​Server Message Types

​API Key Management

​Creating an API Key

​Origin Restrictions

​Authentication and Verified Identity

Install Web SDK

Quick Start

Vanilla JavaScript

React

Web Component

AgentSDK

Constructor

Methods

Static Methods

Events

ChatClient

Methods

send() Options

Events

Message Type

RichContent Type

ActionSet Type

AttachmentRef Type

VoiceClient

Methods

Static Methods

Voice States

VoiceInfo Type

VoiceClientOptions

Events

React Hooks

AgentProvider

useAgent()

useChat()

useVoice()

File Uploads

Supported File Types

Upload Limits

Styling and Theming

Widget Theming

Widget Positions

Widget Modes

TypedEventEmitter

WebSocket Message Types

Server Message Types

API Key Management

Creating an API Key

Origin Restrictions

Authentication and Verified Identity