# CopilotKitCoreConfig

> Configuration object passed to the CopilotKitCore constructor.

## Overview [#overview]

`CopilotKitCoreConfig` is the configuration object accepted by the [`CopilotKitCore`](/reference/core/classes/CopilotKitCore) constructor. It wires the core to a CopilotRuntime endpoint and seeds it with frontend tools, suggestions, request headers, and forwarded properties.

## Import [#import]

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

## Definition [#definition]

```ts
interface CopilotKitCoreConfig {
  runtimeUrl?: string;
  runtimeTransport?: CopilotRuntimeTransport;
  deferInitialConnection?: boolean;
  agents__unsafe_dev_only?: Record<string, AbstractAgent>;
  headers?: CopilotKitHeadersSource;
  credentials?: RequestCredentials;
  messageFilter?: CopilotKitMessageFilter;
  properties?: Record<string, unknown>;
  tools?: FrontendTool<any>[];
  suggestionsConfig?: SuggestionsConfig[];
  debug?: DebugConfig;
  learning?: LearningConfig;
}
```

## Properties [#properties]

<PropertyReference name="runtimeUrl" type="string">
  The endpoint of the CopilotRuntime.
</PropertyReference>

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

<PropertyReference name="deferInitialConnection" type="boolean" default="false">
  When `true`, the constructor does not start the `/info` connection. Call
  `connect()` to start it.
</PropertyReference>

<PropertyReference name="agents__unsafe_dev_only" type="Record<string, AbstractAgent>">
  Mapping from agent name to its `AbstractAgent` instance. For development only. Production requires a CopilotRuntime.
</PropertyReference>

<PropertyReference name="headers" type="CopilotKitHeadersSource" default="{}">
  Headers appended to every HTTP request made by `CopilotKitCore`. 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. A header value of `null` or
  `undefined` leaves that header out.

  If the builder throws or rejects, the request is not sent and `onError`
  gets [`HEADER_RESOLUTION_FAILED`](/reference/core/enums/CopilotKitCoreErrorCode).

  See `setHeaders` and `resolveHeaders` on
  [`CopilotKitCore`](/reference/core/classes/CopilotKitCore).
</PropertyReference>

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

<PropertyReference name="messageFilter" type="CopilotKitMessageFilter">
  Rewrites the message list sent to runtime agents on every run. Use it when the
  agent already stores the conversation and re-sending it is waste or
  duplication. The filter changes only the request body. The transcript in the
  UI does not change. CopilotKit repairs broken tool-call pairs before it sends
  the request. Intelligence runs and suggestion runs are never filtered.
  Change it later with `setMessageFilter`.
</PropertyReference>

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

<PropertyReference name="tools" type="FrontendTool<any>[]" default="[]">
  Ordered collection of [frontend tools](/reference/core/types/FrontendTool) available to the core.
</PropertyReference>

<PropertyReference name="suggestionsConfig" type="SuggestionsConfig[]" default="[]">
  [Suggestions configuration](/reference/core/types/SuggestionsConfig) for the core.
</PropertyReference>

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

<PropertyReference name="learning" type="LearningConfig">
  Turns on interaction capture with `@copilotkit/learning`. Capture starts only
  after a `startTrajectory()` call connects to the capture channel. Change it
  later with `setLearningConfig`.
</PropertyReference>

## Usage [#usage]

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

const copilotkit = new CopilotKitCore({
  runtimeUrl: "/api/copilotkit",
  headers: { Authorization: "Bearer token" },
  properties: { userId: "user_123" },
  tools: [
    {
      name: "sayHello",
      description: "Greet the user",
      parameters: z.object({ name: z.string() }),
      handler: async ({ name }) => `Hello, ${name}!`,
    },
  ],
});
```
