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-core @kapaai/agent-react

yarn

yarn add @kapaai/agent-core @kapaai/agent-react

pnpm

pnpm add @kapaai/agent-core @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"
    >
      <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.

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.