Quick Start

Five steps to a working AI chat widget in a React app: install the package, wrap your tree with the provider, drop in a chat UI, mount a server route, and verify the round-trip. Total time ~5 minutes assuming you already have a Next.js app and an OpenAI API key. If you don't have an API key, grab one from platform.openai.com first — @tour-kit/ai works with any Vercel AI SDK provider but OpenAI's gpt-4o-mini is the cheapest path to "working".

This guide ships the no-context variant — the assistant has no product knowledge yet. After you confirm the round-trip works, move on to the CAG Guide (small docs) or RAG Guide (large docs) to give the model real product context.

Installation

pnpm add @tour-kit/ai

You also need the AI SDK as a peer dependency:

pnpm add ai @ai-sdk/openai

Client Setup

Wrap your application with AiChatProvider:

import { AiChatProvider } from '@tour-kit/ai'

export function App() {
  return (
    <AiChatProvider
      config={{
        endpoint: '/api/chat',
        tourContext: true,
      }}
    >
      <YourApp />
    </AiChatProvider>
  )
}

Add a Chat Widget

Use the useAiChat hook to build your chat UI:

import { useAiChat } from '@tour-kit/ai'

function ChatWidget() {
  const { messages, sendMessage, status } = useAiChat()

  return (
    <div>
      <div>
        {messages.map((msg) => (
          <div key={msg.id}>
            <strong>{msg.role}:</strong> {msg.content}
          </div>
        ))}
      </div>
      <input
        placeholder="Ask a question..."
        onKeyDown={(e) => {
          if (e.key === 'Enter') {
            sendMessage({ text: e.currentTarget.value })
            e.currentTarget.value = ''
          }
        }}
      />
    </div>
  )
}

Server Setup

Create an API route handler. For Next.js:

// app/api/chat/route.ts
import { createChatRouteHandler } from '@tour-kit/ai/server'
import { openai } from '@ai-sdk/openai'

const { POST } = createChatRouteHandler({
  model: openai('gpt-4o-mini'),
  context: {
    strategy: 'context-stuffing',
    documents: [],
  },
})

export { POST }

Set your API key in .env.local:

OPENAI_API_KEY=sk-...

Verify Your Setup

Render ChatWidget somewhere visible, type a message, and confirm three things:

1. The user message appears in the list immediately (client-side optimistic update).
2. The status transitions through submitted → streaming → ready.
3. An assistant reply streams in token-by-token (not all at once at the end).

If all three work, the round-trip is healthy. The most common failures:

Next Steps

• CAG Guide — give the assistant product knowledge by injecting docs into every prompt (small docs)
• RAG Guide — vector-search retrieval for large documentation sets
• Tour Integration — connect the assistant to live tour state via useTourAssistant
• Components — swap the custom UI for the pre-built <AiChatPanel> + <AiChatToggle> combo