AgentProvider

AgentProvider is the root component for the Agent SDK. It sets up the chat engine, theming, and provides context to all child components.

Keep AgentProvider mounted

AgentProvider holds all conversation state: messages, streaming status, session tokens, and tool approval state. Mount it high in your component tree and keep it mounted for the lifetime of your app. Unmounting the provider resets all state.

To show or hide the chat UI, toggle AgentPanel's open prop or conditionally render AgentChat. Both can be mounted and unmounted freely without losing conversation data.

Usage

import { AgentProvider, AgentChat } from '@kapaai/agent-react';

<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"
  tools={myTools}
  context={myContext}
  builtinToolMeta={{
    search_knowledge_base: { displayName: 'Search Knowledge Base' },
  }}
  theme={{ accentColor: '#2563eb', colorScheme: 'dark' }}
>
  <AgentChat branding={{ title: 'AI Assistant' }} />
</AgentProvider>

Props

Prop	Type	Required	Description
getSessionToken	() => Promise<...>	Yes	Async function that returns a session token. Accepts the raw Kapa API response directly. Called lazily on first message. See Authentication.
projectId	string	Yes	Your Kapa project ID.
integrationId	string	Yes	Your Kapa integration ID.
model	string	Yes	Agent model version (e.g. kapa-agent-1.0). See Models.
tools	AgentTool<TContext>[]	No	Client-side tool definitions. Defaults to []. See Custom tools.
context	TContext	No	Context object passed to every tool's execute function. Defaults to {}.
builtinToolMeta	Record<string, ToolDisplayMeta>	No	Display metadata for server-side built-in tools (e.g. search_knowledge_base).
customInstructions	string	No	Additional system prompt instructions for the agent.
user	EndUserInfo	No	End user metadata (email, name) for analytics.
sourceGroupIdsInclude	string[]	No	Array of source group IDs to limit the agent's knowledge base. When set, the agent retrieves from sources in the specified groups and any sources not assigned to a group (global sources). See source groups documentation for details.
onEvent	OnAgentEvent	No	Callback for analytics events (message_sent, response_completed, tool_executed, etc.).
theme	AgentThemeConfig	No	Visual theme. See Theming.
enableHistory	boolean	No	Enable conversation history. When true, shows the history toggle in AgentChat and enables the history methods. Defaults to false.

In addition to the core events, the React SDK also emits panel_opened and panel_closed events when using AgentPanel.

AgentThemeConfig

Field	Type	Default	Description
accentColor	string	'#9333ea'	Primary color (hex). A full palette is generated automatically.
colorScheme	'dark' | 'light' | 'auto'	'dark'	Color scheme. 'auto' follows system preference.
fontFamily	string	'Inter, system-ui, sans-serif'	Font family for the entire chat UI.
fontSize	number	14	Base font size in pixels.
radius	'sharp' | 'soft' | 'round' | 'pill'	'soft'	Border radius style.

See Theming for details and examples.

ToolDisplayMeta

The agent includes a built-in search_knowledge_base tool that searches your project's knowledge base server-side. Since it's not a client tool, you can't define or execute it, but you can customize how it appears in the chat. See Built-in tools for details.

builtinToolMeta={{
  search_knowledge_base: {
    displayName: 'Search Knowledge Base',
    icon: IconSearch,       // optional
    iconColor: '#38bdf8',   // optional
  },
}}