Reasoning
Surface the agent's thinking chain in the chat, with the default card or a fully custom one.
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:
const AGENT_ID = "reasoning-default";
export default function ReasoningDefaultDemo() {
return (
<CopilotKit runtimeUrl="/api/copilotkit" agent={AGENT_ID}>
<div className="flex justify-center items-center h-screen w-full">
<div className="h-full w-full max-w-4xl">
<Chat />
</div>
</div>
</CopilotKit>
);
}
function Chat() {
useReasoningDefaultSuggestions();
return <CopilotChat agentId={AGENT_ID} className="h-full rounded-2xl" />;
}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";const AGENT_ID = "reasoning-custom";
export default function ReasoningCustomDemo() {
return (
<CopilotKit runtimeUrl="/api/copilotkit" agent={AGENT_ID}>
<div className="flex justify-center items-center h-screen w-full">
<div className="h-full w-full max-w-4xl">
<Chat />
</div>
</div>
</CopilotKit>
);
}
function Chat() {
useReasoningCustomSuggestions();
return (
<CopilotChat
agentId={AGENT_ID}
className="h-full rounded-2xl"
messageView={{
reasoningMessage:
ReasoningBlock as unknown as typeof CopilotChatReasoningMessage,
}}
/>
);
}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?