feat(sdk): auto-inject A2UI tool in CopilotKitMiddleware (CopilotKit#5161)

Prebuilt agents get dynamic A2UI with no extra wiring — adding the
middleware is enough. When the frontend registers an A2UI catalog
(surfaced by the runtime into state["ag-ui"].a2ui_schema), the
middleware infers the agent's own model, advertises the generate_a2ui
tool in the model-call hook, and executes it in the tool-call hook. No
catalog → the tool is never advertised.

Covers both @copilotkit/sdk-js and the copilotkit Python SDK. Bumps the
A2UI tool-factory dependency to where get_a2ui_tools ships
(@ag-ui/langgraph 0.0.35, ag-ui-langgraph >=0.0.37).

Author: ranst91

.npmrc

@@ -1,3 +1,4 @@
 minimum-release-age=1440
 minimum-release-age-exclude[]=@ag-ui/langgraph
+minimum-release-age-exclude[]=@ag-ui/a2ui-middleware
 block-exotic-subdeps=true

packages/runtime/package.json

@@ -77,11 +77,11 @@
     "attw": "attw --pack . --profile node16"
   },
   "dependencies": {
-    "@ag-ui/a2ui-middleware": "0.0.5",
+    "@ag-ui/a2ui-middleware": "0.0.6",
     "@ag-ui/client": "0.0.53",
     "@ag-ui/core": "0.0.53",
     "@ag-ui/encoder": "0.0.53",
-    "@ag-ui/langgraph": "0.0.34",
+    "@ag-ui/langgraph": "0.0.37",
     "@ag-ui/mcp-apps-middleware": "0.0.3",
     "@ai-sdk/anthropic": "^3.0.49",
     "@ai-sdk/google": "^3.0.33",

packages/sdk-js/package.json

@@ -59,7 +59,7 @@
     "attw": "attw --pack . --profile node16"
   },
   "dependencies": {
-    "@ag-ui/langgraph": "0.0.34",
+    "@ag-ui/langgraph": "0.0.37",
     "@copilotkit/shared": "workspace:*"
   },
   "devDependencies": {

packages/sdk-js/src/langgraph/__tests__/middleware.test.ts

@@ -498,6 +498,231 @@ describe("afterAgent", () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// Auto-A2UI — middleware injects + executes generate_a2ui when the frontend
+// registered a catalog (surfaced into state["ag-ui"].a2ui_schema)
+// ---------------------------------------------------------------------------
+//
+// Contract: the developer passes nothing — using the middleware is enough.
+// generate_a2ui is advertised to the model only when an A2UI catalog is
+// present, is built from the agent's own (inferred) model, and is executed by
+// the middleware itself (it is never in the agent's static tool registry).
+
+async function runWrapTool(middleware: any, request: any) {
+  let received: any = null;
+  const handler = async (req: any) => {
+    received = req;
+    return { content: "tool-ok" } as any;
+  };
+  await middleware.wrapToolCall(request, handler);
+  return received;
+}
+
+describe("auto-A2UI injection", () => {
+  it("does NOT advertise generate_a2ui when the inject flag is absent", async () => {
+    const request = makeRequest({
+      state: { messages: [], thread_id: "a2ui-off" },
+      tools: [{ name: "backend" }],
+    });
+
+    const { received } = await runWrap(copilotkitMiddleware, request);
+
+    expect(received.tools.map((t: any) => t.name)).toEqual(["backend"]);
+  });
+
+  it("does NOT advertise generate_a2ui when a catalog is present but the flag is absent (opt-in)", async () => {
+    const request = makeRequest({
+      state: {
+        messages: [],
+        thread_id: "a2ui-noflag",
+        "ag-ui": { a2ui_schema: "<components/>" },
+      },
+      tools: [{ name: "backend" }],
+    });
+
+    const { received } = await runWrap(copilotkitMiddleware, request);
+
+    const names = received.tools.map((t: any) => t.name);
+    expect(names).not.toContain("generate_a2ui");
+    expect(names).toContain("backend");
+  });
+
+  it("advertises generate_a2ui (alongside existing tools) when the flag is on", async () => {
+    const request = makeRequest({
+      state: {
+        messages: [],
+        thread_id: "a2ui-on",
+        "ag-ui": { a2ui_schema: "<components/>", inject_a2ui_tool: true },
+      },
+      tools: [{ name: "backend" }],
+    });
+
+    const { received } = await runWrap(copilotkitMiddleware, request);
+
+    const names = received.tools.map((t: any) => t.name);
+    expect(names).toContain("backend");
+    expect(names).toContain("generate_a2ui");
+  });
+
+  it("binds to the catalog from copilotkit.context when the flag is on (runtime-proxy path)", async () => {
+    const request = makeRequest({
+      state: {
+        messages: [],
+        thread_id: "a2ui-ctx",
+        "ag-ui": { inject_a2ui_tool: true },
+        copilotkit: {
+          context: [
+            {
+              description:
+                "A2UI catalog capabilities: available catalog IDs and custom component definitions.",
+              value:
+                "Available A2UI catalog:\n- declarative-gen-ui-catalog\n  - Card: {...}\n  - Metric: {...}",
+            },
+          ],
+        },
+      },
+      tools: [{ name: "backend" }],
+    });
+
+    const { received } = await runWrap(copilotkitMiddleware, request);
+
+    const names = received.tools.map((t: any) => t.name);
+    expect(names).toContain("backend");
+    expect(names).toContain("generate_a2ui");
+  });
+
+  it("executes generate_a2ui via wrapToolCall using the inferred model", async () => {
+    const state = {
+      messages: [],
+      thread_id: "a2ui-exec",
+      "ag-ui": { a2ui_schema: "<components/>", inject_a2ui_tool: true },
+    };
+    // First the model call infers the model + stashes the built tool.
+    await runWrap(copilotkitMiddleware, makeRequest({ state, tools: [] }));
+
+    const received = await runWrapTool(copilotkitMiddleware, {
+      toolCall: { name: "generate_a2ui", id: "1", args: {} },
+      tool: undefined,
+      state,
+      runtime: {},
+    });
+
+    expect(received.tool).toBeDefined();
+    expect(received.tool.name).toBe("generate_a2ui");
+  });
+
+  it("leaves non-A2UI tool calls untouched", async () => {
+    const state = {
+      messages: [],
+      thread_id: "a2ui-other",
+      "ag-ui": { a2ui_schema: "<components/>", inject_a2ui_tool: true },
+    };
+    await runWrap(copilotkitMiddleware, makeRequest({ state, tools: [] }));
+
+    const backendTool = { name: "backend" };
+    const received = await runWrapTool(copilotkitMiddleware, {
+      toolCall: { name: "backend", id: "1", args: {} },
+      tool: backendTool,
+      state,
+      runtime: {},
+    });
+
+    expect(received.tool).toBe(backendTool);
+  });
+
+  it("stops executing generate_a2ui after the run ends (afterAgent clears the bridge)", async () => {
+    const state = {
+      messages: [],
+      thread_id: "a2ui-clean",
+      "ag-ui": { a2ui_schema: "<components/>", inject_a2ui_tool: true },
+    };
+    await runWrap(copilotkitMiddleware, makeRequest({ state, tools: [] }));
+    copilotkitMiddleware.afterAgent(state, {} as any);
+
+    const received = await runWrapTool(copilotkitMiddleware, {
+      toolCall: { name: "generate_a2ui", id: "1", args: {} },
+      tool: undefined,
+      state,
+      runtime: {},
+    });
+
+    expect(received.tool).toBeUndefined();
+  });
+
+  // --- A2UI injectA2UITool flag (forwarded → ag-ui state) ------------------
+
+  it("does NOT advertise generate_a2ui when inject_a2ui_tool is false", async () => {
+    const request = makeRequest({
+      state: {
+        messages: [],
+        thread_id: "a2ui-optout",
+        "ag-ui": { a2ui_schema: "<components/>", inject_a2ui_tool: false },
+      },
+      tools: [{ name: "backend" }],
+    });
+
+    const { received } = await runWrap(copilotkitMiddleware, request);
+
+    const names = received.tools.map((t: any) => t.name);
+    expect(names).not.toContain("generate_a2ui");
+    expect(names).toContain("backend");
+  });
+
+  it("advertises generate_a2ui when inject_a2ui_tool is true", async () => {
+    const request = makeRequest({
+      state: {
+        messages: [],
+        thread_id: "a2ui-optin",
+        "ag-ui": { a2ui_schema: "<components/>", inject_a2ui_tool: true },
+      },
+      tools: [{ name: "backend" }],
+    });
+
+    const { received } = await runWrap(copilotkitMiddleware, request);
+
+    expect(received.tools.map((t: any) => t.name)).toContain("generate_a2ui");
+  });
+
+  it("drops the runtime's render_a2ui when injecting our generate_a2ui", async () => {
+    const request = makeRequest({
+      state: {
+        messages: [],
+        thread_id: "a2ui-drop",
+        "ag-ui": { a2ui_schema: "<components/>", inject_a2ui_tool: true },
+        copilotkit: {
+          actions: [{ name: "render_a2ui" }, { name: "fe_tool" }],
+        },
+      },
+      tools: [],
+    });
+
+    const { received } = await runWrap(copilotkitMiddleware, request);
+
+    const names = received.tools.map((t: any) => t.name);
+    expect(names).toContain("generate_a2ui");
+    expect(names).toContain("fe_tool");
+    expect(names).not.toContain("render_a2ui");
+  });
+
+  it("does NOT double-inject when the agent already defines generate_a2ui", async () => {
+    const request = makeRequest({
+      state: {
+        messages: [],
+        thread_id: "a2ui-dup",
+        "ag-ui": { a2ui_schema: "<components/>", inject_a2ui_tool: true },
+      },
+      tools: [{ name: "generate_a2ui" }],
+    });
+
+    const { received } = await runWrap(copilotkitMiddleware, request);
+
+    const count = received.tools.filter(
+      (t: any) => t.name === "generate_a2ui",
+    ).length;
+    expect(count).toBe(1);
+  });
+});
+
 // ---------------------------------------------------------------------------
 // zodState — Standard-Schema JSON-schema augmentation
 // ---------------------------------------------------------------------------