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:
agentsis populated after the runtime responds, so it may be empty immediately after construction. Usesubscribe({ onAgentsChanged })to react when agents become available. - Error surfacing: failures from runtime fetches, agent runs, tool runs, and subscriber callbacks go to the
onErrorsubscriber callback with a CopilotKitCoreErrorCode. The method that failed does not throw them. The exception isrunTool(): 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
setHeaderscall 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_onlyAPIs: the*Agent__unsafe_dev_onlymethods register local agents that run in the browser and talk to their AG-UI endpoints directly, with no CopilotRuntime. The ReactselfManagedAgentsprop uses this path in production.
How is this guide?