# 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](/generative-ui/reasoning), [LangGraph (Python)](/langgraph-python/generative-ui/reasoning), [LangGraph (TypeScript)](/langgraph-typescript/generative-ui/reasoning).

## What is this? [#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? [#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) [#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 [#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`:

```tsx
import type { CopilotChatReasoningMessage } from "@copilotkit/react-core/v2";
import { CopilotKit, CopilotChat } from "@copilotkit/react-core/v2";
import { ReasoningBlock } from "./reasoning-block";
```

<Tabs items={['page.tsx', 'reasoning-block.tsx']}>
  <Tab value="page.tsx">
  </Tab>
  <Tab value="reasoning-block.tsx">
  </Tab>
</Tabs>

Replace `ReasoningBlock` with your own component.

<Callout type="info">
  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](/agent-spec/custom-look-and-feel/reasoning-messages#customizing-the-reasoning-message).
</Callout>

<IntegrationGrid path="generative-ui/reasoning" />
