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.
Choose your AI backend
LangGraph (Python)
LangGraph (TypeScript)
LangGraph (FastAPI)
Langchain DeepAgents
Google ADK
Mastra
CrewAI Flows
PydanticAI
Google Antigravity
OpenAI Agents SDK (Python)
Claude Agent SDK (Python)
Claude Agent SDK (TypeScript)
Agno
AG2
LlamaIndex
AWS Strands (Python)
AWS Strands (TypeScript)
MS Agent Framework (Python)
MS Agent Framework (.NET)
MS Agent Harness (.NET)
How is this guide?