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

The code on this page comes from the showcase's 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

This sample comes from the showcase's 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: the ReasoningMessage. message.content holds the streaming text.
  • messages: the full message list.
  • isRunning: true while the agent runs.
  • isLatest: true for 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?