Quickstart (React)

This guide gets you from zero to a working agent chat in your React application.

Prerequisites

• An Agent integration set up in your Kapa dashboard (Integrations → Agent)
• A customer API key (from your Kapa dashboard → API Keys)
• A React application (Vite, Next.js, Create React App, etc.)

1. Install the packages

npm

npm install @kapaai/agent-react

yarn

yarn add @kapaai/agent-react

pnpm

pnpm add @kapaai/agent-react

2. Create a session endpoint

The SDK needs a session token to authenticate with the Kapa API. Create a server-side endpoint that proxies the session creation. This keeps your API key on the server.

Next.js App Router

app/api/session/route.ts

import { NextResponse } from 'next/server';

export async function POST() {
  const res = await fetch(
    `https://api.kapa.ai/agent/v1/projects/${process.env.KAPA_PROJECT_ID}/agent/sessions/`,
    {
      method: 'POST',
      headers: { 'X-API-Key': process.env.KAPA_API_KEY! },
    },
  );

  if (!res.ok) {
    return NextResponse.json({ error: 'Session failed' }, { status: res.status });
  }

  return NextResponse.json(await res.json());
}

Express

server.js

app.post('/api/session', async (req, res) => {
  const response = await fetch(
    `https://api.kapa.ai/agent/v1/projects/${process.env.KAPA_PROJECT_ID}/agent/sessions/`,
    {
      method: 'POST',
      headers: { 'X-API-Key': process.env.KAPA_API_KEY },
    },
  );

  if (!response.ok) {
    return res.status(response.status).json({ error: 'Session failed' });
  }

  res.json(await response.json());
});

warning

Never expose your API key to the browser. Always create session tokens server-side.

3. Add the agent chat

App.tsx

import { AgentProvider, AgentChat } from '@kapaai/agent-react';

function App() {
  return (
    <AgentProvider
      getSessionToken={async () => {
        const res = await fetch('/api/session', { method: 'POST' });
        if (!res.ok) throw new Error('Session failed');
        return res.json();
      }}
      projectId="your-project-id"
      integrationId="your-integration-id"
      model="kapa-agent-1.0"
    >
      <div style={{ height: '100vh' }}>
        <AgentChat
          branding={{
            title: 'AI Assistant',
            subtitle: 'How can I help?',
            examplePrompts: ['How do I get started?', 'What are the main features?'],
          }}
        />
      </div>
    </AgentProvider>
  );
}

That's it. You have a working agent chat. The SDK handles theming, streaming, and the full chat UI automatically.

Knowledge base search works out of the box

No tools are configured yet, and none are required. The agent already answers questions from your Kapa knowledge sources through built-in, server-side knowledge base search, complete with cited sources shown in the chat. Custom tools are layered on top when you want the agent to take actions in your product. See Built-in tools.

Next steps

• Add custom tools. Let the agent call functions in the user's browser
• Customize the theme. Change the accent color and enable light mode
• Use the slide-in panel. Add a drawer that slides in from the right
• Server-side built-in tools. Configure display names for Kapa's built-in tools

For a complete runnable example with custom tools, approval flow, and render props, see the React example in the examples repo.