# CopilotKitCoreSubscriber

> Set of optional callbacks notified of CopilotKitCore lifecycle events.

## Overview [#overview]

`CopilotKitCoreSubscriber` is the object passed to [`CopilotKitCore.subscribe`](/reference/core/classes/CopilotKitCore). 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]

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

## Definition [#definition]

The shape below shows one callback, `onRuntimeConnectionStatusChanged`.
[Properties](#properties) lists the event shape of each callback.

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

## Properties [#properties]

<PropertyReference name="onRuntimeConnectionStatusChanged" type="(event) => void | Promise<void>">
  Fired when the runtime connection status changes. Event: `{ copilotkit, status }` where `status` is a [`CopilotKitCoreRuntimeConnectionStatus`](/reference/core/enums/CopilotKitCoreRuntimeConnectionStatus).
</PropertyReference>

<PropertyReference name="onToolExecutionStart" type="(event) => void | Promise<void>">
  Fired when a frontend tool starts executing. Event: `{ copilotkit, toolCallId, agentId, toolName, args }`.
</PropertyReference>

<PropertyReference name="onToolExecutionEnd" type="(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.
</PropertyReference>

<PropertyReference name="onAgentsChanged" type="(event) => void | Promise<void>">
  Fired when the registered agents change. Event: `{ copilotkit, agents }`.
</PropertyReference>

<PropertyReference name="onAgentRunStarted" type="(event) => void | Promise<void>">
  Fired when an agent run or connect begins. Event: `{ copilotkit, agent }`. The
  `agent` can be a per-thread clone that is not in `copilotkit.agents`, so
  `onAgentsChanged` does not fire for it.
</PropertyReference>

<PropertyReference name="onContextChanged" type="(event) => void | Promise<void>">
  Fired when the shared context changes. Event: `{ copilotkit, context }`.
</PropertyReference>

<PropertyReference name="onCatalogComponentsChanged" type="(event) => void | Promise<void>">
  Fired when the A2UI catalog component list changes, or when a component is
  enabled or disabled. Event: `{ copilotkit, catalogComponents }`.
</PropertyReference>

<PropertyReference name="onSuggestionsConfigChanged" type="(event) => void | Promise<void>">
  Fired when the suggestions configuration changes. Event: `{ copilotkit, suggestionsConfig }`.
</PropertyReference>

<PropertyReference name="onSuggestionsChanged" type="(event) => void | Promise<void>">
  Fired when the generated suggestions for an agent change. Event: `{ copilotkit, agentId, suggestions }`.
</PropertyReference>

<PropertyReference name="onSuggestionsStartedLoading" type="(event) => void | Promise<void>">
  Fired when suggestion generation begins for an agent. Event: `{ copilotkit, agentId }`.
</PropertyReference>

<PropertyReference name="onSuggestionsFinishedLoading" type="(event) => void | Promise<void>">
  Fired when suggestion generation completes for an agent. Event: `{ copilotkit, agentId }`.
</PropertyReference>

<PropertyReference name="onPropertiesChanged" type="(event) => void | Promise<void>">
  Fired when the forwarded properties change. Event: `{ copilotkit, properties }`.
</PropertyReference>

<PropertyReference name="onHeadersChanged" type="(event) => void | Promise<void>">
  Fired when `setHeaders` gets one of these changes:

  - a record whose normalized values differ
  - a new builder function
  - a builder in place of a record, or a record in place of a builder

  A builder that returns a new token for a request does not fire it. Event:
  `{ copilotkit, headers }`.
</PropertyReference>

<PropertyReference name="onInspectorMetadataChanged" type="(event) => void | Promise<void>">
  Fired when optional trusted Inspector metadata changes or is cleared. Event:
  `{ copilotkit, inspectorMetadata }`, where `inspectorMetadata` is an
  `InspectorMetadataV1 | undefined` snapshot. Metadata notifications are ordered,
  and a callback failure does not block later subscribers or refreshes.
</PropertyReference>

<PropertyReference name="onError" type="(event) => void | Promise<void>">
  Fired when an error occurs. Event: `{ copilotkit, error, code, context }` where `code` is a [`CopilotKitCoreErrorCode`](/reference/core/enums/CopilotKitCoreErrorCode).
</PropertyReference>

<PropertyReference name="onThreadStoreRegistered" type="(event) => void | Promise<void>">
  Fired when a thread store is registered. Event: `{ copilotkit, agentId, store }`.
</PropertyReference>

<PropertyReference name="onThreadStoreUnregistered" type="(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 }`.
</PropertyReference>

<PropertyReference name="onTrajectoryChanged" type="(event) => void | Promise<void>">
  Fired when the active trajectory ID changes, for example after
  `startTrajectory()` or `stopTrajectory()`. Event: `{ copilotkit, trajectoryId }`.
  `trajectoryId` is `null` while capture is stopped.
</PropertyReference>

## Usage [#usage]

```ts
const subscription = copilotkit.subscribe({
  onRuntimeConnectionStatusChanged: ({ status }) => {
    console.log("connection:", status);
  },
  onError: ({ code, error }) => {
    console.error(code, error);
  },
  onInspectorMetadataChanged: ({ inspectorMetadata }) => {
    console.log("project context:", inspectorMetadata);
  },
});

// later
subscription.unsubscribe();
```
