copilotkit__copilotkit/docs/snippets/shared/reference/copilotkit-component.mdx

{
 /*
  * ATTENTION! DO NOT MODIFY THIS FILE!
  * This page is auto-generated. If you want to make any changes to this page, changes must be made at:
  * packages/react-core/src/components/copilot-provider/copilotkit.tsx
  */
}

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

You can find more information about self-hosting CopilotKit [here](/direct-to-llm/guides/self-hosting).

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

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

## Properties

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

  Don't have it yet? Go to https://cloud.copilotkit.ai and get one for free.
</PropertyReference>

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

  Don't have it yet? Go to https://cloud.copilotkit.ai and get one for free.
</PropertyReference>

<PropertyReference name="guardrails_c" type="{ validTopics?: string[]; invalidTopics?: string[]; }"  >
Restrict input to specific topics using guardrails.
  @remarks

  This feature is only available when using CopilotKit's hosted cloud service. To use this feature, sign up at https://cloud.copilotkit.ai to get your publicApiKey. The feature allows restricting chat conversations to specific topics.
</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>"  >
Additional headers to be sent with the request.

  For example:
  ```json
  {
    "Authorization": "Bearer X"
  }
  ```
</PropertyReference>

<PropertyReference name="children" type="ReactNode" required >
The children to be rendered within the CopilotKit.
</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 LangChain agents. See the LangGraph Agent Authentication Guide (see code examples above) 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)
  copilotRuntimeNextJSAppRouterEndpoint({
    runtime,
    endpoint: "/copilotkit",
    cors: {
      origin: "https://myapp.com",
      credentials: true,
    },
  });
  ```
</PropertyReference>

<PropertyReference name="showDevConsole" type="boolean"  >
Whether to show the dev console.

  Set to `true` to show error banners and toasts, `false` to hide all error UI.
  Defaults to `false` for production safety.
</PropertyReference>

<PropertyReference name="a2ui" type="{ theme?: Theme; catalog?: any; loadingComponent?: React.ComponentType; includeSchema?: boolean }">
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 and only
  needed if you want to override defaults.

  | Option | Type | Description |
  | --- | --- | --- |
  | `theme` | `Theme` | Override the default A2UI viewer theme. |
  | `catalog` | `any` | Custom component catalog. Defaults to `basicCatalog`. |
  | `loadingComponent` | `React.ComponentType` | Custom loading component shown while a surface is generating. |
  | `includeSchema` | `boolean` | When `true` (default), full component schemas are sent as agent context. |

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

<PropertyReference name="agent" type="string"  >
The name of the agent to use.
</PropertyReference>

<PropertyReference name="forwardedParameters" type="Pick<ForwardedParametersInput, 'temperature'>"  >
The forwarded parameters to use for the task.
</PropertyReference>

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

  This feature is only available when using CopilotKit's hosted cloud service. To use this feature, sign up at https://cloud.copilotkit.ai to get your publicApiKey. The feature allows restricting chat conversations to specific topics.
</PropertyReference>

<PropertyReference name="threadId" type="string"  >
The thread id to use for the CopilotKit.
</PropertyReference>

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

  Requires publicApiKey: Error handling only works when publicApiKey is provided.
  This is a premium Copilot Cloud feature.

  @param errorEvent - Structured error event with rich debugging context

  @example
  ```typescript
  <CopilotKit
    publicApiKey="ck_pub_your_key"
    onError={(errorEvent) => {
      debugDashboard.capture(errorEvent);
    }}
  >
  ```
</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. Defaults
  to enabled.
</PropertyReference>