API Reference

The v2 React API (@copilotkit/react-core/v2) is the next-generation interface for building copilot-powered applications. It provides a streamlined set of hooks and components built on top of the AG-UI agent protocol.

Provider Setup

The v2 API uses the <CopilotKit> provider. Wrap your application with it to configure the runtime connection:

import { CopilotKit } from "@copilotkit/react-core/v2";

function App() {
  return (
    <CopilotKit runtimeUrl="/api/copilotkit">
      <YourApp />
    </CopilotKit>
  );
}

Advanced: Using CopilotKit directly

CopilotKit is a low-level provider intended for advanced use cases. Most applications should use the <CopilotKit> component from @copilotkit/react-core/v2 instead.

If you need direct control over the v2 provider (e.g. for custom integrations), import CopilotKit from @copilotkit/react-core/v2:

import { CopilotKit } from "@copilotkit/react-core/v2";

<CopilotKit runtimeUrl="/api/copilotkit">
  <App />
</CopilotKit>

Props

runtimeUrlstring

URL of the CopilotKit runtime endpoint. Lazily forwarded to the core after mount.

headersRecord<string, string>

Default: "{}"

Request headers forwarded with runtime calls.

credentialsRequestCredentials

Credentials mode for fetch requests (e.g. "include" for HTTP-only cookies in cross-origin requests).

publicApiKeystring

Copilot Cloud public API key.

publicLicenseKeystring

Alias for publicApiKey.

propertiesRecord<string, unknown>

Default: "{}"

Runtime metadata payload.

useSingleEndpointboolean

When enabled, all runtime calls use a single endpoint.

agents__unsafe_dev_onlyRecord<string, AbstractAgent>

Preinstantiated agents for development/testing. Not intended for production use.

renderToolCallsReactToolCallRenderer[]

Static set of tool call renderers. The array should be stable across renders.

renderActivityMessagesReactActivityMessageRenderer[]

Static set of activity message renderers.

renderCustomMessagesReactCustomMessageRenderer[]

Static set of custom message renderers.

frontendToolsReactFrontendTool[]

Static tool handlers defined at the provider level. The array should be stable across renders.

humanInTheLoopReactHumanInTheLoop[]

Declarative human-in-the-loop tool definitions. Each becomes both a tool handler and a tool call renderer.

showDevConsoleboolean | "auto"

Show the CopilotKit developer console for debugging.

onError(event: { error: Error; code: CopilotKitCoreErrorCode; context: Record<string, any> }) => void | Promise<void>

Error handler called when CopilotKit encounters an error. Fires for all error types: runtime connection failures, agent errors, and tool errors.

Unlike the v1 onError, this does not require a publicApiKey — error handling works with any configuration.

<CopilotKit
  runtimeUrl="/api/copilotkit"
  onError={(event) => {
    console.error(`[${event.code}]`, event.error.message, event.context);
  }}
>
  <App />
</CopilotKit>

Styling

When using v2 UI components, import the stylesheet once at your app boundary:

import "@copilotkit/react-core/v2/styles.css";

API Reference

Looking for tool rendering hooks? Start with useComponent, useRenderTool, and useDefaultRenderTool.

Hooks

React hooks for agents, tools, context, and chat configuration.

UI Components

Pre-built chat components: CopilotChat, CopilotPopup, CopilotSidebar, and more.