# CopilotKitCore

> Framework-agnostic client that connects to a CopilotRuntime and manages agents, tools, context, and suggestions.

## Overview [#overview]

`CopilotKitCore` is the main entry point of [`@copilotkit/core`](/reference/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]

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

## Constructor [#constructor]

```ts
new CopilotKitCore(config: CopilotKitCoreConfig)
```

<PropertyReference name="config" type="CopilotKitCoreConfig" required>
  Configuration object. See [CopilotKitCoreConfig](/reference/core/types/CopilotKitCoreConfig) for the full type.

  <PropertyReference name="runtimeUrl" type="string">
    Endpoint of the CopilotRuntime that requests are sent to.
  </PropertyReference>

  <PropertyReference name="runtimeTransport" type='"rest" | "single" | "auto"' default="auto">
    Transport style for runtime endpoints. `"auto"` probes REST and falls back to single-route.
  </PropertyReference>

  <PropertyReference name="headers" type="Record<string, string> | (() => Record<string, string>) | (() => Promise<Record<string, string>>)" default="{}">
    Headers appended to every HTTP request made by the core. Pass a record for
    static headers, or a function (sync or async) to build them fresh. A
    builder runs when each request is sent, so a refreshed token is always
    used. Cache inside the builder. A builder that calls the network every
    time adds one call per request. If the builder throws or rejects, the
    request is not sent and `onError` gets `HEADER_RESOLUTION_FAILED`.
  </PropertyReference>

  <PropertyReference name="credentials" type="RequestCredentials">
    Credentials mode for fetch requests (e.g. `"include"` for HTTP-only cookies).
  </PropertyReference>

  <PropertyReference name="properties" type="Record<string, unknown>" default="{}">
    Values sent as `forwardedProps` to the AG-UI agent.
  </PropertyReference>

  <PropertyReference name="tools" type="FrontendTool<any>[]" default="[]">
    Frontend tools available to the core. See [FrontendTool](/reference/core/types/FrontendTool).
  </PropertyReference>

  <PropertyReference name="suggestionsConfig" type="SuggestionsConfig[]" default="[]">
    Suggestion configurations registered at construction. See [SuggestionsConfig](/reference/core/types/SuggestionsConfig).
  </PropertyReference>

  <PropertyReference name="agents__unsafe_dev_only" type="Record<string, AbstractAgent>" default="{}">
    Local agent instances keyed by name. These agents run in the browser and talk to their AG-UI endpoints directly, with no CopilotRuntime. The React `selfManagedAgents` prop uses this path in production.
  </PropertyReference>

  <PropertyReference name="debug" type="DebugConfig">
    Enables debug logging for the client-side event pipeline.
  </PropertyReference>
</PropertyReference>

## Methods [#methods]

### Agents [#agents]

<PropertyReference name="getAgent" type="(id: string) => AbstractAgent | undefined" required>
  Returns the agent registered under `id`, or `undefined` if none exists.
</PropertyReference>

<PropertyReference name="runAgent" type="(params: CopilotKitCoreRunAgentParams) => Promise<RunAgentResult>" required>
  Runs an agent against the runtime, streaming events and executing any frontend tool calls it produces.
</PropertyReference>

<PropertyReference name="connectAgent" type="(params: CopilotKitCoreConnectAgentParams) => Promise<RunAgentResult>" required>
  Connects to an agent to receive its current state and message stream without starting a new run.
</PropertyReference>

<PropertyReference name="stopAgent" type="(params: CopilotKitCoreStopAgentParams) => void" required>
  Aborts the current run for the given agent.
</PropertyReference>

<PropertyReference name="registerProxiedAgent" type="(params) => { agent; unregister }" required>
  Registers a [ProxiedCopilotRuntimeAgent](/reference/core/classes/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.
</PropertyReference>

<PropertyReference name="addAgent__unsafe_dev_only" type="(params: CopilotKitCoreAddAgentParams) => void" required>
  Adds a local agent instance. Development only.
</PropertyReference>

<PropertyReference name="removeAgent__unsafe_dev_only" type="(id: string) => void" required>
  Removes a local agent by id. Development only.
</PropertyReference>

<PropertyReference name="setAgents__unsafe_dev_only" type="(agents: Record<string, AbstractAgent>) => void" required>
  Replaces the full set of local agents. Development only.
</PropertyReference>

### Tools [#tools]

<PropertyReference name="addTool" type="(tool: FrontendTool) => void" required>
  Registers a frontend tool the agent can call. If an earlier `addTool` call registered a tool with the same name and `agentId`, this call does nothing and logs a warning. A tool with the same name and `agentId` from the `tools` config is replaced by this one. See [FrontendTool](/reference/core/types/FrontendTool).
</PropertyReference>

<PropertyReference name="removeTool" type="(id: string, agentId?: string) => void" required>
  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.
</PropertyReference>

<PropertyReference name="getTool" type="(params: CopilotKitCoreGetToolParams) => FrontendTool<any> | undefined" required>
  Returns a registered tool, or `undefined` if not found.
</PropertyReference>

<PropertyReference name="setTools" type="(tools: FrontendTool<any>[]) => void" required>
  Replaces the tools set by the `tools` config. Tools registered with `addTool` stay registered.
</PropertyReference>

<PropertyReference name="runTool" type="(params: CopilotKitCoreRunToolParams) => Promise<CopilotKitCoreRunToolResult>" required>
  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`.
</PropertyReference>

### Context [#context]

<PropertyReference name="addContext" type="(context: Context) => string" required>
  Adds a context entry shared with the agent and returns its generated id.
</PropertyReference>

<PropertyReference name="removeContext" type="(id: string) => void" required>
  Removes a context entry by id.
</PropertyReference>

### Suggestions [#suggestions]

<PropertyReference name="addSuggestionsConfig" type="(config: SuggestionsConfig) => string" required>
  Registers a suggestion configuration and returns its generated id.
</PropertyReference>

<PropertyReference name="removeSuggestionsConfig" type="(id: string) => void" required>
  Removes a suggestion configuration by id.
</PropertyReference>

<PropertyReference name="getSuggestions" type="(agentId: string) => CopilotKitCoreGetSuggestionsResult" required>
  Returns the current suggestions and loading state for an agent.
</PropertyReference>

<PropertyReference name="reloadSuggestions" type="(agentId: string) => void" required>
  Re-generates suggestions for an agent.
</PropertyReference>

<PropertyReference name="clearSuggestions" type="(agentId: string) => void" required>
  Clears the current suggestions for an agent.
</PropertyReference>

### Subscriptions [#subscriptions]

<PropertyReference name="subscribe" type="(subscriber: CopilotKitCoreSubscriber) => CopilotKitCoreSubscription" required>
  Subscribes to core lifecycle events (agents changed, context changed, errors, runtime connection status, and more). Returns a subscription with an `unsubscribe()` method. See [CopilotKitCoreSubscriber](/reference/core/types/CopilotKitCoreSubscriber).
</PropertyReference>

<PropertyReference name="subscribeToAgentWithOptions" type="(agent, subscriber, options?) => CopilotKitCoreSubscription" required>
  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.
</PropertyReference>

### Inspector metadata [#inspector-metadata]

<PropertyReference name="refreshInspectorMetadata" type="() => Promise<void>" required>
  Refreshes optional trusted Inspector metadata without reconnecting runtime
  agents. Core makes the request only while connected to a runtime that reports
  `inspectorMetadata: true` from its runtime-info response. Each refresh has a
  five-second deadline. Route, timeout, and parse failures resolve with metadata
  absent; they do not change the runtime connection state.
</PropertyReference>

### Configuration [#configuration]

<PropertyReference name="setRuntimeUrl" type="(runtimeUrl: string | undefined) => void" required>
  Updates the runtime endpoint.
</PropertyReference>

<PropertyReference name="setRuntimeTransport" type="(runtimeTransport: CopilotRuntimeTransport) => void" required>
  Updates the transport style.
</PropertyReference>

<PropertyReference name="setHeaders" type="(headers: CopilotKitHeadersSource) => void" required>
  Replaces the request headers and re-applies them to existing agents. Pass a
  record, a sync builder, or an async builder. See the
  [`headers`](/reference/core/types/CopilotKitCoreConfig) config option. For a
  record, any key whose value is `null` or `undefined` is dropped from the
  stored headers, which is the supported way to clear a header (e.g.
  `Authorization` on logout). An empty string remains a valid header value and
  is preserved. Core clears trusted Inspector metadata before refreshing it
  with the new headers, and `onHeadersChanged` subscribers are notified.

  This is a no-op (no Inspector refresh, no `onHeadersChanged`) when the
  current source is also a record with equal normalized values. A new builder
  function, a record with different values, or a record↔builder switch all
  count as a change. A builder resolving a new token on its own (a rotated
  auth token, for example) never fires `onHeadersChanged` and never re-applies
  headers on its own. The new token is used the next time a request is sent. Key
  reactive work off a change in headers, not off header values or object
  identity.
</PropertyReference>

<PropertyReference name="resolveHeaders" type="() => Record<string, string> | Promise<Record<string, string>>" required>
  Resolves the current headers: synchronous for a record or a sync builder, a
  promise for an async builder. Concurrent calls share one in-flight builder
  call. Use this to get the value a builder would produce right now. The
  `headers` getter below only reflects the last resolved value.
</PropertyReference>

<PropertyReference name="setCredentials" type="(credentials: RequestCredentials | undefined) => void" required>
  Replaces the fetch credentials mode and re-applies it to existing agents. Core clears trusted Inspector metadata before refreshing it with the new mode.
</PropertyReference>

<PropertyReference name="setMessageFilter" type="(messageFilter: CopilotKitMessageFilter | undefined) => void" required>
  Replaces the filter applied to the outbound message list and re-applies it to existing agents. Agents discovered later pick it up too, so a filter set before `/info` lands is not lost. Pass `undefined` to go back to sending the full thread.
</PropertyReference>

<PropertyReference name="setProperties" type="(properties: Record<string, unknown>) => void" required>
  Replaces the forwarded properties sent to agents.
</PropertyReference>

<PropertyReference name="setDebug" type="(debug: DebugConfig | undefined) => void" required>
  Toggles debug logging for the client-side event pipeline.
</PropertyReference>

<PropertyReference name="setDefaultThrottleMs" type="(value: number | undefined) => void" required>
  Sets the default throttle interval (ms) used by `subscribeToAgentWithOptions`. Invalid values are ignored.
</PropertyReference>

### State queries [#state-queries]

<PropertyReference name="getStateByRun" type="(agentId, threadId, runId) => State | undefined" required>
  Returns the agent state snapshot recorded for a specific run.
</PropertyReference>

<PropertyReference name="getRunIdForMessage" type="(agentId, threadId, messageId) => string | undefined" required>
  Returns the run id that produced a given message.
</PropertyReference>

<PropertyReference name="getRunIdsForThread" type="(agentId, threadId) => string[]" required>
  Returns the ordered run ids recorded for a thread.
</PropertyReference>

### Properties (read-only) [#properties-read-only]

<PropertyReference name="agents" type="Readonly<Record<string, AbstractAgent>>" required>
  The currently registered agents, keyed by id.
</PropertyReference>

<PropertyReference name="tools" type="Readonly<FrontendTool<any>[]>" required>
  The currently registered frontend tools.
</PropertyReference>

<PropertyReference name="context" type="Readonly<Record<string, Context>>" required>
  The current shared context entries, keyed by id.
</PropertyReference>

<PropertyReference name="runtimeUrl" type="string | undefined" required>
  The configured runtime endpoint.
</PropertyReference>

<PropertyReference name="runtimeConnectionStatus" type="CopilotKitCoreRuntimeConnectionStatus" required>
  The current runtime connection status. See [CopilotKitCoreRuntimeConnectionStatus](/reference/core/enums/CopilotKitCoreRuntimeConnectionStatus).
</PropertyReference>

<PropertyReference name="inspectorMetadata" type="InspectorMetadataV1 | undefined" required>
  The latest trusted, parsed metadata from the connected runtime. It is
  `undefined` when the runtime does not advertise the capability, the optional
  request fails, or the runtime has no supported metadata. Subscribe with
  [`onInspectorMetadataChanged`](/reference/core/types/CopilotKitCoreSubscriber#properties)
  to react to changes.
</PropertyReference>

<PropertyReference name="headers / credentials / properties" type="getter" required>
  Snapshots of the configured headers, credentials mode, and forwarded
  properties. `headers` is the last resolved value. With a builder, this may
  be `{}` before the first request, or stale between requests. Call
  `resolveHeaders()` for the value a builder would produce right now.
</PropertyReference>

## Usage [#usage]

A tool's `parameters` take any Standard Schema. This sample uses `zod`.

```ts
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 [#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 from runtime fetches, agent runs, tool runs, and subscriber callbacks go to the `onError` subscriber callback with a [CopilotKitCoreErrorCode](/reference/core/enums/CopilotKitCoreErrorCode). The method that failed does not throw them. The exception is `runTool()`: 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 `setHeaders` call 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_only` APIs**: the `*Agent__unsafe_dev_only` methods register local agents that run in the browser and talk to their AG-UI endpoints directly, with no CopilotRuntime. The React `selfManagedAgents` prop uses this path in production.
