CopilotKit

useCopilotKit

Low-level React hook for accessing the CopilotKit context

Overview

useCopilotKit is a low-level React hook that returns the CopilotKit context value, providing direct access to the core instance and provider-level state. It subscribes to runtime connection status changes and triggers re-renders when the connection status updates.

useCopilotKit is a low-level hook. Most applications should use higher-level hooks like useAgent or useFrontendTool instead.

Throws an error if used outside of a CopilotKit (or the <CopilotKit> wrapper component).

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 registered frontend tool directly from code — no LLM turn 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.

function ExportButton() {
  const { copilotkit } = useCopilotKit();

  // Register the tool
  useFrontendTool({
    name: "exportData",
    description: "Export data as CSV",
    parameters: [{ name: "format", type: "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 () => {
    const { result, error } = await copilotkit.runTool({
      name: "exportData",
      parameters: { format: "csv" },
    });
    if (error) console.error(error);
  };

  return <button onClick={handleExport}>Export CSV</button>;
}

runTool Parameters

Prop

Type

runTool Return Value

Prop

Type

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 of CopilotKit or the <CopilotKit> wrapper component.
  • Runtime Status Subscription: The hook subscribes to onRuntimeConnectionStatusChanged events, so components re-render when the runtime connection completes or fails.
  • Stable Core Reference: The copilotkit instance is created once per provider and remains stable across re-renders. Only the executingToolCallIds set changes as tool calls begin and complete.
  • Provider-Level Tool Tracking: executingToolCallIds is tracked at the provider level rather than in individual components. This ensures that tool execution start events fired before child components mount are not lost.

Related

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