Kapa Agent SDK — Examples

Example applications showing how to build in-product AI agents with the Kapa Agent Framework.

Each example demonstrates custom tool definitions with Zod schemas, human-in-the-loop approval flow, streaming responses, session-based authentication, and conversation history. The examples use mock tools simulating a project management SaaS to showcase all SDK features without requiring a real backend.

Examples

Example	Description
react	React + Vite app using AgentProvider and AgentChat components with custom tool render props for inline UI
nextjs	Next.js App Router app with server-side session creation via Route Handler and the full chat UI
react-headless	React + Vite app using only the useAgentChat() hook with a fully custom UI — no SDK components
vanilla-js	Plain JavaScript app using the Agent class directly with DOM rendering via marked + DOMPurify
server	Express server that proxies session token creation (used by react, react-headless, and vanilla-js)

Prerequisites

• Node.js 18+
• A Kapa API key, project ID, and integration ID. See Getting Started

All examples use Zod schemas for tool definitions and include zod and zod-to-json-schema as dependencies. Both are installed automatically with npm install.

Quick Start

1. Start the session server (not needed for the Next.js example, which has its own API route):

   cd server
   cp .env.example .env.local   # fill in your API key and project ID
   npm install
   npm run dev                  # http://localhost:3456

2. Run an example:

   cd react                     # or nextjs, react-headless, vanilla-js
   cp .env.example .env.local   # fill in your project ID, integration ID, and model
   npm install
   npm run dev

Authentication

Session tokens are created server-side using your Kapa API key, then passed to the frontend. 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)

The server/ directory and the Next.js /api/session route both implement this pattern. In production, replace these with your own backend endpoint.

To enable conversation history, the session endpoint also sets external_owner_id to a stable identifier for the current user. This must come from your backend, not the frontend. The examples use a hardcoded "demo-user" value. See the authentication guide for details.

Packages

• @kapaai/agent-react — React hooks and UI components. Includes @kapaai/agent-core as a dependency, so React examples only install this package.
• @kapaai/agent-core — Headless core (Agent class, streaming, tools, session management). Used directly only by the vanilla-js example.

License

MIT