# CopilotKit

> The CopilotKit provider component, wrapping your application.

<Callout type="info" title="This is the v1 provider, re-exported for back-compat">
  `<CopilotKit>` is the v1 provider. It is re-exported from
  `@copilotkit/react-core/v2` so that a v1 application keeps working after the
  import path changes, and it renders `<CopilotKitProvider>` internally. **The
  v2 provider is `<CopilotKitProvider>`**. Reach for that one in new v2 code.
</Callout>

`<CopilotKit>` and `<CopilotKitProvider>` use different props to name the agent:

|                | v1 `<CopilotKit>`  | v2 `<CopilotKitProvider>` |
| -------------- | ------------------ | ------------------------- |
| Name the agent | `agent="my_agent"` | `agentId="my_agent"`      |

You can also name the agent per chat with `<CopilotChat agentId="my_agent">`, or
for a subtree with `<CopilotChatConfigurationProvider agentId="my_agent">`. Both
of those override the provider-level default. See [Provider and handler
pairs](/backend/runtime-endpoints#provider-and-handler-pairs).

Both providers treat an omitted `useSingleEndpoint` the same way: the transport
is negotiated from the Runtime info response. Versions before 1.69.0 pinned
`<CopilotKit>` to the single-route transport.

This component will typically wrap your entire application (or a sub-tree of your application where you want to have a copilot). It provides the copilot context to all other components and hooks.

## Example [#example]

To host the runtime yourself, see [Copilot Runtime](/backend/copilot-runtime).

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

<CopilotKit runtimeUrl="<your-runtime-url>">// ... your app ...</CopilotKit>;
```

## Properties [#properties]

<PropertyReference name="publicApiKey" type="string"  >
Your Copilot Cloud API key.

Don't have it yet? Go to https://dashboard.operations.copilotkit.ai and get one for free.

</PropertyReference>

<PropertyReference name="publicLicenseKey" type="string"  >
Your public license key for accessing CopilotKit Intelligence features.

Don't have it yet? Go to https://dashboard.operations.copilotkit.ai and get one for free.

</PropertyReference>

<PropertyReference name="licenseToken" type="string">
  Signed license token for offline verification of CopilotKit Intelligence features.
</PropertyReference>

<PropertyReference name="guardrails_c" type="{ validTopics?: string[]; invalidTopics?: string[]; }"  >
This prop has no effect. It stays in the type only so that old code still compiles.

</PropertyReference>

<PropertyReference name="runtimeUrl" type="string">
  The endpoint for the Copilot Runtime instance. See the Copilot Runtime API
  documentation.
</PropertyReference>

<PropertyReference name="transcribeAudioUrl" type="string">
  The endpoint for the Copilot transcribe audio service.
</PropertyReference>

<PropertyReference name="textToSpeechUrl" type="string">
  The endpoint for the Copilot text to speech service.
</PropertyReference>

<PropertyReference name="headers" type="Record<string, string> | (() => Record<string, string>) | (() => Promise<Record<string, string>>)"  >
Additional headers to be sent with runtime requests. Pass an object for static
headers, or a function (sync or async) that builds them fresh. The function
runs when each request is sent, so a refreshed token is always used.

Cache inside the builder. Clerk's and Auth0's `getToken()` already cache. A
builder that calls the network every time adds one call per request.

If the builder throws or rejects, that request is not sent and `onError` gets
`header_resolution_failed`.

The v1 `CopilotTask` / GraphQL path doesn't await an async builder: it
sends that request without the builder's headers, and logs a one-time dev
warning. A sync builder and a plain object both reach `CopilotTask` as
expected.

Core headers are also sent to any `selfManagedAgents` /
`agents__unsafe_dev_only` agent, including ones on other origins. Don't put a
bearer token in core headers if those agents point at a third party.

For example:

```tsx
const { getToken } = useAuth();

<CopilotKit
  runtimeUrl="/api/copilotkit"
  headers={async () => ({ Authorization: `Bearer ${await getToken()}` })}
>
  {children}
</CopilotKit>
```

</PropertyReference>

<PropertyReference name="children" type="ReactNode" required>
  The part of your app that uses CopilotKit hooks and components. This is
  usually your whole app.
</PropertyReference>

<PropertyReference name="properties" type="Record<string, any>"  >
Custom properties to be sent with the request.
  Can include threadMetadata for thread creation and authorization for LangGraph Platform authentication.
  For example:
  ```js
  {
    'user_id': 'users_id',
    'authorization': 'your-auth-token', // For LangGraph Platform authentication
    threadMetadata: {
      'account_id': '123',
      'user_type': 'premium'
    }
  }
  ```

Note: The `authorization` property is automatically forwarded to LangGraph agents. See [Authentication](/auth) for details.

</PropertyReference>

<PropertyReference name="credentials" type="RequestCredentials"  >
Indicates whether the user agent should send or receive cookies from the other domain
  in the case of cross-origin requests.

To enable HTTP-only cookie authentication, set `credentials="include"` and configure
CORS on your runtime endpoint:

```tsx
// Frontend (https://myapp.com)
<CopilotKit runtimeUrl="https://api.myapp.com/copilotkit" credentials="include">
  {children}
</CopilotKit>;

// Backend (https://api.myapp.com)
import { createCopilotRuntimeHandler } from "@copilotkit/runtime/v2";

const handler = createCopilotRuntimeHandler({
  runtime,
  basePath: "/copilotkit",
  cors: {
    origin: "https://myapp.com",
    credentials: true,
  },
});
```

</PropertyReference>

<PropertyReference name="showDevConsole" type="boolean"  >
**Deprecated.** This prop controls only the error banners and toasts. To show
or hide the Inspector, use `enableInspector`.

Set to `true` to show error banners and toasts, `false` to hide all error UI.
Defaults to `true` on localhost and `false` on every other host.

</PropertyReference>

<PropertyReference name="showIntelligenceIndicator" type="boolean">
Whether to automatically mount the built-in CopilotKit Intelligence indicator
in chat. Set to `false` when your application renders its own Intelligence
status UI. Defaults to `true`.

</PropertyReference>

<PropertyReference name="selfManagedAgents" type="Record<string, AbstractAgent>">
  AG-UI agents managed by your app and registered directly with CopilotKit.
  Use this when you connect to agents without routing through a Copilot Runtime.
</PropertyReference>

<PropertyReference name="agents__unsafe_dev_only" type="Record<string, AbstractAgent>">
  Preconfigured local agents for development and tests. Use `selfManagedAgents`
  for production direct-agent setups.
</PropertyReference>

<PropertyReference name="a2ui" type="{ theme?: Theme; catalog?: any; loadingComponent?: React.ComponentType; includeSchema?: boolean; recovery?: A2UIRecoveryRendererOptions }">
Configuration for the A2UI (Agent-to-UI) renderer.

The built-in A2UI renderer is activated automatically when the runtime reports
that `a2ui` is configured in `CopilotRuntime`. This prop is optional. Use it to
override:

- `theme`: the A2UI viewer theme.
- `catalog`: the component catalog. The default is the basic catalog.
- `loadingComponent`: the component shown while a surface generates.
- `includeSchema`: whether the catalog schemas go to the agent as context.
- `recovery`: the error-recovery status UI.

`includeSchema` defaults to `true`, which sends the catalog's component schemas
and the A2UI generation and design guidelines to the agent as context. With
`includeSchema: false`, the agent still receives the catalog ID and the names of
the catalog's custom components, without their JSON schemas or the guidelines.
A LangGraph agent that uses the CopilotKit middleware's injected A2UI tool then
gives its A2UI subagent the component names only. To give the subagent more
detail, pass a composition guide through the middleware's A2UI guidelines:
`a2uiParams.guidelines.compositionGuide` in TypeScript, or
`a2ui_params["guidelines"]["composition_guide"]` in Python.

```tsx
<CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ theme: myCustomTheme }}>
  {children}
</CopilotKit>
```

</PropertyReference>

<PropertyReference name="mcpApps" type="{ allowSameOriginFallback?: boolean }">
Configuration for the built-in MCP Apps renderer.

`allowSameOriginFallback` restores `allow-same-origin` on the MCP App sandbox.
By default widgets get an opaque origin. **Unsafe:** with it set, a widget runs
with your page's origin and can read your cookies, storage and DOM. Only use it
for widgets you trust that need `localStorage`, `IndexedDB` or cookies. See
[Sandbox and widget storage](/generative-ui/mcp-apps#sandbox-and-widget-storage).

</PropertyReference>

<PropertyReference name="openGenerativeUI" type="{ sandboxFunctions?: SandboxFunction[]; designSkill?: string }">
  Configuration for Open Generative UI. Use `sandboxFunctions` to expose host
  functions to generated sandboxed iframes, and `designSkill` to override the
  design guidance injected as agent context for `generateSandboxedUi`.
</PropertyReference>

<PropertyReference name="defaultThrottleMs" type="number">
  Default throttle interval, in milliseconds, for `useAgent` re-renders caused
  by message and state updates. Individual `useAgent` calls and prebuilt chat
  components can override it with their own `throttleMs`.
</PropertyReference>

<PropertyReference name="agent" type="string">
  The agent to talk to, named by its **key in the runtime's `agents` map**, not the
  agent's own `name` or `id`. See [Which name identifies an
  agent](/backend/copilot-runtime#which-name-identifies-an-agent).
</PropertyReference>

<PropertyReference
  name="forwardedParameters"
  type="Pick<ForwardedParametersInput, 'temperature'>"
>
  Model parameters (only `temperature`) that the provider puts in the
  CopilotKit context. The built-in hooks do not read this value.
</PropertyReference>

<PropertyReference name="authConfig_c" type="{ SignInComponent: React.ComponentType<{ onSignInComplete: (authState: AuthState) => void; }>; }"  >
The auth config to use for the CopilotKit.

This feature is only available when using CopilotKit's cloud-hosted service. To use this feature, sign up at https://dashboard.operations.copilotkit.ai to get your publicApiKey. `SignInComponent` is the sign-in component that `useCopilotAuthenticatedAction_c` renders before it runs an action that needs the user to sign in.

</PropertyReference>

<PropertyReference name="threadId" type="string">
  The ID of the thread to load and continue. Set it to resume a saved
  conversation. While this prop is set, `setThreadId()` throws.
</PropertyReference>

<PropertyReference name="onError" type="CopilotErrorHandler"  >
Optional error handler for debugging and observability.

Requires publicApiKey: Error handling only works when publicApiKey is provided.
This is a CopilotKit Intelligence feature. The handler receives a structured
error event with debugging context.

```tsx
<CopilotKit
  publicApiKey="ck_pub_your_key"
  onError={(errorEvent) => {
    debugDashboard.capture(errorEvent);
  }}
>
  {children}
</CopilotKit>
```

</PropertyReference>

<PropertyReference name="enableInspector" type="boolean">
  Enable or disable the CopilotKit Inspector, letting you inspect AG-UI events,
  view agent messages, check agent state, and visualize agent context. It is
  enabled by default in development browser builds on localhost or loopback
  hosts, and is always disabled on remote hosts, in production, and during
  server rendering.
</PropertyReference>

<PropertyReference name="debug" type="DebugConfig">
  Enable client-side debug logging for the AG-UI transport and event pipeline.
  Pass `true` for event and lifecycle summaries, or a config object with
  `verbose: true` to include full event payloads.
</PropertyReference>
