provideCopilotKit.mdx

title	provideCopilotKit
description	Angular provider that configures CopilotKit through dependency injection: runtime URL, agents, tools, headers, and more

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

The CopilotKit configuration object. 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). 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. 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. Arbitrary key/value properties forwarded to the runtime with each request. Use this for request-scoped metadata such as a user id or tenant. 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. 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. 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. 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. 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. 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`). 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. 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. 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>

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>

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.

Related