showcase/shell-docs/src/content/reference/angular/functions/provideCopilotKit.mdx
provideCopilotKit is the primary setup entry point for @copilotkit/angular. It returns an Angular Provider that you add to your application providers. The provider stores your CopilotKitConfig behind the COPILOT_KIT_CONFIG injection token, where the root CopilotKit service reads it.
Register it once in app.config.ts. A component-local config provider alone does not configure the root CopilotKit service.
You typically configure the connection one of two ways: point at a CopilotKit runtime with runtimeUrl, or connect directly to one or more AG-UI agents with selfManagedAgents.
import { provideCopilotKit } from "@copilotkit/angular";
import type { Provider } from "@angular/core";
function provideCopilotKit(config: CopilotKitConfig): Provider;
<PropertyReference name="theme" type="Theme">
The A2UI theme used to style rendered surfaces.
</PropertyReference>
<PropertyReference name="catalog" type="Catalog<LitComponentImplementation>">
A catalog of custom components the agent may render. Providing it enables
A2UI even when the runtime does not advertise A2UI through `/info`.
</PropertyReference>
<PropertyReference name="loadingComponent" type="() => LitRenderable">
A function returning the element shown while a surface is loading.
</PropertyReference>
<PropertyReference name="includeSchema" type="boolean" default="true">
Whether to send the catalog component schemas to the agent as context. Set
to `false` to omit the schema context.
</PropertyReference>
<PropertyReference name="recovery" type="A2UIRecoveryOptions">
Controls when A2UI retry and diagnostic state becomes visible.
<PropertyReference name="showAfterMs" type="number" default="2000">
Delay before revealing a transient retry.
</PropertyReference>
<PropertyReference name="showAfterAttempts" type="number" default="2">
Attempt number that reveals retry state immediately.
</PropertyReference>
<PropertyReference name="debugExposure" type='"hidden" | "collapsed" | "verbose"'>
Client diagnostic visibility. Authoritative server lifecycle content may
override it.
</PropertyReference>
</PropertyReference>
<PropertyReference name="sandboxFunctions" type="SandboxFunction[]">
Functions the sandboxed UI can call back into the host application via
`Websandbox.connection.remote.<functionName>(args)`. Each has a `name`,
`description`, `parameters` schema, and a `handler`.
</PropertyReference>
<PropertyReference name="designSkill" type="string">
Design guidelines passed to the agent for generated UI. Defaults to the
built-in shadcn-inspired design skill.
</PropertyReference>
Returns an Angular Provider that binds your (header-augmented) config to the COPILOT_KIT_CONFIG injection token. Add it to the application providers.
Point runtimeUrl at your CopilotKit runtime endpoint and register the provider in your application config.
import { ApplicationConfig } from "@angular/core";
import { provideCopilotKit } from "@copilotkit/angular";
export const appConfig: ApplicationConfig = {
providers: [
provideCopilotKit({
runtimeUrl: "/api/copilotkit",
headers: {
Authorization: "Bearer <token>",
},
properties: {
userId: "user_123",
},
}),
],
};
To talk to an agent server without a CopilotKit runtime, pass selfManagedAgents with an @ag-ui/client agent such as HttpAgent.
import { ApplicationConfig } from "@angular/core";
import { provideCopilotKit } from "@copilotkit/angular";
import { HttpAgent } from "@ag-ui/client";
export const appConfig: ApplicationConfig = {
providers: [
provideCopilotKit({
selfManagedAgents: {
default: new HttpAgent({ url: "http://localhost:8000/" }),
},
}),
],
};
Pass frontendTools to register client tools when the application starts. Their handlers run inside the root injection context, so they can use inject().
import { ApplicationConfig } from "@angular/core";
import { provideCopilotKit } from "@copilotkit/angular";
import { z } from "zod";
export const appConfig: ApplicationConfig = {
providers: [
provideCopilotKit({
runtimeUrl: "/api/copilotkit",
frontendTools: [
{
name: "sayHello",
description: "Greet the user by name",
parameters: z.object({ name: z.string() }),
handler: async ({ name }) => `Hello, ${name}!`,
},
],
}),
],
};
COPILOT_KIT_CONFIG injection token. Read it with injectCopilotKitConfig.licenseKey is merged into the
X-CopilotCloud-Public-Api-Key header unless that header is already present.
The current package does not render a watermark or log a missing-key warning.agents and selfManagedAgents are merged together when the underlying core is created, so an id present in both resolves to the selfManagedAgents entry.