Reasoning
Surface the agent's thinking chain in the chat, with the default card or a fully custom one.
Not available for agent-spec yet
reasoning-custom demo, and agent-spec doesn't have it yet. See this page for CopilotKit's Built-in Agent, LangGraph (Python), LangGraph (TypeScript).What is this?
Some models (gpt-6-luna, Anthropic's thinking
variants) emit reasoning tokens, internal chain-of-thought traces that
explain how the model is working toward its answer. CopilotKit surfaces
these as first-class messages: when a REASONING_MESSAGE_* event arrives
from the agent, the chat renders it inline so the user can follow the
agent's thinking.
Reasoning is its own message type in the chat. Keep the built-in card, or
pass your own component to the reasoningMessage slot.
When should I use this?
Expose reasoning in the UI when you want to:
- Give users real-time insight into the agent's thought process
- Show progress on long or multi-step problems
- Debug prompt behavior during development
- Brand the reasoning card to match the rest of your product
Default reasoning rendering (zero-config)
By default, reasoning events render inside CopilotKit's built-in
CopilotChatReasoningMessage card:
- A "Thinking…" label with a pulsing indicator while the model reasons.
- Auto-expanded content so users can follow the chain of thought live.
- Collapses to "Thought for X seconds" once reasoning finishes, with a chevron to re-expand.
- Reasoning text rendered as Markdown.
No configuration is needed; if your model emits reasoning tokens, the card appears automatically:
Not available for agent-spec yet
reasoning-default demo, and agent-spec doesn't have it yet.Here's what the built-in card looks like while the model thinks through a multi-step problem:
Custom reasoning rendering
For full control over the reasoning card, pass a component to the
reasoningMessage slot on messageView. Your component receives these props:
message: theReasoningMessage.message.contentholds the streaming text.messages: the full message list.isRunning:truewhile the agent runs.isLatest:truefor the last rendered message in the list.
Import the slot type and your component in page.tsx:
import type { CopilotChatReasoningMessage } from "@copilotkit/react-core/v2";
import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2";
import { ReasoningBlock } from "./reasoning-block";Replace ReasoningBlock with your own component.
The messageView.reasoningMessage slot also accepts a sub-slot object,
{ header, contentView, toggle }. Use it to change parts of the default
card. For the props of each sub-slot, see
Customizing the Reasoning Message.
How is this guide?