CopilotKitCore

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 — reach for it directly when you need an agent client outside of those frameworks.

Import

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

Constructor

new CopilotKitCore(config: CopilotKitCoreConfig)

Methods

Agents

Tools

Context

Suggestions

Subscriptions

Configuration

State queries

Properties (read-only)

Usage

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

const copilotkit = new CopilotKitCore({
  runtimeUrl: "/api/copilotkit",
  tools: [
    {
      name: "showAlert",
      handler: ({ message }: { message: string }) => window.alert(message),
    },
  ],
});

const subscription = copilotkit.subscribe({
  onRuntimeConnectionStatusChanged: ({ status }) => console.log(status),
});

// `agents` populates after the runtime responds — `onAgentsChanged` (above)
// fires when they're ready; this guarded lookup is for illustration.
const agent = copilotkit.getAgent("default");
if (agent) {
  await copilotkit.runAgent({ agent });
}

subscription.unsubscribe();

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 (runtime fetch, agent run, tool execution, subscriber callbacks) are delivered through the onError subscriber callback with a CopilotKitCoreErrorCode; they are not thrown from the originating method — except runTool(), which also throws when the named tool or its resolved agent cannot be found.
• Subscriber isolation — a throw in one subscriber callback is caught and logged; it does not stall notifications to other subscribers.
• __unsafe_dev_only APIs — the *Agent__unsafe_dev_only methods register local in-memory agents for development. Production setups must go through a CopilotRuntime.

Related

• @copilotkit/core overview
• CopilotKitCoreConfig
• CopilotKitCoreSubscriber
• ProxiedCopilotRuntimeAgent
• FrontendTool