CopilotKitCoreSubscriber

Overview

CopilotKitCoreSubscriber is the object passed to CopilotKitCore.subscribe. Every callback is optional, receives an event object that always includes the copilotkit instance, and may return void or a Promise<void>. Use it to react to connection status, tool execution, suggestions, configuration changes, and errors.

Import

import type { CopilotKitCoreSubscriber } from "@copilotkit/core";

Definition

Every callback is optional, receives an event object that always includes the copilotkit instance, and returns void or Promise<void>. The shape below shows the representative onRuntimeConnectionStatusChanged callback; the Properties section documents each callback's exact event shape.

interface CopilotKitCoreSubscriber {
  onRuntimeConnectionStatusChanged?: (event: {
    copilotkit: CopilotKitCore;
    status: CopilotKitCoreRuntimeConnectionStatus;
  }) => void | Promise<void>;
  // ...one optional callback per lifecycle event (tool execution, agents,
  // context, suggestions, properties, headers, errors, thread stores).
  // See the Properties section below for each callback's event shape.
}

Properties

onRuntimeConnectionStatusChanged(event) => void | Promise<void>

Fired when the runtime connection status changes. Event: { copilotkit, status } where status is a CopilotKitCoreRuntimeConnectionStatus.

onToolExecutionStart(event) => void | Promise<void>

Fired when a frontend tool starts executing. Event: { copilotkit, toolCallId, agentId, toolName, args }.

onToolExecutionEnd(event) => void | Promise<void>

Fired when a frontend tool finishes executing. Event: { copilotkit, toolCallId, agentId, toolName, result, error? }, where result is the stringified tool result.

onAgentsChanged(event) => void | Promise<void>

Fired when the registered agents change. Event: { copilotkit, agents }.

onContextChanged(event) => void | Promise<void>

Fired when the shared context changes. Event: { copilotkit, context }.

onSuggestionsConfigChanged(event) => void | Promise<void>

Fired when the suggestions configuration changes. Event: { copilotkit, suggestionsConfig }.

onSuggestionsChanged(event) => void | Promise<void>

Fired when the generated suggestions for an agent change. Event: { copilotkit, agentId, suggestions }.

onSuggestionsStartedLoading(event) => void | Promise<void>

Fired when suggestion generation begins for an agent. Event: { copilotkit, agentId }.

onSuggestionsFinishedLoading(event) => void | Promise<void>

Fired when suggestion generation completes for an agent. Event: { copilotkit, agentId }.

onPropertiesChanged(event) => void | Promise<void>

Fired when the forwarded properties change. Event: { copilotkit, properties }.

onHeadersChanged(event) => void | Promise<void>

Fired when the request headers change. Event: { copilotkit, headers }.

onError(event) => void | Promise<void>

Fired when an error occurs. Event: { copilotkit, error, code, context } where code is a CopilotKitCoreErrorCode.

onThreadStoreRegistered(event) => void | Promise<void>

Fired when a thread store is registered. Event: { copilotkit, agentId, store }.

onThreadStoreUnregistered(event) => void | Promise<void>

Fired when a thread store is removed (by explicit unregister or by a replacing register). The previous store is delivered via prevStore. Event: { copilotkit, agentId, prevStore }.

Usage

const subscription = copilotkit.subscribe({
  onRuntimeConnectionStatusChanged: ({ status }) => {
    console.log("connection:", status);
  },
  onError: ({ code, error }) => {
    console.error(code, error);
  },
});

// later
subscription.unsubscribe();