# CopilotKitProvider

> The Vue 3 provider component that wraps your application and supplies the CopilotKit context.

<Callout type="info">
  This is the Vue 3 provider component. Import it from `@copilotkit/vue/v2`.
</Callout>

`CopilotKitProvider` typically wraps your entire application (or a sub-tree where you want a copilot). It creates the CopilotKit core instance and provides the copilot context to all descendant components and composables (such as [`useCopilotKit`](/reference/vue/hooks/useCopilotKit) and [`useAgent`](/reference/vue/hooks/useAgent)).

The wrapped application is rendered through the component's [default slot](#slots), since Vue uses slots rather than a `children` prop.

## Example [#example]

```vue
<script setup lang="ts">
import { CopilotKitProvider } from "@copilotkit/vue/v2";
</script>

<template>
  <CopilotKitProvider runtime-url="/api/copilotkit">
    <!-- ... your app ... -->
  </CopilotKitProvider>
</template>
```

Connect to Copilot Cloud with a public API key instead of a self-hosted runtime:

```vue
<script setup lang="ts">
import { CopilotKitProvider } from "@copilotkit/vue/v2";
</script>

<template>
  <CopilotKitProvider public-api-key="ck_pub_your_key">
    <!-- ... your app ... -->
  </CopilotKitProvider>
</template>
```

## Properties [#properties]

You must provide at least one of `runtimeUrl`, `publicApiKey`, or `publicLicenseKey` (or a set of local agents), otherwise the provider warns in development and throws in production.

<PropertyReference name="runtimeUrl" type="string">
  The endpoint for the Copilot Runtime instance. When omitted but a public key is set, requests fall back to the Copilot Cloud chat endpoint.
</PropertyReference>

<PropertyReference name="headers" type="Record<string, string> | (() => Record<string, string>) | (() => Promise<Record<string, string>>)">
  Additional headers to send with each request. Pass a plain object for
  static headers, or a function (sync or async) that returns them. A builder
  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`.

Passing the same builder again does nothing. Passing a new builder function
through the `headers` prop also does nothing, because the provider keeps one
stable wrapper for any builder. When the user changes, do one of these:

- Remount the provider, for example with a `key`.
- Call `copilotkit.value.setHeaders(...)` with a new function or a record. The
  Inspector metadata and thread lists reload for the new user. The runtime's
  `/info` is not fetched again.

`copilotkit.value.headers` is the last resolved value. Use
`await copilotkit.value.resolveHeaders()` for your own requests.

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.

```json
{
  "Authorization": "Bearer X"
}
```

</PropertyReference>

<PropertyReference name="credentials" type="RequestCredentials">
  Indicates whether the user agent should send or receive cookies for cross-origin requests. Set to `"include"` to enable HTTP-only cookie authentication (configure CORS with credentials on your runtime endpoint to match).
</PropertyReference>

<PropertyReference name="messageFilter" type="(messages: Message[], context: { agentId: string }) => Message[]">
  Rewrites the message list sent to the agent on every run.

CopilotKit sends the whole thread with each request. When your agent already
stores the conversation (a LangGraph checkpointer, a Mastra memory store, a
Strands `SessionManager`), most of that payload is waste, and an agent that
merges the inbound list with its own store can show the model every turn twice.

Return the messages to send:

```vue
<CopilotKitProvider
  runtime-url="/api/copilotkit"
  :message-filter="(messages) => messages.slice(-1)"
>
  <YourApp />
</CopilotKitProvider>
```

The filter changes the request body only. The transcript the UI renders is
untouched, so the chat still shows the full conversation. Broken tool-call pairs
are repaired before the request goes out, so a filter this blunt cannot strand a
tool result mid-approval.

Agents reached through your CopilotRuntime honor this. An agent your app
constructs itself and passes in directly does not. CopilotKit Intelligence runs
and suggestion runs are never filtered.

</PropertyReference>

<PropertyReference name="defaultThrottleMs" type="number">
  Default throttle interval (in milliseconds) applied to `useAgent` composables that do not specify their own `throttleMs`. Must be a non-negative finite number; invalid values log an error and fall back to unthrottled.
</PropertyReference>

<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. Obtain it from https://dashboard.operations.copilotkit.ai.
</PropertyReference>

<PropertyReference name="properties" type="Record<string, unknown>" default="{}">
  Custom properties sent with each request. Can include `threadMetadata` for thread creation and `authorization` for LangGraph Platform authentication.

```js
{
  user_id: "users_id",
  authorization: "your-auth-token", // For LangGraph Platform authentication
  threadMetadata: {
    account_id: "123",
    user_type: "premium",
  },
}
```

</PropertyReference>

<PropertyReference name="useSingleEndpoint" type="boolean">
  Controls the runtime transport. `true` uses a single endpoint, `false` uses the REST transport, and when omitted the transport is auto-detected.
</PropertyReference>

<PropertyReference name="agents__unsafe_dev_only" type="Record<string, AbstractAgent>" default="{}">
  Local in-browser agents keyed by agent ID, for development only. These run client-side rather than through the runtime, so do not rely on them in production.
</PropertyReference>

<PropertyReference name="selfManagedAgents" type="Record<string, AbstractAgent>" default="{}">
  Self-managed agents keyed by agent ID. Merged with `agents__unsafe_dev_only`. On a key collision, the agent in `selfManagedAgents` wins.
</PropertyReference>

<PropertyReference name="renderToolCalls" type="VueToolCallRenderer<any>[]">
  Renderers for tool calls, mapping a tool name and argument schema to a Vue component used to render the tool call in the UI.
</PropertyReference>

<PropertyReference name="renderActivityMessages" type="VueActivityMessageRenderer<unknown>[]" default="[]">
  Renderers for activity messages, mapping an activity type and content schema to a Vue component. The built-in MCP Apps renderer is always merged in automatically; the A2UI and Open Generative UI renderers are merged in when those features are active.
</PropertyReference>

<PropertyReference name="renderCustomMessages" type="VueCustomMessageRenderer[]" default="[]">
  Renderers that draw extra content before or after each message. Each renderer receives the `message`, its `position` (`"before"` or `"after"`), and run metadata. Set `agentId` to limit a renderer to one agent.
</PropertyReference>

<PropertyReference name="frontendTools" type="VueFrontendTool[]" default="[]">
  Frontend tools available to the agent. Must be a stable array; to add or remove tools dynamically, use the [`useFrontendTool`](/reference/vue/hooks/useFrontendTool) composable instead.
</PropertyReference>

<PropertyReference name="humanInTheLoop" type="VueHumanInTheLoop[]" default="[]">
  Human-in-the-loop tools that pause for user input before resolving. Must be a stable array; to add or remove them dynamically, use the [`useHumanInTheLoop`](/reference/vue/hooks/useHumanInTheLoop) composable instead.
</PropertyReference>

<PropertyReference name="openGenerativeUI" type="{ sandboxFunctions?: SandboxFunction[]; designSkill?: string }">
  Configuration for Open Generative UI. `sandboxFunctions` exposes host functions to generated sandboxed UI (callable via `Websandbox.connection.remote`), and `designSkill` overrides the default design guidelines provided to the generation tool. `sandboxFunctions` must be a stable array.
</PropertyReference>

<PropertyReference name="enableInspector" type="boolean">
  Controls the CopilotKit Inspector during development. It is enabled by
  default in browser development builds and is never loaded in production or
  during SSR. In a Vue template, pass `:enable-inspector="false"` to disable it.
</PropertyReference>

<PropertyReference name="showDevConsole" type="boolean | &quot;auto&quot;">
  **Deprecated:** use `enableInspector`. This prop does not control the
  Inspector.
</PropertyReference>

<PropertyReference name="onError" type="(event: { error: Error; code: CopilotKitCoreErrorCode; context: Record<string, any> }) => void | Promise<void>">
  Optional error handler for debugging and observability. Receives a structured error event with the error, an error code, and contextual debugging information.

```vue
<script setup lang="ts">
import { CopilotKitProvider } from "@copilotkit/vue/v2";

function handleError(event: {
  error: Error;
  code: string;
  context: Record<string, any>;
}) {
  debugDashboard.capture(event);
}
</script>

<template>
  <CopilotKitProvider public-api-key="ck_pub_your_key" :on-error="handleError">
    <!-- ... your app ... -->
  </CopilotKitProvider>
</template>
```

</PropertyReference>

<PropertyReference name="a2ui" type="{ theme?: A2UITheme; catalog?: any; loadingComponent?: Component; includeSchema?: boolean }">
  Configuration for the A2UI (Agent-to-UI) renderer. The built-in A2UI renderer activates automatically when the runtime reports that `a2ui` is configured in `CopilotRuntime`, so this prop is optional and only needed to override the theme, supply a custom component `catalog`, set a `loadingComponent`, or toggle whether the schema is included (`includeSchema`).

  `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.

```vue
<template>
  <CopilotKitProvider
    runtime-url="/api/copilotkit"
    :a2ui="{ theme: myCustomTheme }"
  >
    <!-- ... your app ... -->
  </CopilotKitProvider>
</template>
```

</PropertyReference>

<PropertyReference name="generativeUI" type="GenerativeUIConfig">
  Experimental. Turns on native generative UI. The agent renders your Vue components in the chat, or in a [`GenerativeUISurface`](/reference/vue/components/GenerativeUISurface) on the page. Import the types from `@copilotkit/vue/v2/generative-ui`.

Bind it in camelCase, as `:generativeUI`. Vue reads the kebab-case `:generative-ui` as a different prop (`generativeUi`), so the config does not reach the provider.

```vue
<script setup lang="ts">
import { CopilotChat, CopilotKitProvider } from "@copilotkit/vue/v2";
import { shopUI } from "./shop-ui";
</script>

<template>
  <CopilotKitProvider runtime-url="/api/copilotkit" :generativeUI="{ ui: shopUI }">
    <CopilotChat />
  </CopilotKitProvider>
</template>
```

  <PropertyReference name="ui" type="GenerativeUI" required>
    The object from `createGenerativeUI`: the components the model can render, the app state they read, and the functions they call.
  </PropertyReference>

  <PropertyReference name="transport" type='"tool" | "markdown"' default='"tool"'>
    How the model sends UI operations.

    - `"tool"`: the model calls the `render_ui` tool. The runtime validates each operation before it streams it to the client.
    - `"markdown"`: the model writes the operations in `a2ui` code fences in its reply. The client reads and validates them.
  </PropertyReference>

  <PropertyReference name="agentIds" type="string[]">
    The agents that get the generative UI. When you omit it, every agent gets it.
  </PropertyReference>

  <PropertyReference name="theme" type="GenerativeUITheme">
    Values for the `--a2ui-*` CSS variables and the map style. Top-level values apply in light and dark mode. Values under `dark` apply in dark mode, which is on under a `.dark` class.
  </PropertyReference>

  <PropertyReference name="errorBoundary" type="{ fallback?: Component; onError?: (info: GenerativeUIErrorInfo) => void }">
    Fallback UI and error reports for generated UI.

    - `fallback`: a Vue component that replaces the default fallback of a failed component. It gets `error`, `retry`, `surfaceId`, and `componentId` as props.
    - `onError`: called for render, props, operation, function, and event failures.
  </PropertyReference>

  <PropertyReference name="sendContext" type="boolean" default="true">
    Markdown transport only. Sends the component schema and the fence guideline as context entries. Set `false` when your backend builds its own prompt.
  </PropertyReference>

  <PropertyReference name="includeCatalog" type="boolean" default="true">
    Markdown transport only. Sends the component schemas in the envelope (`catalog.components`).
  </PropertyReference>

For a full walkthrough, see [Surfaces](/generative-ui/components/surfaces) and [State and actions](/generative-ui/components/state-and-actions).

</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](/vue/generative-ui/mcp-apps#sandbox-and-widget-storage).
</PropertyReference>

<PropertyReference name="debug" type="DebugConfig">
  Enable debug logging for the client-side event pipeline. Accepts `true` / `false` to toggle events and lifecycle logging (verbose off), or `{ events?: boolean; lifecycle?: boolean; verbose?: boolean }` for granular control.
</PropertyReference>

## Slots [#slots]

<PropertyReference name="default" type="slot" required>
  The default slot renders the wrapped application. Vue uses slots rather than a `children` prop, so everything placed between the opening and closing `<CopilotKitProvider>` tags receives the copilot context.

```vue
<template>
  <CopilotKitProvider runtime-url="/api/copilotkit">
    <!-- This content is the default slot -->
    <App />
  </CopilotKitProvider>
</template>
```

</PropertyReference>
