Which Hook for Which Job

Choose the right CopilotKit v2 hook for tools, rendering, human review, and custom chat surfaces.

CopilotKit v2 has a focused set of hooks for letting the agent do things in your app and for rendering what it does. They split into two groups: hooks that register behavior, and hooks that register how a tool call looks in the chat. Use this page as the quick map, then follow each hook to its entry in the hooks reference.

The 30-second version

HookUse it when you want to
useFrontendToolGive the agent a client-side tool to call (run logic in the browser), with optional inline UI.
useRenderToolRender the UI for a specific tool call by name (typed), without defining the tool's handler.
useDefaultRenderToolProvide one wildcard renderer for any tool call that has no specific renderer.
useComponentRegister a React component as a frontend tool that the agent calls to show it.
useHumanInTheLoopPause the agent on a tool call and wait for the user to approve, edit, or supply input.
useInterruptHandle an agent-initiated interrupt and resume execution once the user responds.
useRenderToolCallGet a render function for tool calls to drive your own custom chat surface (headless).

How to choose

Start with the verb.

  • "The agent should run something in my app." Use useFrontendTool. You define the tool's schema and handler; the agent calls it. Add a render to also show inline UI for the call. If the tool only shows a React component, use useComponent.
  • "The agent's tool call should look like something." Use a render hook. Use useRenderTool to render one named tool, or useDefaultRenderTool as the catch-all for anything you didn't render explicitly.
  • "The agent should stop and ask me before continuing." Use useHumanInTheLoop for tool-level approval/edit gates, or useInterrupt for agent-driven interrupts you resume with user input. See Human in the Loop for both patterns.
  • "I'm building my own chat UI." Use useRenderToolCall. It returns the renderer function so you can place tool-call output anywhere in a headless layout.

Tool vs. renderer

Two hooks in this set register a tool the agent can call:

  • useFrontendTool: you give the schema and the handler.
  • useComponent: a tool that renders your component. It wraps useFrontendTool.

The render-only hooks do not define a tool. They only render tool calls:

  • useRenderTool
  • useDefaultRenderTool
  • useRenderToolCall

The tool call can come from your frontend or from the agent. So you can pair a backend tool with useRenderTool and never write a handler on the client.

How is this guide?