# CopilotKit

> The root Angular service that exposes CopilotKit agents, tools, runtime state, and suggestions as signals

## Overview [#overview]

`CopilotKit` is the central injectable service for `@copilotkit/angular`. It is `providedIn: "root"`, so a single instance is shared across your application. It builds and owns the underlying `CopilotKitCore` from the [`CopilotKitConfig`](/reference/angular/functions/provideCopilotKit#parameters) you registered with [`provideCopilotKit`](/reference/angular/functions/provideCopilotKit), exposes reactive runtime state as Angular [signals](https://angular.dev/guide/signals), and provides methods to register tools, manage suggestions, and update the runtime connection.

In most apps you do not call its methods directly. The injectable functions such as [`registerFrontendTool`](/reference/angular/functions/registerFrontendTool), [`registerRenderToolCall`](/reference/angular/functions/registerRenderToolCall), and [`registerHumanInTheLoop`](/reference/angular/functions/registerHumanInTheLoop) register against the current injector and remove registrations with the same name and optional agent id when that injector is destroyed. Inject the service when you need direct access to its signals or the `core` instance.

## Accessing the service [#accessing-the-service]

Inject it from any injection context, for example a component or service.

```ts title="src/app/status.component.ts"
import { Component, inject } from "@angular/core";
import { CopilotKit } from "@copilotkit/angular";

@Component({
  selector: "app-status",
  standalone: true,
  template: `<p>Status: {{ copilotKit.runtimeConnectionStatus() }}</p>`,
})
export class StatusComponent {
  protected readonly copilotKit = inject(CopilotKit);
}
```

## Signals [#signals]

All reactive state is exposed as read-only Angular signals. Read a signal by calling it, for example `copilotKit.agents()`.

<PropertyReference name="agents" type="Signal<Record<string, AbstractAgent>>">
  The agents currently registered, keyed by agent id. Updated when the core's
  agents change. To follow one agent's messages and running state, use
  [`injectAgentStore`](/reference/angular/functions/injectAgentStore).
</PropertyReference>

<PropertyReference name="runtimeConnectionStatus" type="Signal<CopilotKitCoreRuntimeConnectionStatus>">
  The current runtime connection status: `Disconnected`, `Connecting`,
  `Connected`, or `Error`.
</PropertyReference>

<PropertyReference name="runtimeUrl" type="Signal<string | undefined>">
  The current runtime URL, or `undefined` when none is configured.
</PropertyReference>

<PropertyReference name="runtimeTransport" type="Signal<CopilotRuntimeTransport>">
  The active runtime transport: `"rest"`, `"single"`, or `"auto"`. Defaults to
  `"auto"`.
</PropertyReference>

<PropertyReference name="headers" type="Signal<Record<string, string>>">
  The headers from the last header source change. A source change is an
  `updateRuntime({ headers })` call. It updates from `onHeadersChanged`, which fires only on a real
  source change, never when a builder merely resolves a fresh token for a
  request. With a builder this can read `{}` (or a stale record) between
  source changes even though requests already carry the current token. For
  the value a builder would resolve right now, call
  `copilotKit.core.resolveHeaders()`.
</PropertyReference>

<PropertyReference name="credentials" type="Signal<RequestCredentials | undefined>">
  The current Fetch credentials mode, or `undefined` when none is configured.
</PropertyReference>

<PropertyReference name="threadEndpoints" type="Signal<ThreadEndpointRuntimeInfo | undefined>">
  Thread endpoint support advertised by the connected runtime's `/info`
  response. It is `undefined` until the runtime reports the capability.
</PropertyReference>

<PropertyReference name="audioFileTranscriptionEnabled" type="Signal<boolean>">
  Whether the connected runtime's `/info` response advertises audio file
  transcription support. It remains `false` until the runtime reports the
  capability.
</PropertyReference>

<PropertyReference name="intelligence" type="Signal<IntelligenceRuntimeInfo | undefined>">
  Intelligence runtime information advertised by `/info`, including the
  realtime WebSocket URL when available.
</PropertyReference>

<PropertyReference name="licenseStatus" type="Signal<RuntimeLicenseStatus | undefined>">
  License status reported by the connected runtime, or `undefined` before the
  runtime reports it.
</PropertyReference>

<PropertyReference name="runtimeEntitlements" type="Signal<RuntimeEntitlementResponse | undefined>">
  Structured entitlement data from the connected runtime's `/info` response, or
  `undefined` before the runtime reports it.
</PropertyReference>

<PropertyReference name="runtimeEntitlementRetryPending" type="Signal<boolean>">
  `true` while the core still waits for its one retry of a failed entitlement
  lookup.
</PropertyReference>

<PropertyReference name="suggestionsByAgent" type="Signal<Record<string, CopilotKitCoreGetSuggestionsResult>>">
  Suggestions keyed by agent id. Each value is
  `{ suggestions: Suggestion[]; isLoading: boolean }`.
</PropertyReference>

<PropertyReference name="toolCallRenderConfigs" type="Signal<RenderToolCallConfig[]>">
  All registered tool call renderers, including built-in renderers (for example
  A2UI).
</PropertyReference>

<PropertyReference name="clientToolCallRenderConfigs" type="Signal<FrontendToolConfig[]>">
  All registered client (frontend) tools, including built-in tools (for example
  the open generative UI tool when enabled).
</PropertyReference>

<PropertyReference name="humanInTheLoopToolRenderConfigs" type="Signal<HumanInTheLoopConfig[]>">
  All registered human-in-the-loop tool configs.
</PropertyReference>

<PropertyReference name="activityMessageRenderConfigs" type="Signal<RenderActivityMessageConfig[]>">
  All registered activity message renderers, including built-in renderers.
</PropertyReference>

## Properties [#properties]

<PropertyReference name="core" type="CopilotKitCore">
  The underlying `CopilotKitCore` instance from `@copilotkit/core`. Use it for
  lower-level operations that the service does not wrap, such as adding context
  or subscribing to core events.
</PropertyReference>

<PropertyReference name="defaultToolRenderingEnabled" type="boolean">
  Whether the text-only fallback renderer for otherwise unknown tools was
  enabled with `defaultToolRendering: true`.
</PropertyReference>

## Methods [#methods]

<PropertyReference name="addFrontendTool" type="(tool: FrontendToolConfig & { injector: Injector }) => void">
  Register a client-side tool. The handler is rebound to run inside the provided
  `injector`, so it can use `inject()`. Prefer
  [`registerFrontendTool`](/reference/angular/functions/registerFrontendTool),
  which supplies the injector and removes registrations with the same name and
  optional agent id on destroy.
</PropertyReference>

<PropertyReference name="addRenderToolCall" type="(renderConfig: RenderToolCallConfig) => void">
  Register a renderer for a tool call. Prefer
  [`registerRenderToolCall`](/reference/angular/functions/registerRenderToolCall)
  for injector-scoped, name-based cleanup.
</PropertyReference>

<PropertyReference name="addRenderActivityMessage" type="(renderConfig: RenderActivityMessageConfig) => void">
  Register a renderer for an agent activity message type.
</PropertyReference>

<PropertyReference name="removeRenderActivityMessage" type="(renderConfig: RenderActivityMessageConfig) => void">
  Remove a dynamically registered activity renderer by object identity.
</PropertyReference>

<PropertyReference name="addHumanInTheLoop" type="(humanInTheLoopTool: HumanInTheLoopConfig) => void">
  Register a human-in-the-loop tool. The tool pauses the run until the user
  responds. Prefer
  [`registerHumanInTheLoop`](/reference/angular/functions/registerHumanInTheLoop)
  for injector-scoped, name-based cleanup.
</PropertyReference>

<PropertyReference name="addSuggestionsConfig" type="(config: SuggestionsConfig) => string">
  Add a suggestions configuration and return its id.
</PropertyReference>

<PropertyReference name="removeSuggestionsConfig" type="(id: string) => void">
  Remove a previously added suggestions configuration by id.
</PropertyReference>

<PropertyReference name="getSuggestions" type="(agentId: string) => CopilotKitCoreGetSuggestionsResult">
  Return the current suggestions for an agent as
  `{ suggestions, isLoading }`. Reads from `suggestionsByAgent` first, falling
  back to the core.
</PropertyReference>

<PropertyReference name="reloadSuggestions" type="(agentId: string) => void">
  Regenerate the suggestions for an agent.
</PropertyReference>

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

<PropertyReference name="removeTool" type="(toolName: string, agentId?: string) => void">
  Remove a tool by name (optionally scoped to an `agentId`) and drop its
  matching client tool, human-in-the-loop, and tool call render configs.
</PropertyReference>

<PropertyReference name="getAgent" type="(agentId: string) => AbstractAgent | undefined">
  Return the agent registered under `agentId`, or `undefined`.
</PropertyReference>

<PropertyReference name="updateRuntime" type="(options: { runtimeUrl?: string; runtimeTransport?: CopilotRuntimeTransport; headers?: CopilotKitHeadersSource; credentials?: RequestCredentials; messageFilter?: CopilotKitMessageFilter; properties?: Record<string, unknown>; agents?: Record<string, AbstractAgent>; selfManagedAgents?: Record<string, AbstractAgent> }) => void">
  Update the runtime connection at runtime. Only the fields you pass are
  applied. The options are:

  - `runtimeUrl`: the runtime endpoint URL. Also updates the `runtimeUrl` signal.
  - `runtimeTransport`: `"rest"`, `"single"`, or `"auto"`. Also updates the `runtimeTransport` signal.
  - `headers`: the header source, described below. Also updates the `headers` signal.
  - `credentials`: the Fetch credentials mode. Also updates the `credentials` signal. Passing `undefined` clears it.
  - `messageFilter`: the filter for the messages sent on each run. Passing `undefined` clears it.
  - `properties`: the properties sent to the runtime.
  - `agents`: the agents to register.
  - `selfManagedAgents`: the self-managed agents to register.

  When you pass `agents` or `selfManagedAgents`, CopilotKit replaces the
  registered agents with both sets. A set that you leave out comes from
  `provideCopilotKit`.

  `headers` accepts a record, a sync builder, or an async builder, the same
  as [`provideCopilotKit`](/reference/angular/functions/provideCopilotKit).
  Re-passing the same builder function is a no-op. On a user switch, call
  `updateRuntime({ headers })` with a new function (or a record), or remount,
  so Inspector metadata and thread lists reload for the new user (this does
  not refetch the runtime's `/info`). Passing a record equal (by value) to
  the currently applied one is also a no-op.
</PropertyReference>

## Usage [#usage]

### Read agents and connection status in a template [#read-agents-and-connection-status-in-a-template]

```ts title="src/app/agents-panel.component.ts"
import { Component, inject } from "@angular/core";
import { CopilotKit } from "@copilotkit/angular";

@Component({
  selector: "app-agents-panel",
  standalone: true,
  template: `
    <p>Status: {{ copilotKit.runtimeConnectionStatus() }}</p>
    <ul>
      @for (id of agentIds(); track id) {
        <li>{{ id }}</li>
      }
    </ul>
  `,
})
export class AgentsPanelComponent {
  protected readonly copilotKit = inject(CopilotKit);
  protected readonly agentIds = () => Object.keys(this.copilotKit.agents());
}
```

### Switch the runtime URL at runtime [#switch-the-runtime-url-at-runtime]

```ts title="src/app/runtime-switcher.component.ts"
import { Component, inject } from "@angular/core";
import { CopilotKit } from "@copilotkit/angular";

@Component({
  selector: "app-runtime-switcher",
  standalone: true,
  template: `<button (click)="useStaging()">Use staging</button>`,
})
export class RuntimeSwitcherComponent {
  private readonly copilotKit = inject(CopilotKit);

  protected useStaging(): void {
    this.copilotKit.updateRuntime({
      runtimeUrl: "https://staging.example.com/api/copilotkit",
    });
  }
}
```

### Reload suggestions for an agent [#reload-suggestions-for-an-agent]

```ts title="src/app/suggestions.component.ts"
import { Component, inject } from "@angular/core";
import { CopilotKit } from "@copilotkit/angular";

@Component({
  selector: "app-suggestions",
  standalone: true,
  template: `<button (click)="refresh()">Refresh suggestions</button>`,
})
export class SuggestionsComponent {
  private readonly copilotKit = inject(CopilotKit);

  protected refresh(): void {
    this.copilotKit.reloadSuggestions("default");
  }
}
```
