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:

tsx

// CopilotKit is imported from the root package, not from the v2 subpackage

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

<Accordions> <Accordion title="Advanced: Using CopilotKitProvider directly"> <Callout type="warn"> `CopilotKitProvider` is a low-level provider intended for advanced use cases. Most applications should use the `<CopilotKit>` component from `@copilotkit/react-core` instead. </Callout>

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

tsx

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

Props

<PropertyReference name="runtimeUrl" type="string"> URL of the CopilotKit runtime endpoint. Lazily forwarded to the core after mount. </PropertyReference> <PropertyReference name="headers" type="Record<string, string>" default="{}"> Request headers forwarded with runtime calls. </PropertyReference> <PropertyReference name="credentials" type="RequestCredentials"> Credentials mode for fetch requests (e.g. `"include"` for HTTP-only cookies in cross-origin requests). </PropertyReference> <PropertyReference name="publicApiKey" type="string"> Copilot Cloud public API key. </PropertyReference> <PropertyReference name="publicLicenseKey" type="string"> Alias for `publicApiKey`. </PropertyReference>

<PropertyReference name="properties" type="Record<string, unknown>" default="{}"

Runtime metadata payload. </PropertyReference>

<PropertyReference name="useSingleEndpoint" type="boolean"> When enabled, all runtime calls use a single endpoint. </PropertyReference>

<PropertyReference name="agents__unsafe_dev_only" type="Record<string, AbstractAgent>"

Preinstantiated agents for development/testing. Not intended for production use. </PropertyReference>

<PropertyReference name="renderToolCalls" type="ReactToolCallRenderer[]"> Static set of tool call renderers. The array should be stable across renders. </PropertyReference>

<PropertyReference name="renderActivityMessages" type="ReactActivityMessageRenderer[]"

Static set of activity message renderers. </PropertyReference>

<PropertyReference name="renderCustomMessages" type="ReactCustomMessageRenderer[]"

Static set of custom message renderers. </PropertyReference>

<PropertyReference name="frontendTools" type="ReactFrontendTool[]"> Static tool handlers defined at the provider level. The array should be stable across renders. </PropertyReference> <PropertyReference name="humanInTheLoop" type="ReactHumanInTheLoop[]"> Declarative human-in-the-loop tool definitions. Each becomes both a tool handler and a tool call renderer. </PropertyReference> <PropertyReference name="showDevConsole" type='boolean | "auto"'> Show the CopilotKit developer console for debugging. </PropertyReference> <PropertyReference name="onError" type="(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.

tsx

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

</PropertyReference> </Accordion> </Accordions>

Styling

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

tsx

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

<Callout type="info"> Looking for tool rendering hooks? Start with [`useComponent`](/reference/hooks/useComponent), [`useRenderTool`](/reference/hooks/useRenderTool), and [`useDefaultRenderTool`](/reference/hooks/useDefaultRenderTool). </Callout> <Cards> <Card title="Hooks" description="React hooks for agents, tools, context, and chat configuration." href="/reference/hooks/useAgent" icon={<LinkIcon />} /> <Card title="UI Components" description="Pre-built chat components: CopilotChat, CopilotPopup, CopilotSidebar, and more." href="/reference/components/CopilotChat" icon={<LinkIcon />} /> </Cards>