CopilotKit
Reference / core / classes

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 — 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)
configCopilotKitCoreConfigrequired

Configuration object. See CopilotKitCoreConfig for the full type.

runtimeUrlstring

Endpoint of the CopilotRuntime that requests are sent to.

runtimeTransport"rest" | "single" | "auto"
Default: "auto"

Transport style for runtime endpoints. "auto" probes REST and falls back to single-route.

headersRecord<string, string>
Default: "{}"

Headers appended to every HTTP request made by the core.

credentialsRequestCredentials

Credentials mode for fetch requests (e.g. "include" for HTTP-only cookies).

propertiesRecord<string, unknown>
Default: "{}"

Values sent as forwardedProps to the AG-UI agent.

toolsFrontendTool<any>[]
Default: "[]"

Frontend tools available to the core. See FrontendTool.

suggestionsConfigSuggestionsConfig[]
Default: "[]"

Suggestion configurations registered at construction. See SuggestionsConfig.

agents__unsafe_dev_onlyRecord<string, AbstractAgent>
Default: "{}"

Local agent instances keyed by name. Development only — production requires a CopilotRuntime.

debugDebugConfig

Enables debug logging for the client-side event pipeline.

Methods

Agents

getAgent(id: string): AbstractAgent | undefinedmethod

Returns the agent registered under id, or undefined if none exists.

runAgent(params: CopilotKitCoreRunAgentParams): Promise<RunAgentResult>method

Runs an agent against the runtime, streaming events and executing any frontend tool calls it produces.

connectAgent(params: CopilotKitCoreConnectAgentParams): Promise<RunAgentResult>method

Connects to an agent to receive its current state and message stream without starting a new run.

stopAgent(params: CopilotKitCoreStopAgentParams): voidmethod

Aborts the current run for the given agent.

registerProxiedAgent(params): { agent; unregister }method

Registers a ProxiedCopilotRuntimeAgent under a local agentId that routes outbound requests to runtimeAgentId. Returns the proxy and an unregister cleanup handle. Throws if agentId is already taken.

addAgent__unsafe_dev_only(params: CopilotKitCoreAddAgentParams): voidmethod

Adds a local agent instance. Development only.

removeAgent__unsafe_dev_only(id: string): voidmethod

Removes a local agent by id. Development only.

setAgents__unsafe_dev_only(agents: Record<string, AbstractAgent>): voidmethod

Replaces the full set of local agents. Development only.

Tools

addTool(tool: FrontendTool): voidmethod

Registers a frontend tool the agent can call. If a tool with the same name and agentId is already registered, the call is a no-op (a warning is logged). See FrontendTool.

removeTool(id: string, agentId?: string): voidmethod

Removes a registered tool by name. With no agentId, removes only the global (unscoped) tool of that name; with agentId, removes only the tool scoped to that agent.

getTool(params: CopilotKitCoreGetToolParams): FrontendTool<any> | undefinedmethod

Returns a registered tool, or undefined if not found.

setTools(tools: FrontendTool<any>[]): voidmethod

Replaces the entire tool registry.

runTool(params: CopilotKitCoreRunToolParams): Promise<CopilotKitCoreRunToolResult>method

Executes a registered frontend tool directly, without an LLM turn. The handler runs, render components appear, and both the tool call and result messages are appended to agent.messages.

Context

addContext(context: Context): stringmethod

Adds a context entry shared with the agent and returns its generated id.

removeContext(id: string): voidmethod

Removes a context entry by id.

Suggestions

addSuggestionsConfig(config: SuggestionsConfig): stringmethod

Registers a suggestion configuration and returns its generated id.

removeSuggestionsConfig(id: string): voidmethod

Removes a suggestion configuration by id.

getSuggestions(agentId: string): CopilotKitCoreGetSuggestionsResultmethod

Returns the current suggestions and loading state for an agent.

reloadSuggestions(agentId: string): voidmethod

Re-generates suggestions for an agent.

clearSuggestions(agentId: string): voidmethod

Clears the current suggestions for an agent.

Subscriptions

subscribe(subscriber: CopilotKitCoreSubscriber): CopilotKitCoreSubscriptionmethod

Subscribes to core lifecycle events (agents changed, context changed, errors, runtime connection status, and more). Returns a subscription with an unsubscribe() method. See CopilotKitCoreSubscriber.

subscribeToAgentWithOptions(agent, subscriber, options?): CopilotKitCoreSubscriptionmethod

Subscribes to a single agent's message, state, and run-lifecycle callbacks with optional throttling. Every callback is wrapped with error protection. Use agent.subscribe() directly when you need AG-UI event handlers or per-item notifications.

Configuration

setRuntimeUrl(runtimeUrl: string | undefined): voidmethod

Updates the runtime endpoint.

setRuntimeTransport(runtimeTransport: CopilotRuntimeTransport): voidmethod

Updates the transport style.

setHeaders(headers: Record<string, string>): voidmethod

Replaces the request headers and re-applies them to existing agents.

setCredentials(credentials: RequestCredentials | undefined): voidmethod

Replaces the fetch credentials mode and re-applies it to existing agents.

setProperties(properties: Record<string, unknown>): voidmethod

Replaces the forwarded properties sent to agents.

setDebug(debug: DebugConfig | undefined): voidmethod

Toggles debug logging for the client-side event pipeline.

setDefaultThrottleMs(value: number | undefined): voidmethod

Sets the default throttle interval (ms) used by subscribeToAgentWithOptions. Invalid values are ignored.

State queries

getStateByRun(agentId, threadId, runId): State | undefinedmethod

Returns the agent state snapshot recorded for a specific run.

getRunIdForMessage(agentId, threadId, messageId): string | undefinedmethod

Returns the run id that produced a given message.

getRunIdsForThread(agentId, threadId): string[]method

Returns the ordered run ids recorded for a thread.

Properties (read-only)

agents: Readonly<Record<string, AbstractAgent>>getter

The currently registered agents, keyed by id.

tools: Readonly<FrontendTool<any>[]>getter

The currently registered frontend tools.

context: Readonly<Record<string, Context>>getter

The current shared context entries, keyed by id.

runtimeUrl: string | undefinedgetter

The configured runtime endpoint.

runtimeConnectionStatus: CopilotKitCoreRuntimeConnectionStatusgetter

The current runtime connection status. See CopilotKitCoreRuntimeConnectionStatus.

headers / credentials / propertiesgetter

Snapshots of the configured headers, credentials mode, and forwarded properties.

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