Agent SDK Overview

The Kapa Agent SDK lets you embed an AI agent chat into your application. Unlike traditional chatbots, the agent can execute tools on the client side — running queries, calling APIs, and rendering rich results directly in the user's browser using their own auth context.

Two packages, layered:

Package	Purpose
@kapaai/agent-core	Pure TypeScript — session management, streaming, tool execution, approval flow. Works in any JS environment.
@kapaai/agent-react	React components + hooks. Full chat UI with theming, dark/light mode, and a ready-made slide-in panel.

React consumers install both packages — @kapaai/agent-react depends on @kapaai/agent-core as a peer dependency and re-exports core types for convenience.

How it works

1. Authentication — Your server creates a short-lived session token by calling the Kapa API with your API key. The token is returned to the browser.
2. Streaming — The SDK uses this token to stream agent responses directly from the Kapa API.
3. Tool execution — When the agent requests a tool call, the SDK executes it client-side using your tool definitions and the user's auth context.
4. Loop — Tool results are sent back to the agent, which continues reasoning and may call more tools or return a final answer.

Quick start

React

npm install @kapaai/agent-core @kapaai/agent-react

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

function App() {
  return (
    <AgentProvider
      getSessionToken={async () => {
        const res = await fetch('/api/session', { method: 'POST' });
        return res.json();
      }}
      projectId="your-project-id"
      integrationId="your-integration-id"
    >
      <div style={{ height: 600 }}>
        <AgentChat
          branding={{
            title: 'AI Assistant',
          }}
        />
      </div>
    </AgentProvider>
  );
}

Vanilla JS / Any framework

npm install @kapaai/agent-core

import { Agent } from '@kapaai/agent-core';

const agent = new Agent({
  projectId: 'your-project-id',
  integrationId: 'your-integration-id',
  tools: [],
  context: {},
  getSessionToken: async () => {
    const res = await fetch('/api/session', { method: 'POST' });
    return res.json();
  },
  onMessagesChange: (messages) => {
    // Render messages in your UI
  },
  onStreamingChange: (isStreaming) => {
    // Show/hide loading indicator
  },
});

await agent.sendMessage('How do I get started?');

Choose your path

React

Full chat UI out of the box with theming and dark/light mode.

• Quickstart (React) — Get running in 5 minutes
• Components — AgentProvider, AgentChat, AgentPanel
• Theming — Accent colors, dark/light mode
• Custom tools — Zod schemas, approval flow, custom rendering with JSX
• Headless mode — Use hooks only with your own UI components
• Next.js guide — App Router integration

JavaScript / TypeScript (any framework)

Build your own UI. Works with Vue, Svelte, Angular, vanilla JS, or any other framework.

• Quickstart (JS/TS) — Plain JS chat in 5 minutes
• Agent class — Methods, options, message format
• Building a UI — Rendering messages, tool cards, approval buttons
• Custom tools — Tool definitions and approval flow

Shared guides

• Authentication — Session tokens and server-side proxy setup

Examples

Runnable example apps covering all of the above: github.com/kapa-ai/agent-sdk-examples