Reference / Hooks

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.

Info

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 CopilotKitProvider (or the <CopilotKit> wrapper component).

Signature

function useCopilotKit(): CopilotKitContextValue;

Parameters

This hook takes no parameters.

Return Value

contextCopilotKitContextValue

The context object containing the core instance and provider-level state.

copilotkitCopilotKitCoreReact

The live CopilotKit core instance. This is the central coordinator that manages agents, tools, suggestions, and runtime communication. It exposes methods for:

  • Agent management (agents, getAgent)
  • Tool registration and execution
  • Suggestion configuration and retrieval
  • Runtime connection management
  • Event subscription via subscribe()

The core instance is created once per CopilotKitProvider and is stable across re-renders.

executingToolCallIdsReadonlySet<string>

Set of tool call IDs currently being executed. This is tracked at the provider level to ensure tool execution events are captured even before child components mount. This is important for scenarios like human-in-the-loop reconnection, where pending tool calls may already exist when the component tree mounts.

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

paramsCopilotKitCoreRunToolParams
namestringrequired

Name of the registered frontend tool to execute.

agentIdstring

Agent ID for tool and message scoping. Defaults to "default".

parametersRecord<string, unknown>
Default: "{}"

Arguments passed to the tool handler.

followUpstring | 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

runTool Return Value

resultCopilotKitCoreRunToolResult
toolCallIdstring

Unique ID of the tool call, matching the message added to history.

resultstring

Stringified return value from the tool handler (empty string for render-only tools).

errorstring | undefined

Error message if the handler threw. The tool result message will contain "Error: ...".

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 CopilotKitProvider 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