Agent SDK Overview

The Kapa Agent SDK lets you embed an AI agent chat into your application, with orchestration, streaming chat UI, knowledge base search, and custom tools in a single package.

The SDK is frontend-first: orchestration, tool execution, and the chat UI all run in your application code, so there is no agent backend for you to deploy or operate. Because tool calls happen in your frontend too, they can use the same APIs, cookies, and permission checks you already apply to normal user actions, with no separate authorization layer to build for the agent.

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

Server-side

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.

Frontend

2. Streaming. The SDK calls the Kapa API with the session token, streaming agent responses directly back to the browser.
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, then sends the result back to the Kapa API.
4. Loop. The agent 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