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
| Hook | Use it when you want to |
|---|---|
useFrontendTool | Give the agent a client-side tool to call (run logic in the browser), with optional inline UI. |
useRenderTool | Render the UI for a specific tool call by name (typed), without defining the tool's handler. |
useDefaultRenderTool | Provide one wildcard renderer for any tool call that has no specific renderer. |
useComponent | Register a React component as a frontend tool that the agent calls to show it. |
useHumanInTheLoop | Pause the agent on a tool call and wait for the user to approve, edit, or supply input. |
useInterrupt | Handle an agent-initiated interrupt and resume execution once the user responds. |
useRenderToolCall | Get 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 arenderto also show inline UI for the call. If the tool only shows a React component, useuseComponent. - "The agent's tool call should look like something." Use a render hook.
Use
useRenderToolto render one named tool, oruseDefaultRenderToolas the catch-all for anything you didn't render explicitly. - "The agent should stop and ask me before continuing." Use
useHumanInTheLoopfor tool-level approval/edit gates, oruseInterruptfor 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 wrapsuseFrontendTool.
The render-only hooks do not define a tool. They only render tool calls:
useRenderTooluseDefaultRenderTooluseRenderToolCall
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?