agent-sdk-integration

Kapa Agent SDK integration

Guide a developer through adding the Kapa Agent SDK to their application, improving an existing integration, or migrating from the Kapa Chat SDK. The Agent SDK embeds an AI agent chat that answers from the customer's knowledge base out of the box (built-in server-side knowledge base search) and can call tools that run in the user's browser.

This skill is a collaborative workflow, not a code generator. Propose, explain the trade-offs, and confirm before making changes. The developer knows their product and their users better than you do.

Golden rules

1. Work interactively. At every decision point (which SDK, which tools, approval, history, UI, how the panel opens), present options with a recommendation and a one-line rationale, then let the developer choose. Grouping a few tightly-related quick decisions into one prompt is fine; do not overwhelm with a long chain, and always give concrete defaults.
2. Ground every API detail in the source of truth. The SDK evolves. Do not rely on memory for prop names, tool shapes, or endpoints. Before writing integration code:
   • Ground against the version you will actually ship, and prefer the latest. For a new setup or a migration, install the current release explicitly (npm install @kapaai/agent-react@latest, or the repo's package manager). Do this even when a copy already exists in node_modules: a pre-existing install can be stale and older than the current release, and grounding against it produces outdated code. After installing, read that version's types. For an existing-setup review, ground against the version the repo already ships, and see the Improve section for when to suggest an upgrade.
   • Read the installed package types. Find each package's type entry from its own package.json (the types field, or the types entries under exports). It is commonly dist/index.d.ts, dist/index.d.mts, or dist/index.d.cts, so do not assume a .d.ts extension. Read both @kapaai/agent-react and @kapaai/agent-core.
   • Consult the official docs at https://docs.kapa.ai/dev/agent (fetch them if you have web access). See "Reference links" below.
   • If the installed types disagree with this skill or the docs, trust the installed types for the version you are shipping. This skill's embedded details track the 1.0.0 API.
3. Never invent endpoints, props, or tool APIs. Only wire up endpoints you have actually found in the codebase. Only pass props that exist in the installed types.
4. Never expose the API key to the browser. Session tokens are minted server-side. See references/auth-and-history.md.
5. Keep the tool set small and high-signal. Fewer reliable tools beat a large grab-bag. Start with the essential ones and expand later.
6. Make no destructive changes without buy-in. Show diffs or plans first.