Agent SDK Overview

The Kapa Agent SDK lets you embed an AI agent chat into your application, with orchestration, a streaming chat UI, custom tools, and built-in knowledge base search in a single package. Knowledge base search is built in: out of the box, the agent answers from your own documentation, grounded in the same knowledge sources you've already configured in Kapa, with no retrieval system for you to build.

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, knowledge base search, 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 only need to install @kapaai/agent-react. It includes @kapaai/agent-core as a 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.

Knowledge base search runs server-side as part of this loop. The agent decides when to search your knowledge sources, and Kapa executes the retrieval on its backend, then feeds the results (with their source URLs) back into the conversation. You never call it and never handle the raw documents.

Built-in knowledge base search

Knowledge base search is built into the agent, not something you wire up yourself. Every agent includes a server-side search_knowledge_base tool that retrieves from the knowledge sources you have already configured in your Kapa project (documentation, GitHub repos, API references, and more). It runs on Kapa's production retrieval pipeline, the same hybrid semantic search and reranking behind the Website Widget, and prunes low-relevance results so the agent's context stays lean.

What this gives you:

• No RAG to build. You do not design a retrieval tool, run a vector database, manage embeddings, or tune reranking. The agent is already wired to your indexed knowledge sources.
• Works with zero custom tools. The agent answers product questions from your documentation before you define a single tool. Custom tools are additive: you layer them on top when you want the agent to take actions in your product.
• Grounded, cited answers. Results come back with their source URLs, and the SDK surfaces them as source tiles in the chat so users can verify every claim. Expressing uncertainty when the sources do not cover a question is built in too, the same behavior you get from the widget.
• Runs server-side. Retrieval executes on Kapa's backend, so raw chunks never reach the browser and there is nothing for you to secure, scale, or keep in sync.

You can scope the agent to specific source groups, and customize how the search step is labeled in the chat with builtinToolMeta. See Built-in tools for the full reference.

See our research on knowledge base search in agents for the data behind why this matters.

Quick start

React

npm install @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