@ola-krutrim/ai-sdk

Drop-in React components for Agent Bazaar chat and voice. Pass your agent credentials — the SDK handles sessions, streaming, branding, rich content, and voice.

npm install @ola-krutrim/ai-sdk react react-dom

import { ChatWidget, ChatButton } from "@ola-krutrim/ai-sdk/react";

You need an agent name and agent key from the Agent Bazaar console.

Which component should I use?

| Your goal | Component | Example | |-----------|-----------|---------| | Chat embedded in your page (sidebar, section, modal body) | ChatWidget | <ChatWidget agentName="…" agentKey="…" /> | | Floating launcher on the screen (bubble or bottom bar) | ChatButton | <ChatButton agentName="…" agentKey="…" /> |

Rule of thumb: use ChatWidget when you already have a place for chat in your layout. Use ChatButton when you want a fixed launcher that opens a panel.

How ChatButton and ChatWidget work together

ChatButton creates an inner ChatWidget and shares one useAgentChat call — a single GET /details for both the launcher and the panel.

ChatButton
├── launcher          ← circular button OR bottom header bar
└── panel
    └── ChatWidget    ← created internally; shares chat state

Recommended — chatWidgetProps

Put widget options (credentials, size, voice, theme) in chatWidgetProps. Launcher options stay on ChatButton.

<ChatButton
  type="circular"
  launcherPosition="bottom_right"
  panelPlacement="top_right"
  buttonSize="medium"
  chatWidgetProps={{
    agentName: "my_agent",
    agentKey: import.meta.env.VITE_AGENT_KEY,
    size: "medium",
    voiceEnable: true,
    accentColor: "#2563eb",
  }}
/>

Shorthand — flat props on ChatButton

Still supported: pass ChatWidget props directly on ChatButton (same single API call).

<ChatButton
  agentName="my_agent"
  agentKey={import.meta.env.VITE_AGENT_KEY}
  size="medium"
  type="circular"
  launcherPosition="bottom_right"
/>

Shared client

const client = new AgentBazaar({
  agentName: import.meta.env.VITE_AGENT_NAME,
  agentKey: import.meta.env.VITE_AGENT_KEY,
});

<ChatButton
  type="header"
  headerPosition="bottom_right"
  chatWidgetProps={{ client, size: "medium" }}
/>

Inline + floating on the same page

Each component still has its own session (two GET /details — one per component):

const agent = {
  agentName: "my_agent",
  agentKey: import.meta.env.VITE_AGENT_KEY,
};

<>
  <ChatWidget {...agent} size="large" />
  <ChatButton
    type="header"
    headerPosition="bottom_right"
    chatWidgetProps={{ ...agent, size: "medium" }}
  />
</>

ChatWidget — inline chat panel

Use when chat lives inside your page layout.

import { ChatWidget } from "@ola-krutrim/ai-sdk/react";

export function SupportChat() {
  return (
    <ChatWidget
      agentName="my_agent"
      agentKey={import.meta.env.VITE_AGENT_KEY}
      size="medium"
      placeholder="Ask anything…"
    />
  );
}

With theming and voice:

<ChatWidget
  agentName="my_agent"
  agentKey={process.env.NEXT_PUBLIC_AGENT_KEY}
  apiBase="https://your-api-host.com"
  title="Support"
  subtitle="We reply in seconds"
  accentColor="#2563eb"
  size="medium"
  voiceEnable={true}
  defaultMode="chat"
  onSessionId={(id) => console.log("Session:", id)}
/>

Built in automatically:

• Agent logo, colors, title, and description from the API
• Persistent chat session and streaming replies
• Text, images, charts/HTML, and custom widget payloads
• Mic button when voice is enabled on your agent

ChatButton — floating launcher

Use when you want a fixed launcher that opens a chat panel. Pass all ChatWidget props plus launcher options below.

Circular — round floating button

<ChatButton
  agentName="my_agent"
  agentKey={import.meta.env.VITE_AGENT_KEY}
  type="circular"
  launcherPosition="bottom_right"
  panelPlacement="top_right"
  buttonSize="medium"
  size="medium"
/>

Header — bottom bar that expands upward

<ChatButton
  agentName="my_agent"
  agentKey={import.meta.env.VITE_AGENT_KEY}
  type="header"
  headerPosition="bottom_right"
  headerSize="large"
  headerText="medium"
  size="medium"
/>

When type="header", the launcher bar acts as the header and the inner ChatWidget hides its own header (hideHeader is set automatically).

Open on load, hide without ending session

<ChatButton
  agentName="my_agent"
  agentKey={import.meta.env.VITE_AGENT_KEY}
  type="header"
  headerPosition="bottom_left"
  defaultOpen={true}
  minimizeKill={false}
  voiceEnable={true}
/>

| Prop | What it does | |------|----------------| | First click | Session (and voice) start only after the user clicks the launcher — even if defaultOpen is true. | | defaultOpen | Panel appears open on load; user still clicks once to start chatting. | | minimizeKill={false} | Close hides the panel; session and voice keep running. | | minimizeKill={true} (default) | Close ends the session (unmounts the inner ChatWidget). |

Props reference

ChatWidget props

| Prop | Type | Description | Default | |------|------|-------------|---------| | Connection | | client | AgentBazaar | Pre-built SDK client (alternative to agentName + agentKey) | — | | agentName | string | Agent identifier from the console | — | | agentKey | string | API key (Bearer token) | — | | apiBase | string | API host | https://krutrim-agent-bazaar-new.kruti.ai | | stream | boolean | Stream replies as they generate | true | | openingMessages | string[] | Greeting lines before user types | From agent | | Layout & look | | size | string | Preset panel dimensions | "medium" | | width | string | Custom width override (e.g. "100%") | From size | | height | string | Custom height override | From size | | className | string | Extra CSS class on root | — | | style | object | Inline styles on root | — | | hideHeader | boolean | Hide the top header bar | false | | showDescription | boolean | Show subtitle in header | true | | disableWhileLoading | boolean | Disable input while loading | true | | headerColor | string | Header background | Agent color | | logoUrl | string | Header logo URL | Agent icon | | title | string | Header title | Business/agent name | | subtitle | string | Header subtitle | Agent description | | accentColor | string | Buttons and user bubbles | Agent color | | backgroundColor | string | Chat background | "#ffffff" | | userBubbleColor | string | User bubble color | Accent color | | agentBubbleColor | string | Agent bubble color | "#f3f4f6" | | textColor | string | Main text color | "#111827" | | borderRadius | string | Corner radius | "12px" | | fontFamily | string | Font stack | System UI | | placeholder | string | Input placeholder | "Type a message…" | | Voice | | voiceEnable | boolean | Force voice on/off | From agent details | | defaultMode | string | Start mode after engagement | "chat" | | voiceButtonPlacement | string | Mic button location | "default" | | voiceUserId | string | User id for voice WebSocket | — | | voiceMetadata | object | Extra voice metadata | — | | voiceWsUrl | string | Override voice WebSocket URL | Auto | | voiceAuth | string | Voice auth mode | "query" | | recorderSampleRate | number | Mic sample rate | SDK default | | playerSampleRate | number | Playback sample rate | SDK default | | Rich content | | renderWidget | function | Custom widget payload renderer | Built-in card | | renderHtml | function | Custom HTML/chart renderer | Built-in iframe | | visualization | object | Built-in iframe options | — | | Callbacks | | onError | function | Chat error handler | — | | onSessionId | function | Called when session id is set | — | | onVoiceError | function | Voice setup error handler | — |

Voice notes

• Voice shows when your agent has embed voice enabled, unless you set voiceEnable.
• Tap mic to start; waveform appears when agent audio is live.
• Tap mic again to hang up, or restart after "Voice terminated".
• For local dev across ports, use voiceAuth="proxy" and proxy /api/v1/voice/embed so your dev server adds the Bearer token.

ChatButton props

Accepts all ChatWidget props above, plus:

| Prop | Type | Description | Default | |------|------|-------------|---------| | type | string | Launcher style | "circular" | | launcherPosition | string | Circular button position on screen | "bottom_right" | | panelPlacement | string | Panel position relative to button (type="circular") | "top_right" | | headerPosition | string | Bottom dock side (type="header") | "bottom_right" | | panelGap | number | Gap (px) between button and panel | 12 | | defaultOpen | boolean | Show panel open on load | false | | minimizeKill | boolean | Close ends session vs. hides panel | true | | buttonSize | string | Circular button size | "medium" | | headerSize | string | Header dock width | "medium" | | headerText | string | Header title/logo scale | "medium" | | zIndex | number | Launcher stacking order | 9999 | | chatWidgetProps | ChatWidgetProps | Inner panel config (preferred over flat widget props) | — |

Placement values: top_left, top_right, top_center, bottom_left, bottom_right, bottom_center, left_center, right_center

ChatWidget size presets:

| Size | Width | Height | |------|-------|--------| | small | 320px | 440px | | medium | 380px | 520px | | large | 440px | 600px | | extralarge | 520px | 680px |

Set width or height explicitly to override the preset (e.g. width="100%").

ChatButton launcher presets:

| Size | Circular button | Header dock width | |------|-----------------|-------------------| | small | 44px | 280px | | medium | 56px | 360px | | large | 72px | 440px | | extralarge | 88px | 520px |

headerText controls logo, title, subtitle, and padding inside the header bar (independent of headerSize).

Environment variables

VITE_AGENT_NAME=my_agent
VITE_AGENT_KEY=your-agent-key
VITE_API_BASE=https://your-api-host.com   # optional

Never expose the agent key in client code unless your deployment model allows it; use a server-side proxy or embed tokens when required.

License

MIT