feat(showcase/ag2): add headless-complete demo with dedicated AG2 sub-app

Author: AlemTuzlak

showcase/integrations/ag2/src/agent_server.py

@@ -19,6 +19,7 @@
 from dotenv import load_dotenv
 
 from agents.agent import stream as default_stream
+from agents.headless_complete import headless_complete_app
 from agents.shared_state_read_write import (
     shared_state_read_write_app,
 )
@@ -57,6 +58,7 @@ async def dispatch(self, request, call_next):
 # under it, so the named mounts must come first.
 app.mount("/shared-state-read-write", shared_state_read_write_app)
 app.mount("/subagents", subagents_app)
+app.mount("/headless-complete", headless_complete_app)
 
 
 # Mount the default AG2 AG-UI endpoint at the root.

showcase/integrations/ag2/src/agents/headless_complete.py

@@ -0,0 +1,88 @@
+"""AG2 agent backing the Headless Chat (Complete) demo.
+
+The cell exists to prove that every CopilotKit rendering surface works
+when the chat UI is composed manually (no <CopilotChatMessageView /> or
+<CopilotChatAssistantMessage />). To exercise those surfaces we give
+this agent two mock backend tools (``get_weather``, ``get_stock_price``)
+which the frontend renders via app-registered ``useRenderTool``
+renderers, plus a frontend-registered ``useComponent`` tool
+(``highlight_note``) that the agent can invoke -- the UI flows through
+the same ``useRenderToolCall`` path.
+
+The system prompt nudges the model toward the right surface per user
+question and falls back to plain text otherwise.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from autogen import ConversableAgent, LLMConfig
+from autogen.ag_ui import AGUIStream
+from fastapi import FastAPI
+
+
+SYSTEM_PROMPT = (
+    "You are a helpful, concise assistant wired into a headless chat "
+    "surface that demonstrates CopilotKit's full rendering stack. Pick "
+    "the right surface for each user question and fall back to plain "
+    "text when none of the tools fit.\n\n"
+    "Routing rules:\n"
+    "  - If the user asks about weather for a place, call `get_weather` "
+    "with the location.\n"
+    "  - If the user asks about a stock or ticker (AAPL, TSLA, MSFT, "
+    "...), call `get_stock_price` with the ticker.\n"
+    "  - If the user asks you to highlight, flag, or mark a short note "
+    "or phrase, call the frontend `highlight_note` tool with the text "
+    "and a color (yellow, pink, green, or blue). Do NOT ask the user "
+    "for the color -- pick a sensible one if they didn't say.\n"
+    "  - Otherwise, reply in plain text.\n\n"
+    "After a tool returns, write one short sentence summarizing the "
+    "result. Never fabricate data a tool could provide."
+)
+
+
+async def get_weather(
+    location: Annotated[str, "City or place to look up the weather for"],
+) -> dict:
+    """Get the current weather for a given location.
+
+    Returns a mock payload with city, temperature in Fahrenheit, humidity,
+    wind speed, and conditions.
+    """
+    return {
+        "city": location,
+        "temperature": 68,
+        "humidity": 55,
+        "wind_speed": 10,
+        "conditions": "Sunny",
+    }
+
+
+async def get_stock_price(
+    ticker: Annotated[str, "Stock ticker symbol (e.g. AAPL, TSLA, MSFT)"],
+) -> dict:
+    """Get a mock current price for a stock ticker.
+
+    Returns a payload with the ticker symbol (uppercased), price in USD,
+    and percentage change for the day.
+    """
+    return {
+        "ticker": ticker.upper(),
+        "price_usd": 189.42,
+        "change_pct": 1.27,
+    }
+
+
+agent = ConversableAgent(
+    name="headless_complete_assistant",
+    system_message=SYSTEM_PROMPT,
+    llm_config=LLMConfig({"model": "gpt-4o-mini", "stream": True}),
+    human_input_mode="NEVER",
+    max_consecutive_auto_reply=8,
+    functions=[get_weather, get_stock_price],
+)
+
+stream = AGUIStream(agent)
+headless_complete_app = FastAPI()
+headless_complete_app.mount("", stream.build_asgi())

showcase/integrations/ag2/src/app/api/copilotkit/route.ts

@@ -56,6 +56,7 @@ const sharedAgentNames = [
 const dedicatedAgents: Record<string, string> = {
   "shared-state-read-write": "/shared-state-read-write/",
   subagents: "/subagents/",
+  "headless-complete": "/headless-complete/",
 };
 
 const agents: Record<string, AbstractAgent> = {};

showcase/integrations/ag2/src/app/demos/headless-complete/README.md

@@ -0,0 +1,35 @@
+# Headless Chat (Complete)
+
+## What This Demo Shows
+
+Full chat implementation built from scratch on `useAgent` — no
+`<CopilotChat />`, no `<CopilotChatMessageView>`, no
+`<CopilotChatAssistantMessage>`. Demonstrates that every CopilotKit
+rendering surface (text, reasoning, tool-call renders, custom-message
+slots) can be re-composed by hand from the low-level hooks.
+
+## How to Interact
+
+Try asking your Copilot to:
+
+- "What's the weather in Tokyo?"
+- "What's AAPL trading at right now?"
+- "Highlight 'meeting at 3pm' in yellow."
+
+## Technical Details
+
+- **Backend**: A dedicated AG2 `ConversableAgent` (see
+  `src/agents/headless_complete.py`) mounted at `/headless-complete/`
+  on the Python agent server. Exposes `get_weather` and
+  `get_stock_price` as backend tools.
+- **Frontend tool**: `highlight_note` is registered on the frontend
+  via `useComponent`, which surfaces through the same
+  `useRenderToolCall` path the manual hook consumes.
+- **Manual composition**: `use-rendered-messages.tsx` mirrors
+  CopilotChatMessageView's role dispatch, walking each message and
+  producing a `renderedContent` node. The list (message-list.tsx)
+  drops that node into a `<UserBubble>` or `<AssistantBubble>`
+  chrome wrapper.
+- **Chrome only**: the bubbles, typing indicator, and input bar
+  contain zero imports from `@copilotkit/react-core`'s chat
+  primitives — they're pure presentational components.

showcase/integrations/ag2/src/app/demos/headless-complete/assistant-bubble.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import React from "react";
+
+/**
+ * Left-aligned assistant bubble — pure chrome.
+ *
+ * Receives a precomputed `renderedContent` node (built by
+ * `useRenderedMessages`) and wraps it in the styled bubble container.
+ * No imports from `@copilotkit/react-core`'s chat primitives here — the
+ * manual composition upstream already produced the final node, so this
+ * file is purely presentational.
+ *
+ * An empty node (e.g. an assistant message that has neither text nor tool
+ * calls yet) is suppressed so the bubble doesn't flash an empty rounded
+ * box while streaming hasn't started.
+ */
+// @region[custom-bubbles]
+export function AssistantBubble({ children }: { children: React.ReactNode }) {
+  if (isEmpty(children)) return null;
+
+  return (
+    <div className="flex justify-start">
+      <div className="max-w-[85%] flex flex-col gap-2">
+        <div className="rounded-2xl rounded-bl-sm bg-[#F0F0F4] text-[#010507] px-4 py-2 text-sm">
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}
+// @endregion[custom-bubbles]
+
+function isEmpty(node: React.ReactNode): boolean {
+  if (node == null || node === false) return true;
+  if (typeof node === "string") return node.trim().length === 0;
+  if (Array.isArray(node)) return node.every(isEmpty);
+  return false;
+}

showcase/integrations/ag2/src/app/demos/headless-complete/highlight-note.tsx

@@ -0,0 +1,42 @@
+"use client";
+
+import React from "react";
+import { z } from "zod";
+
+/**
+ * Frontend-only component invoked by the agent as a tool call via
+ * `useComponent({ name: "highlight_note", ... })`. The backend does
+ * NOT define this tool — `useComponent` is sugar over
+ * `useFrontendTool`, so the tool is registered against the frontend and
+ * surfaces through the same `useRenderToolCall` path the manual hook
+ * in `use-rendered-messages.tsx` is wired to.
+ */
+export const highlightNotePropsSchema = z.object({
+  text: z.string().describe("The note text to highlight."),
+  color: z
+    .enum(["yellow", "pink", "green", "blue"])
+    .describe("Highlight color for the note."),
+});
+
+export type HighlightNoteProps = z.infer<typeof highlightNotePropsSchema>;
+
+const COLOR_CLASSES: Record<HighlightNoteProps["color"], string> = {
+  yellow: "bg-[#FFF388]/30 border-[#FFF388] text-[#010507]",
+  pink: "bg-[#FA5F67]/10 border-[#FA5F6733] text-[#010507]",
+  green: "bg-[#85ECCE]/20 border-[#85ECCE4D] text-[#010507]",
+  blue: "bg-[#BEC2FF1A] border-[#BEC2FF] text-[#010507]",
+};
+
+export function HighlightNote({ text, color }: HighlightNoteProps) {
+  const cls = COLOR_CLASSES[color] ?? COLOR_CLASSES.yellow;
+  return (
+    <div
+      className={`mt-2 mb-2 inline-block rounded-xl border px-3 py-2 text-sm font-medium shadow-sm ${cls}`}
+    >
+      <span className="mr-2 text-[10px] uppercase tracking-[0.14em] text-[#57575B]">
+        Note
+      </span>
+      {text}
+    </div>
+  );
+}

showcase/integrations/ag2/src/app/demos/headless-complete/input-bar.tsx

@@ -0,0 +1,73 @@
+"use client";
+
+import React, { useRef } from "react";
+
+/**
+ * Composer for the headless chat.
+ *
+ * A textarea plus a Send / Stop toggle. Enter submits; Shift+Enter inserts a
+ * newline. The textarea is disabled while the agent is running so users can't
+ * pile up concurrent turns.
+ */
+export function InputBar({
+  value,
+  onChange,
+  onSubmit,
+  onStop,
+  isRunning,
+  canStop,
+}: {
+  value: string;
+  onChange: (v: string) => void;
+  onSubmit: () => void;
+  onStop: () => void;
+  isRunning: boolean;
+  canStop: boolean;
+}) {
+  const inputRef = useRef<HTMLTextAreaElement>(null);
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key === "Enter" && !e.shiftKey) {
+      e.preventDefault();
+      onSubmit();
+    }
+  };
+
+  return (
+    <form
+      className="border-t border-[#E9E9EF] p-3 flex gap-2 items-end bg-white"
+      onSubmit={(e) => {
+        e.preventDefault();
+        onSubmit();
+      }}
+    >
+      <textarea
+        ref={inputRef}
+        rows={1}
+        value={value}
+        onChange={(e) => onChange(e.target.value)}
+        onKeyDown={handleKeyDown}
+        placeholder={isRunning ? "Agent is working..." : "Type a message..."}
+        disabled={isRunning}
+        className="flex-1 resize-none rounded-2xl border border-[#DBDBE5] bg-white px-4 py-2 text-sm leading-6 text-[#010507] focus:border-[#BEC2FF] focus:outline-none focus:ring-2 focus:ring-[#BEC2FF33] disabled:bg-[#FAFAFC] disabled:text-[#AFAFB7]"
+      />
+      {canStop ? (
+        <button
+          type="button"
+          onClick={onStop}
+          className="rounded-full px-4 py-2 text-sm font-medium bg-[#FA5F67] text-white hover:opacity-90 transition-opacity"
+        >
+          Stop
+        </button>
+      ) : (
+        <button
+          type="submit"
+          disabled={isRunning || value.trim().length === 0}
+          className="rounded-full px-4 py-2 text-sm font-medium bg-[#010507] text-white hover:bg-[#2B2B2B] disabled:bg-[#DBDBE5] disabled:cursor-not-allowed transition-colors"
+        >
+          Send
+        </button>
+      )}
+    </form>
+  );
+}

showcase/integrations/ag2/src/app/demos/headless-complete/message-list.tsx

@@ -0,0 +1,83 @@
+"use client";
+
+import React, { useLayoutEffect, useRef } from "react";
+import type { Message } from "@ag-ui/core";
+import { UserBubble } from "./user-bubble";
+import { AssistantBubble } from "./assistant-bubble";
+import { TypingIndicator } from "./typing-indicator";
+import { useRenderedMessages } from "./use-rendered-messages";
+
+/**
+ * Scrollable messages area — TRULY headless.
+ *
+ * The per-message generative-UI weave (text, reasoning, tool-call renders,
+ * activity messages, custom-before / custom-after) is composed inline by
+ * `useRenderedMessages`, which returns a flat list of messages each carrying
+ * a precomputed `renderedContent` field. Here we simply dispatch on role
+ * and drop that node into the appropriate bubble chrome — no
+ * `<CopilotChatMessageView>`, no `<CopilotChatAssistantMessage>`.
+ *
+ * See `use-rendered-messages.tsx` for the composition logic; it mirrors
+ * `packages/react-core/src/v2/components/chat/CopilotChatMessageView.tsx:542-612`.
+ */
+export function MessageList({
+  messages,
+  isRunning,
+}: {
+  messages: Message[];
+  isRunning: boolean;
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null);
+  const renderedMessages = useRenderedMessages(messages, isRunning);
+
+  // Auto-scroll on streaming content changes (not just new messages).
+  const fingerprint = messages
+    .map((m) => {
+      const contentLen =
+        typeof m.content === "string"
+          ? m.content.length
+          : Array.isArray(m.content)
+            ? m.content.length
+            : 0;
+      const tcLen =
+        "toolCalls" in m && Array.isArray(m.toolCalls)
+          ? m.toolCalls.map((tc) => tc.function.arguments.length).join(",")
+          : "";
+      return `${m.id}:${m.role}:${contentLen}:${tcLen}`;
+    })
+    .join("|");
+
+  useLayoutEffect(() => {
+    const el = scrollRef.current;
+    if (!el) return;
+    el.scrollTop = el.scrollHeight;
+  }, [fingerprint, isRunning]);
+
+  return (
+    <div
+      ref={scrollRef}
+      data-testid="headless-complete-messages"
+      className="flex-1 min-h-0 overflow-y-auto px-4 py-4"
+    >
+      <div className="space-y-3">
+        {renderedMessages.length === 0 && (
+          <div className="text-center text-sm text-[#838389] mt-8">
+            Try weather, a stock, a highlighted note, or an Excalidraw sketch.
+          </div>
+        )}
+        {renderedMessages.map((m) => {
+          // Tool-role messages are folded into the preceding assistant
+          // message's tool-call renders; `renderedContent` is null for them.
+          if (m.renderedContent == null) return null;
+          if (m.role === "user") {
+            return <UserBubble key={m.id}>{m.renderedContent}</UserBubble>;
+          }
+          return (
+            <AssistantBubble key={m.id}>{m.renderedContent}</AssistantBubble>
+          );
+        })}
+        {isRunning && <TypingIndicator />}
+      </div>
+    </div>
+  );
+}