CopilotKitCore

Framework-agnostic client that connects to a CopilotRuntime and manages agents, tools, context, and suggestions.

Overview

CopilotKitCore is the main entry point of @copilotkit/core. It connects to a CopilotRuntime over the AG-UI protocol, exposes the available agents, holds the registry of frontend tools, shared context, and suggestions, and notifies subscribers when any of that state changes. The React, Angular, and vanilla bindings all wrap a single instance of this class. Use it directly when you need an agent client outside of those frameworks.

Import

import { CopilotKitCore } from "@copilotkit/core";

Constructor

new CopilotKitCore(config: CopilotKitCoreConfig)

Prop

Type

Methods

Agents

Prop

Type

Tools

Prop

Type

Context

Prop

Type

Suggestions

Prop

Type

Subscriptions

Prop

Type

Inspector metadata

Prop

Type

Configuration

Prop

Type

State queries

Prop

Type

Properties (read-only)

Prop

Type

Usage

A tool's parameters take any Standard Schema. This sample uses zod.

import { CopilotKitCore } from "@copilotkit/core";
import { z } from "zod";

const copilotkit = new CopilotKitCore({
  runtimeUrl: "/api/copilotkit",
  tools: [
    {
      name: "showAlert",
      description: "Show a browser alert",
      parameters: z.object({ message: z.string() }),
      handler: async ({ message }) => {
        window.alert(message);
      },
    },
  ],
});

const subscription = copilotkit.subscribe({
  onRuntimeConnectionStatusChanged: ({ status }) => console.log(status),
  onAgentsChanged: async () => {
    const agent = copilotkit.getAgent("default");
    if (!agent) return;
    subscription.unsubscribe();
    await copilotkit.runAgent({ agent });
  },
});

Behavior

  • Asynchronous agent population: agents is populated after the runtime responds, so it may be empty immediately after construction. Use subscribe({ onAgentsChanged }) to react when agents become available.
  • Error surfacing: failures from runtime fetches, agent runs, tool runs, and subscriber callbacks go to the onError subscriber callback with a CopilotKitCoreErrorCode. The method that failed does not throw them. The exception is runTool(): it also throws when it cannot find the named tool or its agent.
  • Subscriber isolation: a throw in one subscriber callback is caught and logged; it does not stall notifications to other subscribers.
  • Inspector metadata isolation: metadata loads after the connected and agent notifications finish. A setHeaders call that changes the resolved values, or a credential change, refreshes it. It does not refetch /info. Runtime URL, transport, auth, connection, and capability checks prevent a stale request from replacing a newer value.
  • __unsafe_dev_only APIs: the *Agent__unsafe_dev_only methods register local agents that run in the browser and talk to their AG-UI endpoints directly, with no CopilotRuntime. The React selfManagedAgents prop uses this path in production.

How is this guide?