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"
      model="kapa-agent-1.0"
    >
      <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',
  model: 'kapa-agent-1.0',
  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