showcase/shell-docs/src/content/reference/vue/hooks/useCopilotKit.mdx
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.
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.
import { useCopilotKit } from "@copilotkit/vue/v2";
function useCopilotKit(): CopilotKitContextValue;
This composable takes no parameters.
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).
The core instance is created once per CopilotKitProvider and is stable for the lifetime of the provider.
</PropertyReference>
<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>
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>
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<PropertyReference name="parameters" type="Record<string, unknown>" default="{}"
Arguments passed to the tool handler. </PropertyReference>
<PropertyReference name="followUp" type="string | false" default="false"> 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 </PropertyReference> </PropertyReference>runTool Return ValueBecause 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>
useCopilotKit must be used within CopilotKitProvider if the composable is called outside of a CopilotKitProvider.copilotkit.value to reach the core instance and executingToolCallIds.value to reach the live set. Keep usage reactive with computed, watch, or template bindings.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.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.useAgent -- High-level composable for accessing agent instancesuseFrontendTool -- Register frontend tools that runTool() can executeCopilotKitProvider -- The provider component that creates the context