# @copilotkit/core

> Framework-agnostic TypeScript client for CopilotKit. Runs anywhere JavaScript runs.

`@copilotkit/core` is the framework-agnostic TypeScript client at the heart of CopilotKit. It connects to a CopilotRuntime over the AG-UI protocol, manages agents, frontend tools, shared context, and suggestions, and emits state changes to subscribers. It has no UI or React dependency, so it runs in browsers, Node, workers, and inside the React, Angular, and vanilla bindings.

## Install [#install]

```bash
npm install @copilotkit/core zod
```

## Quick start [#quick-start]

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

const copilotkit = new CopilotKitCore({
  runtimeUrl: "/api/copilotkit",
});

// Register a frontend tool the agent can call.
copilotkit.addTool({
  name: "showAlert",
  parameters: z.object({ message: z.string() }),
  handler: async ({ message }) => {
    window.alert(message);
    return "Alert shown";
  },
});

// Agents load after the runtime responds.
const sub = copilotkit.subscribe({
  onAgentsChanged: async ({ agents }) => {
    const agent = agents["default"];
    if (!agent) return;
    sub.unsubscribe();
    agent.addMessage({
      id: crypto.randomUUID(),
      role: "user",
      content: "Show an alert that says hi",
    });
    await copilotkit.runAgent({ agent });
  },
});
```

## Reference [#reference]

- [CopilotKitCore](/reference/core/classes/CopilotKitCore): the main client class.
- [ProxiedCopilotRuntimeAgent](/reference/core/classes/ProxiedCopilotRuntimeAgent): AG-UI agent that proxies a CopilotRuntime agent.
- [CopilotKitCoreConfig](/reference/core/types/CopilotKitCoreConfig): options accepted by the `CopilotKitCore` constructor.
- [ProxiedCopilotRuntimeAgentConfig](/reference/core/types/ProxiedCopilotRuntimeAgentConfig): options accepted by the `ProxiedCopilotRuntimeAgent` constructor.
- [FrontendTool](/reference/core/types/FrontendTool): shape of a tool registered with `addTool`.
- [CopilotKitCoreSubscriber](/reference/core/types/CopilotKitCoreSubscriber): callbacks passed to `subscribe`.
- [Suggestion](/reference/core/types/Suggestion) / [SuggestionsConfig](/reference/core/types/SuggestionsConfig): suggestion data and configuration.
- [ToolCallStatus](/reference/core/enums/ToolCallStatus): tool-call lifecycle states.
- [CopilotKitCoreErrorCode](/reference/core/enums/CopilotKitCoreErrorCode): error codes surfaced through `onError`.
- [CopilotKitCoreRuntimeConnectionStatus](/reference/core/enums/CopilotKitCoreRuntimeConnectionStatus): runtime connection states.
