Headless UI

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

Headless Chat (Complete)

Waking up the demo

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:

chat.tsx
  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:

chat.tsx
                {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:

message-list.tsx
  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 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:

message-list.tsx
      {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:

message-list.tsx
              {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:

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?