AI Chat Module Recipe

The AI Chat module puts an assistant in your app. It talks to an agent you create in Chocolate Factory (its model, system prompt, knowledge base and tools are configured there) and streams the agent’s answers into a chat.

The module gives you two layouts:

• AiChatPanel — a panel docked to the right edge at full height. On a wide screen the page makes room for it, so an answer sits beside the screen it explains; on a narrower one it overlays the page; on a phone it fills the screen. Open it from an Ask AI button in your header, or with ⌘ I on macOS and Ctrl I elsewhere.
• AiChatWidget — a launcher bubble in a bottom corner that opens a chat window above it, for customer-facing apps.

Both show the same chat: streaming Markdown answers (code blocks with a copy button, tables, links), one working word while the agent searches or thinks, Stop and Try again, Copy answer, starter questions, a recent-chats list, and images: attach them with the paper clip, paste them, drop them, or take a screenshot of the page (drag over the part to show, then draw on it).

The pieces

Choose a backend

The chat reaches the agent one of two ways. The choice is about where the Chocolate Factory key lives and whether answers can stream.

Amplify Hosting runs a Next.js API route as a Lambda that buffers its whole response, so a streamed answer can’t pass through your own route there. The browser-direct backend calls Chocolate Factory itself, which is why it streams everywhere — and why the browser needs the key.

Install

buildpad add ai-chat-routes

buildpad add ai-chat-proxy-routes

buildpad add ai-chat

CHOCOLATE_FACTORY_BASE_URL=https://app.chocolatefactory.ai
CHOCOLATE_FACTORY_API_KEY=cf_…
CHOCOLATE_FACTORY_AGENT_ID=…
# Server proxy only: 32+ random characters that sign conversation tokens
AI_CHAT_SECRET=…

Mount it

'use client';
 
import { AiChatPanel, chocolateFactoryBackend, useChocolateFactoryConfig } from '@/components/ui/ai-chat';
 
export function Assistant({ userId }: { userId: string }) {
  const config = useChocolateFactoryConfig(); // GET /api/ai-chat/config
  if (!config) return null; // not configured: no chat
  return (
    <AiChatPanel
      backend={chocolateFactoryBackend(config)}
      title="Ask Acme"
      storageKey={userId}
      suggestions={['How do I invite a teammate?', 'Where do I change my plan?']}
    />
  );
}

<AiChatProvider>
  <header>… <AiChatButton /> …</header>
  <main style={{ marginInlineEnd: 'var(--bp-ai-chat-offset, 0)', transition: 'margin 200ms ease' }}>
    {children}
  </main>
  <Assistant userId={user.id} />
</AiChatProvider>

<AiChatWidget backend={chocolateFactoryBackend(config)} title="Acme Support" greeting="Hi! How can we help today?" />

<AiChatPanel backend={routeBackend()} title="Ask Acme" storageKey={userId} />

Tell the agent where the user is

vars are sent with every message as Chocolate Factory template variables, so the agent’s system prompt can use them ({{page}}, {{user_name}}, …). Pair them with an AiChatContextChip in the context slot, so the user sees what is shared and can stop sharing:

const [share, setShare] = useState(true);
 
<AiChatPanel
  backend={backend}
  vars={() => (share ? { page: 'Settings › Members', page_path: pathname } : undefined)}
  context={
    share ? (
      <AiChatContextChip label="Settings › Members" title={pathname} onRemove={() => setShare(false)} removeLabel="Don't share this page" />
    ) : null
  }
/>

Props

Shared by AiChat, AiChatPanel and AiChatWidget:

AiChatPanel adds opened, onClose, width (420) and dockFrom (75em); without opened/onClose it follows AiChatProvider. AiChatWidget adds opened, onOpenChange, defaultOpened, position (bottom-right or bottom-left), launcherLabel and width (400). AiChatProvider takes hotkey (mod+I; null turns it off) and defaultOpened.

Strings and theme

Every string comes from the chat namespace of the shared dictionary, in English and Bahasa Indonesia; override them app-wide with BuildpadI18nProvider, or per instance with translations. The styles are plain CSS (bp-ai-chat-* classes) drawn with Mantine variables and the --ds-* design tokens, so the chat follows your theme and colour scheme. --bp-ai-chat-width and --bp-ai-chat-z-index (180, below Mantine modals) can be overridden.