useCopilotKit.mdx

title	useCopilotKit
description	Low-level Vue 3 composable for accessing the CopilotKit context

Overview

useCopilotKit is a low-level Vue 3 composable that injects the CopilotKit provider context, giving direct access to the core instance and provider-level reactive state. Because the values it returns are Vue refs, reading them inside a computed, watch, or template keeps your code reactive to runtime changes such as connection status or in-flight tool calls.

`useCopilotKit` is a low-level composable. Most applications should use higher-level composables like `useAgent` or `useFrontendTool` instead.

Throws an error if called outside of a CopilotKitProvider. The composable injects the provider context, so it must run within a component tree that has CopilotKitProvider as an ancestor.

Signature

import { useCopilotKit } from "@copilotkit/vue/v2";

function useCopilotKit(): CopilotKitContextValue;

Parameters

This composable takes no parameters.

Return Value

The composable returns the CopilotKitContextValue object. Every member is a Vue ref (or computed ref), so access the underlying value with .value (or let the template unwrap it for you).

A `shallowRef` holding the live CopilotKit core instance. `CopilotKitCoreVue` extends the framework-agnostic `CopilotKitCore`, so `copilotkit.value` is the central coordinator that manages agents, tools, suggestions, and runtime communication. It exposes: - Agent management (`agents`, `getAgent`) - Tool registration and execution (`runTool`) - Suggestion configuration and retrieval - Runtime connection management - Event subscription via `subscribe()`

The core instance is created once per CopilotKitProvider and is stable for the lifetime of the provider.

A ref to the set of tool call IDs currently being executed. This is tracked at the provider level so that tool execution events are captured even before child components mount, which matters for scenarios like human-in-the-loop reconnection where pending tool calls may already exist when the component tree mounts. A computed ref to the A2UI theme configured on the provider, or `undefined` if no theme was supplied. A computed ref to the A2UI component catalog configured on the provider. A computed ref to the component rendered while an A2UI surface is loading. A computed ref indicating whether the A2UI schema is included.

Usage

Accessing the Core Instance

<script setup lang="ts">
import { computed } from "vue";
import { useCopilotKit } from "@copilotkit/vue/v2";

const { copilotkit } = useCopilotKit();

const agentIds = computed(() => Object.keys(copilotkit.value.agents ?? {}));
</script>

<template>
  <div>
    <h3>Registered Agents</h3>
    <ul>
      <li v-for="id in agentIds" :key="id">{{ id }}</li>
    </ul>
  </div>
</template>

Subscribing to Core Events

Subscribe in onMounted and tear the subscription down in onUnmounted.

<script setup lang="ts">
import { onMounted, onUnmounted } from "vue";
import { useCopilotKit } from "@copilotkit/vue/v2";

const { copilotkit } = useCopilotKit();

let subscription: { unsubscribe: () => void } | undefined;

onMounted(() => {
  subscription = copilotkit.value.subscribe({
    onRuntimeConnectionStatusChanged: () => {
      console.log("Runtime connection status changed");
    },
  });
});

onUnmounted(() => {
  subscription?.unsubscribe();
});
</script>

Running a Tool Programmatically

copilotkit.value.runTool() lets you execute a registered frontend tool directly from code, with no LLM turn required. The tool's handler runs, render components appear in the UI, and both the tool call and its result are added to the agent's message history.

<script setup lang="ts">
import { z } from "zod";
import { useCopilotKit, useFrontendTool } from "@copilotkit/vue/v2";

const { copilotkit } = useCopilotKit();

// Register the tool
useFrontendTool({
  name: "exportData",
  description: "Export data as CSV",
  parameters: z.object({ format: z.string() }),
  handler: async ({ format }) => {
    const csv = await generateCsv(format);
    downloadFile(csv);
    return `Exported as ${format}`;
  },
});

// Trigger it from a button, no LLM needed
async function handleExport() {
  try {
    const { result, error } = await copilotkit.value.runTool({
      name: "exportData",
      parameters: { format: "csv" },
    });
    // `error` is set when the handler itself throws.
    if (error) console.error(error);
  } catch (err) {
    // `runTool` rejects if the tool (or its agent) cannot be found.
    console.error(err);
  }
}
</script>

<template>
  <button @click="handleExport">Export CSV</button>
</template>

runTool Parameters

Name of the registered frontend tool to execute. Agent ID for tool and message scoping. Defaults to `"default"`.

<PropertyReference name="parameters" type="Record<string, unknown>" default="{}"

Arguments passed to the tool handler.

Controls whether an LLM follow-up is triggered after execution: - `false`, execute tool and stop (default) - `"generate"`, trigger an agent run so the LLM responds to the tool result - Any other string, add a user message with this text, then trigger an agent run

runTool Return Value

Unique ID of the tool call, matching the message added to history. Stringified return value from the tool handler (empty string for render-only tools). Error message if the handler threw. The tool result message will contain `"Error: ..."`. Note that `runTool` itself **rejects** (throws) when the tool or its agent cannot be found — those lookup failures surface as a rejected promise, not via this field — so wrap the call in `try`/`catch` as well as checking `error`.

Checking Tool Execution State

Because executingToolCallIds is a ref, drive UI off it with a computed or read it directly in the template.

<script setup lang="ts">
import { computed } from "vue";
import { useCopilotKit } from "@copilotkit/vue/v2";

const { executingToolCallIds } = useCopilotKit();

const executingCount = computed(() => executingToolCallIds.value.size);
</script>

<template>
  <div v-if="executingCount > 0">
    Executing {{ executingCount }} tool call(s)...
  </div>
</template>

Behavior

• Error on missing provider: Throws useCopilotKit must be used within CopilotKitProvider if the composable is called outside of a CopilotKitProvider.
• Refs, not plain values: Every returned member is a Vue ref or computed ref. Read copilotkit.value to reach the core instance and executingToolCallIds.value to reach the live set. Keep usage reactive with computed, watch, or template bindings.
• Stable core reference: The copilotkit ref is a shallowRef created once per provider and remains stable for the provider's lifetime. Only executingToolCallIds changes as tool calls begin and complete.
• Provider-level tool tracking: executingToolCallIds is tracked at the provider level rather than in individual components, so tool execution start events fired before child components mount are not lost.

Related

• useAgent -- High-level composable for accessing agent instances
• useFrontendTool -- Register frontend tools that runTool() can execute
• CopilotKitProvider -- The provider component that creates the context