provideCopilotKit

Overview

provideCopilotKit is the primary setup entry point for @copilotkit/angular. It returns an Angular Provider that you add to your application (or component) providers array. The provider stores your CopilotKitConfig behind the COPILOT_KIT_CONFIG injection token, where the CopilotKit service and every CopilotKit function reads it.

This is the Angular equivalent of React's <CopilotKit> provider. Because Angular configures CopilotKit through dependency injection rather than a wrapper component, you register it once in app.config.ts (or in a feature component's providers) and everything below it in the injector tree can connect to your runtime and agents.

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.

Signature

import { provideCopilotKit } from "@copilotkit/angular";
import type { Provider } from "@angular/core";

function provideCopilotKit(config: CopilotKitConfig): Provider;

Parameters

<PropertyReference name="config" type="CopilotKitConfig" required> The CopilotKit configuration object. <PropertyReference name="runtimeUrl" type="string"> The URL of your CopilotKit runtime endpoint. Set this to route agent traffic through a runtime (for example a Next.js, Express, or Hono backend). </PropertyReference> <PropertyReference name="headers" type="Record<string, string>"> Extra HTTP headers sent with every runtime request, for example an `Authorization` header. If you pass a `licenseKey`, a `X-CopilotCloud-Public-Api-Key` header is merged in automatically unless you already set one here. </PropertyReference> <PropertyReference name="licenseKey" type="string"> Your CopilotCloud license key (a `ck_pub_...` value). When present and valid it is sent as the `X-CopilotCloud-Public-Api-Key` header and removes the license watermark. An absent or malformed key logs a one-time console warning. </PropertyReference> <PropertyReference name="properties" type="Record<string, unknown>"> Arbitrary key/value properties forwarded to the runtime with each request. Use this for request-scoped metadata such as a user id or tenant. </PropertyReference> <PropertyReference name="agents" type="Record<string, AbstractAgent>"> A map of agent id to AG-UI agent instance. Use this to register agents directly in the client. These are merged with `selfManagedAgents` when the underlying core is constructed. </PropertyReference> <PropertyReference name="selfManagedAgents" type="Record<string, AbstractAgent>"> A map of agent id to AG-UI agent instance that connect directly to an agent endpoint without a CopilotKit runtime. Provide an `@ag-ui/client` agent such as `HttpAgent` here to talk to an agent server directly. </PropertyReference> <PropertyReference name="tools" type="ClientTool[]"> Client tools registered at startup. Each `ClientTool` is a frontend tool definition without a `handler`, plus an optional `renderer` component. When a tool supplies both a `renderer` and `parameters`, its renderer is registered as a tool call renderer automatically. </PropertyReference> <PropertyReference name="renderToolCalls" type="RenderToolCallConfig[]"> Renderers for tool calls. Each entry maps a tool `name` and a `args` [Standard Schema](https://standardschema.dev) to a `component` that visualizes the call. Optional `agentId` scopes the renderer to one agent and `passAgent` exposes the agent to the renderer. </PropertyReference> <PropertyReference name="renderActivityMessages" type="RenderActivityMessageConfig[]"> Renderers for agent activity messages. Each entry maps an `activityType` and a `content` schema to a `component`. Optional `agentId` scopes the renderer to one agent. </PropertyReference> <PropertyReference name="suggestionsConfig" type="SuggestionsConfig[]"> Suggestion configurations. Each entry is either a dynamic config (`instructions` plus optional `minSuggestions`, `maxSuggestions`, `available`, `providerAgentId`, `consumerAgentId`) or a static config (an explicit `suggestions` array plus optional `available` and `consumerAgentId`). </PropertyReference> <PropertyReference name="frontendTools" type="FrontendToolConfig[]"> Client-side tools registered at startup, each with a `name`, `description`, `parameters` schema, async `handler`, and optional `component` renderer, `followUp`, and `agentId`. Handlers run inside the root injection context, so they can use `inject()`. Prefer [`registerFrontendTool`](/reference/angular/functions/registerFrontendTool) for tools scoped to a component. </PropertyReference> <PropertyReference name="humanInTheLoop" type="HumanInTheLoopConfig[]"> Human-in-the-loop tools registered at startup. Each entry has a `name`, `description`, `parameters` schema, a `component` renderer that collects the user's response, and an optional `agentId`. Prefer [`registerHumanInTheLoop`](/reference/angular/functions/registerHumanInTheLoop) for tools scoped to a component. </PropertyReference> <PropertyReference name="a2ui" type="A2UIConfig"> Configuration for A2UI (agent-to-UI declarative surfaces).

<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.
</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> <PropertyReference name="openGenerativeUI" type="OpenGenerativeUIConfig"> Configuration for open generative UI (the `generateSandboxedUi` tool). Providing this object enables the feature.

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

</PropertyReference> </PropertyReference>

Return Value

Returns an Angular Provider that binds your (header-augmented) config to the COPILOT_KIT_CONFIG injection token. Add it to a providers array.

Usage

Connect through a runtime

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",
      },
    }),
  ],
};

Connect directly to an AG-UI agent

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/" }),
      },
    }),
  ],
};

Register startup tools

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}!`,
        },
      ],
    }),
  ],
};

Behavior

The provided config is bound to the COPILOT_KIT_CONFIG injection token. Read it with injectCopilotKitConfig.
If licenseKey (or an X-CopilotCloud-Public-Api-Key header) is missing or malformed, a one-time license watermark warning is logged to the console.
agents and selfManagedAgents are merged together when the underlying core is created, so an id present in both resolves to the selfManagedAgents entry.