Headless UI

Build any UI (chat or not) on top of the CopilotKit primitives with zero UI opinions.

Not available for Langchain DeepAgents yet

The code on this page comes from the showcase's headless-complete demo, and Langchain DeepAgents doesn't have it yet. See this page for CopilotKit's Built-in Agent, LangGraph (Python), LangGraph (TypeScript).

What is this?

A headless UI gives you full control over the chat experience. You bring your own components, layout, and styling while CopilotKit handles agent communication, message management, tool-call rendering, and streaming. No <CopilotChat>, no slot overrides, just your components composed on top of the low-level hooks.

When should I use this?

Use headless UI when:

  • The slot system isn't enough: you need a completely different layout.
  • You're embedding chat into an existing UI with its own patterns.
  • You're building a non-chat surface that still talks to an agent (a dashboard, a canvas, an inspector) and want useRenderToolCall / useRenderActivityMessage on their own.
  • You want to render generative UI primitives outside of a chat entirely.

The core hooks

Three hooks power it, and they're the same ones <CopilotChat> uses internally.

  • useAgent({ agentId }): exposes the current conversation (messages, isRunning) and the run-state object.
  • useCopilotKit(): returns the runtime handle you call runAgent({ agent }) on.
  • useRenderToolCall(): returns a function that renders any registered tool call inline.

Minimal example

Start with a hand-rolled message list and composer built from useAgent + useCopilotKit:

Not available for Langchain DeepAgents yet

This sample comes from the showcase's headless-simple demo, and Langchain DeepAgents doesn't have it yet.

The message list is a plain .map() over the user and assistant text in agent.messages:

Not available for Langchain DeepAgents yet

This sample comes from the showcase's headless-simple demo, and Langchain DeepAgents doesn't have it yet.

This example does not use <CopilotChat /> or slots. The trade-off: you only get text. Tool calls, activity messages, reasoning messages, and custom before/after slots do not show up unless you wire them in yourself. The complete example wires in tool calls and activity messages.

Complete example

The complete example rebuilds the generative-UI composition from the low-level hooks directly, without importing <CopilotChatMessageView>: text, tool calls with their results, and A2UI and MCP Apps activity messages.

The MessageList component

The example's central piece is a MessageList component. It is a manual recreation of what <CopilotChatMessageView> does. MessageList calls useRenderToolCall and useRenderActivityMessage, and indexes tool results by toolCallId:

Two low-level hooks feed it:

  • useRenderToolCall(): returns the renderer for any registered tool call (per-tool via useRenderTool / useComponent, plus the wildcard from useDefaultRenderTool).
  • useRenderActivityMessage(): renders A2UI + MCP Apps activity messages for the current agent scope.

To add custom before/after slots, also call useRenderCustomMessages(). It invokes the renderCustomMessage hooks registered against the active CopilotChatConfigurationProvider, and renders "before" and "after" slots around each message.

Per-role dispatch

The role-switch mirrors CopilotChatMessageView's renderMessageBlock: assistant bodies get text and tool calls, user bodies get their text content, and activity messages route through renderActivityMessage:

Tool-call composition

For each toolCall on an assistant message, we look up the sibling tool-role message (keyed by toolCallId) and hand both to renderToolCall:

Bubble chrome

The UserBubble and AssistantBubble components are pure chrome: they receive content from MessageList and drop it into a styled container. No chat primitives are imported here:

To check it, ask the agent for the weather in Tokyo, so that it calls a tool. Your own bubble shows the reply, and the tool card renders inside it.

To answer an approval from your own UI, see Programmatic control. It shows how to resolve a pause from a button on each kind of framework.

How is this guide?