Headless UI
Build any UI (chat or not) on top of the CopilotKit primitives with zero UI opinions.
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/useRenderActivityMessageon 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 callrunAgent({ 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:
const { agent } = useAgent({ agentId: "headless-simple" });
const { copilotkit } = useCopilotKit();
const [input, setInput] = useState("");
const send = (text: string) => {
const trimmed = text.trim();
if (!trimmed || agent.isRunning) return;
agent.addMessage({
id: crypto.randomUUID(),
role: "user",
content: trimmed,
});
setInput("");
void copilotkit.runAgent({ agent }).catch(() => {});
};The message list is a plain .map() over the user and assistant text in agent.messages:
{visible.map((m) =>
m.role === "user" ? (
<UserBubble key={m.id} content={m.content} />
) : (
<AssistantBubble key={m.id} content={m.content} />
),
)}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:
const renderToolCall = useRenderToolCall();
const { renderActivityMessage } = useRenderActivityMessage();
// Index tool results by their originating tool-call id so each tool-call
// card can hand the matching ToolMessage to `useRenderToolCall`.
// Without this the renderer can't see a result and the card stays in the
// "in-progress" state forever.
const toolMessagesByCallId = useMemo(() => {
const map = new Map<string, ToolMessage>();
for (const m of messages) {
if (m.role === "tool" && "toolCallId" in m && m.toolCallId) {
map.set(m.toolCallId, m as ToolMessage);
}
}
return map;
}, [messages]);Two low-level hooks feed it:
useRenderToolCall(): returns the renderer for any registered tool call (per-tool viauseRenderTool/useComponent, plus the wildcard fromuseDefaultRenderTool).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:
{messages.map((m) => {
if (m.role === "user") {
// Cast through the local input shape — UserBubble accepts a
// simplified version of the ag-ui content union.
return (
<UserBubble
key={m.id}
content={m.content as Parameters<typeof UserBubble>[0]["content"]}
/>
);
}
if (m.role === "assistant") {
const toolCalls =
"toolCalls" in m && Array.isArray(m.toolCalls) ? m.toolCalls : [];
return (
<AssistantBubble
key={m.id}
content={typeof m.content === "string" ? m.content : undefined}
>
{toolCalls.map((tc) => {
const toolMessage = toolMessagesByCallId.get(tc.id);
const node = renderToolCall({
toolCall: tc,
toolMessage,
});
return node ? <div key={tc.id}>{node}</div> : null;
})}
</AssistantBubble>
);
}
if (m.role === "activity") {
const node = renderActivityMessage(m);
if (!node) return null;
return <ActivityWrapper key={m.id}>{node}</ActivityWrapper>;
}
return null;
})}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:
{toolCalls.map((tc) => {
const toolMessage = toolMessagesByCallId.get(tc.id);
const node = renderToolCall({
toolCall: tc,
toolMessage,
});
return node ? <div key={tc.id}>{node}</div> : null;
})}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:
Missing snippet
custom-bubbles not found in ms-agent-python::headless-complete. Tag the source lines with // @region[custom-bubbles] / // @endregion[custom-bubbles].Available: weather-tool-backend, page-send-message, use-rendered-messages-hook, manual-tool-call-rendering, manual-activity-message-renderingTo 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?