Kapa Agent Framework — React

Build in-product AI agents powered by your knowledge base — with a ready-made chat UI, custom tools, theming, and streaming.

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-react provides React components and hooks on top of @kapaai/agent-core. Use the built-in UI for a complete chat experience, or use only the hooks to build a fully custom interface.

Installation

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

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

npm install zod zod-to-json-schema

Quick Start

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

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

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"
      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 }}
      theme={{ accentColor: "#2563eb", colorScheme: "dark" }}
    >
      <div style={{ height: 600 }}>
        <AgentChat
          branding={{
            title: "Support Agent",
            examplePrompts: ["What are my recent orders?"],
          }}
        />
      </div>
    </AgentProvider>
  );
}

Features

• Ready-made chat UI — Full chat panel with messages, tool cards, sources, and streaming out of the box
• Headless mode — Use only useAgentChat() hook to build a completely custom UI
• Custom tools — Define tools with Zod schemas for type-safe argument inference
• Generative UI — Tools can render custom React components per execution state via render prop
• Human-in-the-loop — Tools can require user approval before execution
• Theming — Accent color, dark/light mode, font, border radius — all configurable
• Slide-in panel — AgentPanel component for drawer-style chat
• Analytics events — Optional onEvent callback for monitoring agent interactions
• Session management — Automatic token refresh and 401 retry (via agent-core)

Headless Usage

Use only the hooks to build your own chat interface — no SDK components required:

import { AgentProvider, useAgentChat } from "@kapaai/agent-react";

const ChatUI = () => {
  const {
    messages,
    isStreaming,
    sendMessage,
    approveToolCall,
    rejectToolCall,
  } = useAgentChat();

  // Render your own UI using messages array.
  // Each assistant message has a blocks array with text and tool_calls blocks.
};

Custom Tool Rendering

Tools can provide a render function for custom inline UI based on execution state:

tool({
  name: "get_usage",
  description: "Get API usage for the current billing period",
  parameters: z.object({}),
  execute: async (_args, ctx) => ctx.api.getUsage(),
  render: ({ status, result }) => {
    if (status === "executing") return <p>Loading...</p>;
    if (status === "completed") return <UsageChart data={result} />;
    return null; // fall back to default tool card
  },
});

Tools that need user confirmation before execution:

tool({
  name: "delete_project",
  description: "Delete a project",
  parameters: z.object({ projectId: z.string() }),
  needsApproval: true,
  execute: async ({ projectId }, ctx) => ctx.api.deleteProject(projectId),
});

Theming

<AgentProvider
  theme={{
    accentColor: "#2563eb", // any hex — generates a 10-shade palette
    colorScheme: "dark",    // 'dark' | 'light' | 'auto'
    radius: "soft",         // 'sharp' | 'soft' | 'round' | 'pill'
    fontSize: 14,           // base font size in px
    fontFamily: "Inter, system-ui, sans-serif",
  }}
>

Toggle the color scheme at runtime:

import { useAgentColorScheme } from "@kapaai/agent-react";

const { colorScheme, toggleColorScheme } = useAgentColorScheme();

Slide-in Panel

import { AgentPanel } from "@kapaai/agent-react";

<AgentPanel
  open={isOpen}
  onClose={() => setIsOpen(false)}
  width={480}
  top={60}
  branding={{ title: "Help" }}
/>;

Analytics Events

<AgentProvider
  onEvent={(event) => {
    analytics.track(`agent_${event.type}`, event.data);
  }}
>

Events: message_sent, response_completed, response_error, generation_stopped, tool_executed, tool_approved, tool_denied, conversation_reset, panel_opened, panel_closed.

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 (React, Next.js, headless React, vanilla JS)
• @kapaai/agent-core — Headless core package (peer dependency)