useCopilotKit
Low-level React hook for accessing the CopilotKit context
Overview
useCopilotKit is a low-level React hook that returns the CopilotKit context: the core instance and the provider-level state. The component re-renders when the runtime connection status changes.
useCopilotKit is a low-level hook. Most applications should use higher-level
hooks like useAgent or useFrontendTool instead.
Throws an error if used outside CopilotKitProvider (or the v1 <CopilotKit> wrapper, which renders it).
Signature
import { useCopilotKit } from "@copilotkit/react-core/v2";
function useCopilotKit(): CopilotKitContextValue;Parameters
This hook takes no parameters.
Return Value
Prop
Type
Usage
Accessing the Core Instance
function DebugPanel() {
const { copilotkit } = useCopilotKit();
const agents = Object.keys(copilotkit.agents ?? {});
return (
<div>
<h3>Registered Agents</h3>
<ul>
{agents.map((id) => (
<li key={id}>{id}</li>
))}
</ul>
</div>
);
}Subscribing to Core Events
function ConnectionMonitor() {
const { copilotkit } = useCopilotKit();
useEffect(() => {
const subscription = copilotkit.subscribe({
onRuntimeConnectionStatusChanged: () => {
console.log("Runtime connection status changed");
},
});
return () => {
subscription.unsubscribe();
};
}, [copilotkit]);
return null;
}Running a Tool Programmatically
copilotkit.runTool() lets you execute a frontend tool registered with useFrontendTool directly from code. No LLM turn is required. The tool's handler runs, render components appear in the UI, and both the tool call and result are added to the agent's message history.
import { useCopilotKit, useFrontendTool } from "@copilotkit/react-core/v2";
import { z } from "zod";
function ExportButton() {
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
const handleExport = async () => {
try {
const { result, error } = await copilotkit.runTool({
name: "exportData",
parameters: { format: "csv" },
});
if (error) console.error(error);
} catch (e) {
// The tool or its agent was not found.
console.error(e);
}
};
return <button onClick={handleExport}>Export CSV</button>;
}runTool Parameters
Prop
Type
runTool Return Value
Prop
Type
runTool throws Tool not found: <name> or Agent not found: <agentId> when either lookup fails. The error field does not report these failures.
Checking Tool Execution State
function ToolExecutionIndicator() {
const { executingToolCallIds } = useCopilotKit();
if (executingToolCallIds.size === 0) {
return null;
}
return <div>Executing {executingToolCallIds.size} tool call(s)...</div>;
}Behavior
- Error on Missing Provider: Throws an error if the hook is used outside
CopilotKitProvideror the v1<CopilotKit>wrapper component. - Runtime Status Subscription: The hook subscribes to
onRuntimeConnectionStatusChangedevents, so components re-render when the runtime connection completes or fails. - Stable Core Reference: The
copilotkitinstance is created once per provider and remains stable across re-renders. Only theexecutingToolCallIdsset changes as tool calls begin and complete. - Provider-Level Tool Tracking:
executingToolCallIdsis tracked at the provider level rather than in individual components. As a result, tool execution start events fired before child components mount are not lost.
How is this guide?