Kapa Agent Framework — Core

Build in-product AI agents powered by your knowledge base — with custom tools, streaming, and human-in-the-loop approval.

What is Kapa Agent Framework?

The Kapa Agent Framework lets you embed an AI agent in your product that can answer questions from your knowledge base and take actions through custom tools. The agent runs a multi-turn loop: it streams responses, calls tools (with optional user approval), and continues until it has a final answer.

@kapaai/agent-core is the headless core — pure TypeScript, no UI framework dependencies. It works in browsers, Node.js, and edge runtimes.

Installation

npm install @kapaai/agent-core

For type-safe tool definitions with Zod (optional):

npm install zod zod-to-json-schema

Quick Start

import { Agent, createToolHelper } from "@kapaai/agent-core";
import { z } from "zod";

const tool = createToolHelper<{ api: ApiClient }>();

const agent = new Agent({
  projectId: "your-project-id",
  integrationId: "your-integration-id",
  getSessionToken: async () => {
    const res = await fetch("/api/session", { method: "POST" });
    return res.json();
  },
  tools: [
    tool({
      name: "search_orders",
      description: "Search customer orders",
      parameters: z.object({ query: z.string() }),
      execute: async ({ query }, ctx) => ctx.api.searchOrders(query),
    }),
  ],
  context: { api: myApiClient },
  onMessagesChange: (messages) => renderUI(messages),
  onStreamingChange: (streaming) => toggleSpinner(streaming),
});

await agent.sendMessage("What are my recent orders?");

Features

• Streaming — Token-by-token response streaming with onMessagesChange callbacks
• Custom tools — Define tools with Zod schemas for type-safe argument inference
• Human-in-the-loop — Tools can require user approval before execution
• Session management — Automatic token refresh and 401 retry
• Analytics events — Optional onEvent callback for monitoring agent interactions
• Framework-agnostic — Pure TypeScript, works with any UI framework or none at all

Authentication

Session tokens are created server-side using your Kapa API key, then passed to the agent via getSessionToken. The API key never reaches the browser.

Browser → Your backend → POST /agent/v1/projects/{id}/agent/sessions/ (with API key)
Browser ← session token
Browser → Kapa API → POST /agent/v1/projects/{id}/agent/chat/ (with session token)

Resources

• Documentation — Full setup guide, API reference, and integration patterns
• Examples — Runnable examples (vanilla JS, React, Next.js)
• @kapaai/agent-react — React components and hooks built on top of this package