feat: eagerly create default A2UI renderer when middleware is enabled (CopilotKit#3395)

Author: ranst91

.changeset/odd-planets-deliver.md

@@ -0,0 +1,5 @@
+---
+"@copilotkitnext/react": patch
+---
+
+feat: eagerly create default A2UI renderer when middleware is enabled

packages/v2/core/src/core/agent-registry.ts

@@ -29,6 +29,7 @@ export class AgentRegistry {
     CopilotKitCoreRuntimeConnectionStatus.Disconnected;
   private _runtimeTransport: CopilotRuntimeTransport = "rest";
   private _audioFileTranscriptionEnabled: boolean = false;
+  private _a2uiEnabled: boolean = false;
 
   constructor(private core: CopilotKitCore) {}
 
@@ -59,6 +60,10 @@ export class AgentRegistry {
     return this._audioFileTranscriptionEnabled;
   }
 
+  get a2uiEnabled(): boolean {
+    return this._a2uiEnabled;
+  }
+
   /**
    * Initialize agents from configuration
    */
@@ -206,6 +211,7 @@ export class AgentRegistry {
         CopilotKitCoreRuntimeConnectionStatus.Disconnected;
       this._runtimeVersion = undefined;
       this._audioFileTranscriptionEnabled = false;
+      this._a2uiEnabled = false;
       this.remoteAgents = {};
       this._agents = this.localAgents;
 
@@ -255,6 +261,7 @@ export class AgentRegistry {
       this._runtimeVersion = version;
       this._audioFileTranscriptionEnabled =
         runtimeInfoResponse.audioFileTranscriptionEnabled ?? false;
+      this._a2uiEnabled = runtimeInfoResponse.a2uiEnabled ?? false;
 
       await this.notifyRuntimeStatusChanged(
         CopilotKitCoreRuntimeConnectionStatus.Connected,
@@ -265,6 +272,7 @@ export class AgentRegistry {
         CopilotKitCoreRuntimeConnectionStatus.Error;
       this._runtimeVersion = undefined;
       this._audioFileTranscriptionEnabled = false;
+      this._a2uiEnabled = false;
       this.remoteAgents = {};
       this._agents = this.localAgents;
 

packages/v2/core/src/core/core.ts

@@ -329,6 +329,10 @@ export class CopilotKitCore {
     return this.agentRegistry.audioFileTranscriptionEnabled;
   }
 
+  get a2uiEnabled(): boolean {
+    return this.agentRegistry.a2uiEnabled;
+  }
+
   /**
    * Configuration updates
    */

packages/v2/react/src/index.ts

@@ -12,3 +12,6 @@ export * from "./hooks";
 export * from "./providers";
 export * from "./types";
 export * from "./lib/react-core";
+export { createA2UIMessageRenderer } from "./a2ui/A2UIMessageRenderer";
+export type { A2UIMessageRendererOptions } from "./a2ui/A2UIMessageRenderer";
+export type { Theme as A2UITheme } from "@copilotkit/a2ui-renderer";

packages/v2/react/src/providers/CopilotKitProvider.tsx

@@ -21,6 +21,9 @@ import {
   MCPAppsActivityRenderer,
   MCPAppsActivityType,
 } from "../components/MCPAppsActivityRenderer";
+import { createA2UIMessageRenderer } from "../a2ui/A2UIMessageRenderer";
+import { viewerTheme } from "@copilotkit/a2ui-renderer";
+import type { Theme as A2UITheme } from "@copilotkit/a2ui-renderer";
 import { CopilotKitCoreReact } from "../lib/react-core";
 import type {
   ReactActivityMessageRenderer,
@@ -89,6 +92,26 @@ export interface CopilotKitProviderProps {
     code: CopilotKitCoreErrorCode;
     context: Record<string, any>;
   }) => void | Promise<void>;
+  /**
+   * Configuration for the A2UI (Agent-to-UI) renderer.
+   * The built-in A2UI renderer is activated automatically when the runtime reports
+   * that `a2ui` is configured in `CopilotRuntime`. This prop is optional and only
+   * needed if you want to override the default theme.
+   *
+   * @example
+   * ```tsx
+   * <CopilotKit runtimeUrl="/api/copilotkit" a2ui={{ theme: myCustomTheme }}>
+   *   {children}
+   * </CopilotKit>
+   * ```
+   */
+  a2ui?: {
+    /**
+     * Override the default A2UI viewer theme.
+     * When omitted, the built-in `viewerTheme` from `@copilotkit/a2ui-renderer` is used.
+     */
+    theme?: A2UITheme;
+  };
 }
 
 // Small helper to normalize array props to a stable reference and warn
@@ -133,8 +156,10 @@ export const CopilotKitProvider: React.FC<CopilotKitProviderProps> = ({
   showDevConsole = false,
   useSingleEndpoint = false,
   onError,
+  a2ui,
 }) => {
   const [shouldRenderInspector, setShouldRenderInspector] = useState(false);
+  const [runtimeA2UIEnabled, setRuntimeA2UIEnabled] = useState(false);
 
   useEffect(() => {
     if (typeof window === "undefined") {
@@ -188,16 +213,25 @@ export const CopilotKitProvider: React.FC<CopilotKitProviderProps> = ({
   >(renderActivityMessages, "renderActivityMessages must be a stable array.");
 
   // Built-in activity renderers that are always included
-  const builtInActivityRenderers = useMemo<ReactActivityMessageRenderer<any>[]>(
-    () => [
+  const builtInActivityRenderers = useMemo<
+    ReactActivityMessageRenderer<any>[]
+  >(() => {
+    const renderers: ReactActivityMessageRenderer<any>[] = [
       {
         activityType: MCPAppsActivityType,
         content: MCPAppsActivityContentSchema,
         render: MCPAppsActivityRenderer,
       },
-    ],
-    [],
-  );
+    ];
+
+    if (runtimeA2UIEnabled) {
+      renderers.unshift(
+        createA2UIMessageRenderer({ theme: a2ui?.theme ?? viewerTheme }),
+      );
+    }
+
+    return renderers;
+  }, [runtimeA2UIEnabled, a2ui]);
 
   // Combine user-provided activity renderers with built-in ones
   // User-provided renderers take precedence (come first) so they can override built-ins
@@ -347,6 +381,18 @@ export const CopilotKitProvider: React.FC<CopilotKitProviderProps> = ({
   }
   const copilotkit = copilotkitRef.current;
 
+  // Sync runtimeA2UIEnabled from the core once runtime info is fetched
+  useEffect(() => {
+    const subscription = copilotkit.subscribe({
+      onRuntimeConnectionStatusChanged: () => {
+        setRuntimeA2UIEnabled(copilotkit.a2uiEnabled);
+      },
+    });
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [copilotkit]);
+
   // Subscribe to render tool calls changes to force re-renders
   const [, forceUpdate] = useReducer((x) => x + 1, 0);
 

packages/v2/react/src/providers/__tests__/CopilotKitProvider.test.tsx

@@ -425,6 +425,154 @@ describe("CopilotKitProvider", () => {
     });
   });
 
+  describe("a2ui prop", () => {
+    const originalFetch = global.fetch;
+    const originalWindow = (globalThis as { window?: unknown }).window;
+
+    beforeEach(() => {
+      (globalThis as { window?: unknown }).window = {};
+    });
+
+    afterEach(() => {
+      global.fetch = originalFetch;
+      if (originalWindow === undefined) {
+        delete (globalThis as { window?: unknown }).window;
+      } else {
+        (globalThis as { window?: unknown }).window = originalWindow;
+      }
+    });
+
+    it("does not register an a2ui-surface renderer by default", () => {
+      const { result } = renderHook(() => useCopilotKit(), {
+        wrapper: ({ children }) => (
+          <CopilotKitProvider>{children}</CopilotKitProvider>
+        ),
+      });
+
+      const a2uiRenderer =
+        result.current.copilotkit.renderActivityMessages.find(
+          (r) => r.activityType === "a2ui-surface",
+        );
+      expect(a2uiRenderer).toBeUndefined();
+    });
+
+    it("does not register an a2ui-surface renderer when a2ui.theme is provided but runtime has not signaled a2uiEnabled", () => {
+      const customTheme = { components: {}, elements: {}, markdown: {} } as any;
+
+      const { result } = renderHook(() => useCopilotKit(), {
+        wrapper: ({ children }) => (
+          <CopilotKitProvider a2ui={{ theme: customTheme }}>
+            {children}
+          </CopilotKitProvider>
+        ),
+      });
+
+      const a2uiRenderer =
+        result.current.copilotkit.renderActivityMessages.find(
+          (r) => r.activityType === "a2ui-surface",
+        );
+      expect(a2uiRenderer).toBeUndefined();
+    });
+
+    it("registers an a2ui-surface renderer when runtime reports a2uiEnabled: true", async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          version: "1.0.0",
+          agents: {},
+          audioFileTranscriptionEnabled: false,
+          a2uiEnabled: true,
+        }),
+      });
+
+      const { result } = renderHook(() => useCopilotKit(), {
+        wrapper: ({ children }) => (
+          <CopilotKitProvider runtimeUrl="http://localhost:3000/api">
+            {children}
+          </CopilotKitProvider>
+        ),
+      });
+
+      await vi.waitFor(() => {
+        const a2uiRenderer =
+          result.current.copilotkit.renderActivityMessages.find(
+            (r) => r.activityType === "a2ui-surface",
+          );
+        expect(a2uiRenderer).toBeDefined();
+      });
+    });
+
+    it("does not register an a2ui-surface renderer when runtime reports a2uiEnabled: false", async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          version: "1.0.0",
+          agents: {},
+          audioFileTranscriptionEnabled: false,
+          a2uiEnabled: false,
+        }),
+      });
+
+      const { result } = renderHook(() => useCopilotKit(), {
+        wrapper: ({ children }) => (
+          <CopilotKitProvider runtimeUrl="http://localhost:3000/api">
+            {children}
+          </CopilotKitProvider>
+        ),
+      });
+
+      // Let the connection settle
+      await vi.waitFor(() => {
+        expect(global.fetch).toHaveBeenCalled();
+      });
+
+      const a2uiRenderer =
+        result.current.copilotkit.renderActivityMessages.find(
+          (r) => r.activityType === "a2ui-surface",
+        );
+      expect(a2uiRenderer).toBeUndefined();
+    });
+
+    it("user-provided renderActivityMessages with activityType a2ui-surface takes precedence over built-in", async () => {
+      global.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({
+          version: "1.0.0",
+          agents: {},
+          audioFileTranscriptionEnabled: false,
+          a2uiEnabled: true,
+        }),
+      });
+
+      const userRenderer = {
+        activityType: "a2ui-surface",
+        content: {} as any,
+        render: () => null,
+      };
+
+      const { result } = renderHook(() => useCopilotKit(), {
+        wrapper: ({ children }) => (
+          <CopilotKitProvider
+            runtimeUrl="http://localhost:3000/api"
+            renderActivityMessages={[userRenderer]}
+          >
+            {children}
+          </CopilotKitProvider>
+        ),
+      });
+
+      await vi.waitFor(() => {
+        const renderers =
+          result.current.copilotkit.renderActivityMessages.filter(
+            (r) => r.activityType === "a2ui-surface",
+          );
+        // Both present; user-provided comes first (index 0)
+        expect(renderers.length).toBeGreaterThanOrEqual(1);
+        expect(renderers[0].render).toBe(userRenderer.render);
+      });
+    });
+  });
+
   describe("Edge cases", () => {
     it("handles empty arrays for tools", () => {
       const { result } = renderHook(() => useCopilotKit(), {

packages/v2/runtime/src/__tests__/get-runtime-info.test.ts

@@ -32,6 +32,7 @@ describe("handleGetRuntimeInfo", () => {
       version: expect.any(String),
       agents: {},
       audioFileTranscriptionEnabled: false,
+      a2uiEnabled: false,
     });
   });
 
@@ -54,6 +55,7 @@ describe("handleGetRuntimeInfo", () => {
       version: expect.any(String),
       agents: {},
       audioFileTranscriptionEnabled: true,
+      a2uiEnabled: false,
     });
   });
 
@@ -88,9 +90,27 @@ describe("handleGetRuntimeInfo", () => {
         },
       },
       audioFileTranscriptionEnabled: true,
+      a2uiEnabled: false,
     });
   });
 
+  it("should return a2uiEnabled: true when runtime has a2ui configured", async () => {
+    const runtime = new CopilotRuntime({
+      agents: {},
+      a2ui: {},
+    });
+
+    const response = await handleGetRuntimeInfo({
+      runtime,
+      request: mockRequest,
+    });
+
+    expect(response.status).toBe(200);
+
+    const data = await response.json();
+    expect(data.a2uiEnabled).toBe(true);
+  });
+
   it("should return 500 error when runtime.agents throws an error", async () => {
     const runtime = {
       get agents(): Record<string, AbstractAgent> {

packages/v2/runtime/src/handlers/get-runtime-info.ts

@@ -29,6 +29,7 @@ export async function handleGetRuntimeInfo({
       version: VERSION,
       agents: agentsDict,
       audioFileTranscriptionEnabled: !!runtime.transcriptionService,
+      a2uiEnabled: !!runtime.a2ui,
     };
 
     return new Response(JSON.stringify(runtimeInfo), {

packages/v2/shared/src/types.ts

@@ -23,4 +23,5 @@ export interface RuntimeInfo {
   version: string;
   agents: Record<string, AgentDescription>;
   audioFileTranscriptionEnabled: boolean;
+  a2uiEnabled?: boolean;
 }