refactor(runtime): Support durable compaction of threads (CopilotKit#4130)

<!--
Thank you for sending the PR! We appreciate you spending the time to
work on these changes.

Help us understand your motivation by explaining why you decided to make
this change.


**Please PLEASE reach out to us first before starting any significant
work on new or existing features.**

By the time you've gotten here, you're looking at creating a pull
request so hopefully we're not too late.

We love community contributions! That said, we want to make sure we're
all on the same page before you start.
Investing a lot of time and effort just to find out it doesn't align
with the upstream project feels awful, and we don't want that to happen.
It also helps to make sure the work you're planning isn't already in
progress.

As described in our contributing guide, please file an issue first:
https://github.com/ag-ui-protocol/ag-ui/issues
Or, reach out to us on Discord: https://discord.com/invite/6dffbvGU3D


You can learn more about contributing to copilotkit here:
https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md

Happy contributing!

-->

## What does this PR do?

(Describe the changes introduced in this PR)

## Related PRs and Issues

- (Direct link to related PR or issue, if relevant)

## Checklist

- [ ] I have read the [Contribution
Guide](https://github.com/copilotkit/copilotkit/blob/master/CONTRIBUTING.md)
- [ ] If the PR changes or adds functionality, I have updated the
relevant documentation

Author: MikeRyanDev

examples/integrations/langgraph-python-threads/.env.example

@@ -10,6 +10,9 @@ INTELLIGENCE_GATEWAY_WS_URL=ws://localhost:4401
 INTELLIGENCE_API_KEY=cpk_sPRVSEED_seed0privat0longtoken00
 INTELLIGENCE_ORGANIZATION_ID=casa-de-erlang
 
+# Optional MCP App server for demos. Defaults to Excalidraw when unset.
+MCP_SERVER_URL=https://mcp.excalidraw.com
+
 # Optional thread culler tuning
 THREAD_STALE_HOURS=3
 THREAD_CULL_BATCH_SIZE=1000

examples/integrations/langgraph-python-threads/apps/agent/main.py

@@ -7,20 +7,27 @@
 from langchain.agents import create_agent
 
 # Data & state tools
+from src.a2ui_dynamic_schema import generate_a2ui
+from src.a2ui_fixed_schema import search_flights
 from src.query import query_data
 from src.todos import AgentState, todo_tools
 
 agent = create_agent(
     model="openai:gpt-4.1",
-    tools=[query_data, *todo_tools],
+    tools=[query_data, *todo_tools, generate_a2ui, search_flights],
     middleware=[CopilotKitMiddleware()],
     state_schema=AgentState,
     system_prompt="""
         You are a polished, professional demo assistant. Keep responses to 1-2 sentences.
 
         Tool guidance:
+        - Flights: call search_flights to show flight cards with a pre-built schema.
+        - Dashboards & rich UI: call generate_a2ui to create dashboard UIs with metrics,
+          charts, tables, and cards. It handles rendering automatically.
         - Charts: call query_data first, then render with the chart component.
         - Todos: enable app mode first, then manage todos.
+        - A2UI actions: when you see a log_a2ui_event result (e.g. "view_details"),
+          respond with a brief confirmation. The UI already updated on the frontend.
     """,
 )
 

examples/integrations/langgraph-python-threads/apps/agent/src/a2ui_dynamic_schema.py

@@ -0,0 +1,61 @@
+"""
+Dynamic A2UI tool: LLM-generated UI from conversation context.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from copilotkit import a2ui
+from langchain.tools import ToolRuntime, tool
+from langchain_core.messages import SystemMessage
+from langchain_core.tools import tool as lc_tool
+from langchain_openai import ChatOpenAI
+
+CUSTOM_CATALOG_ID = "copilotkit://app-dashboard-catalog"
+
+
+@lc_tool
+def render_a2ui(
+    surfaceId: str,
+    catalogId: str,
+    components: list[dict],
+    data: dict | None = None,
+) -> str:
+    """Render a dynamic A2UI v0.9 surface."""
+    return "rendered"
+
+
+@tool()
+def generate_a2ui(runtime: ToolRuntime[Any]) -> str:
+    """Generate dynamic A2UI components based on the conversation."""
+    messages = runtime.state["messages"][:-1]
+    context_entries = runtime.state.get("copilotkit", {}).get("context", [])
+    context_text = "\n\n".join(
+        entry.get("value", "")
+        for entry in context_entries
+        if isinstance(entry, dict) and entry.get("value")
+    )
+
+    model = ChatOpenAI(model="gpt-4.1")
+    model_with_tool = model.bind_tools([render_a2ui], tool_choice="render_a2ui")
+    response = model_with_tool.invoke([SystemMessage(content=context_text), *messages])
+
+    if not response.tool_calls:
+        return json.dumps({"error": "LLM did not call render_a2ui"})
+
+    args = response.tool_calls[0]["args"]
+    surface_id = args.get("surfaceId", "dynamic-surface")
+    catalog_id = args.get("catalogId", CUSTOM_CATALOG_ID)
+    components = args.get("components", [])
+    data = args.get("data", {})
+
+    operations = [
+      a2ui.create_surface(surface_id, catalog_id=catalog_id),
+      a2ui.update_components(surface_id, components),
+    ]
+    if data:
+        operations.append(a2ui.update_data_model(surface_id, data))
+
+    return a2ui.render(operations=operations)

examples/integrations/langgraph-python-threads/apps/agent/src/a2ui_fixed_schema.py

@@ -0,0 +1,50 @@
+"""
+Fixed-schema A2UI tool: flight search results.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypedDict
+
+from copilotkit import a2ui
+from langchain.tools import tool
+
+CATALOG_ID = "copilotkit://app-dashboard-catalog"
+SURFACE_ID = "flight-search-results"
+FLIGHT_SCHEMA = a2ui.load_schema(
+    Path(__file__).parent / "a2ui" / "schemas" / "flight_schema.json"
+)
+
+
+class Flight(TypedDict):
+    id: str
+    airline: str
+    airlineLogo: str
+    flightNumber: str
+    origin: str
+    destination: str
+    date: str
+    departureTime: str
+    arrivalTime: str
+    duration: str
+    status: str
+    statusIcon: str
+    price: str
+
+
+@tool
+def search_flights(flights: list[Flight]) -> str:
+    """Search for flights and display the results as rich cards. Return exactly 2 flights.
+
+    Each flight must have: id, airline, airlineLogo, flightNumber, origin,
+    destination, date, departureTime, arrivalTime, duration, status, statusIcon,
+    and price.
+    """
+    return a2ui.render(
+        operations=[
+            a2ui.create_surface(SURFACE_ID, catalog_id=CATALOG_ID),
+            a2ui.update_components(SURFACE_ID, FLIGHT_SCHEMA),
+            a2ui.update_data_model(SURFACE_ID, {"flights": flights}),
+        ],
+    )

examples/integrations/langgraph-python-threads/apps/app/package.json

@@ -9,6 +9,7 @@
   },
   "dependencies": {
     "@ag-ui/client": "0.0.52",
+    "@copilotkit/a2ui-renderer": "1.56.2",
     "@copilotkit/react-core": "1.56.2",
     "@copilotkit/react-ui": "1.56.2",
     "@hono/node-server": "^1.19.14",

examples/integrations/langgraph-python-threads/apps/app/src/App.tsx

@@ -6,6 +6,7 @@ import { ExampleCanvas } from "@/components/example-canvas";
 import { ThreadsDrawer } from "@/components/threads-drawer";
 import { ThemeProvider } from "@/hooks/use-theme";
 import { useExampleSuggestions, useGenerativeUIExamples } from "@/hooks";
+import { demonstrationCatalog } from "@/declarative-generative-ui/renderers";
 import styles from "@/components/threads-drawer/threads-drawer.module.css";
 
 const runtimeUrl = "/api/copilotkit";
@@ -42,7 +43,12 @@ function HomePage() {
 export default function App() {
   return (
     <ThemeProvider>
-      <CopilotKitProvider runtimeUrl={runtimeUrl}>
+      <CopilotKitProvider
+        runtimeUrl={runtimeUrl}
+        a2ui={{ catalog: demonstrationCatalog }}
+        openGenerativeUI={{}}
+        useSingleEndpoint={false}
+      >
         <HomePage />
       </CopilotKitProvider>
     </ThemeProvider>

examples/integrations/langgraph-python-threads/apps/app/src/declarative-generative-ui/definitions.ts

@@ -0,0 +1,140 @@
+import { z } from "zod";
+
+const DynString = z.union([z.string(), z.object({ path: z.string() })]);
+
+export const demonstrationCatalogDefinitions = {
+  Title: {
+    description: "A heading. Use for section titles and page headers.",
+    props: z.object({
+      text: z.string(),
+      level: z.string().optional(),
+    }),
+  },
+  Row: {
+    description: "Horizontal layout container.",
+    props: z.object({
+      gap: z.number().optional(),
+      align: z.string().optional(),
+      justify: z.string().optional(),
+      children: z.union([
+        z.array(z.string()),
+        z.object({ componentId: z.string(), path: z.string() }),
+      ]),
+    }),
+  },
+  Column: {
+    description: "Vertical layout container.",
+    props: z.object({
+      gap: z.number().optional(),
+      align: z.string().optional(),
+      children: z.union([
+        z.array(z.string()),
+        z.object({ componentId: z.string(), path: z.string() }),
+      ]),
+    }),
+  },
+  DashboardCard: {
+    description:
+      "A card container with title and optional subtitle. Has a 'child' slot for content.",
+    props: z.object({
+      title: z.string(),
+      subtitle: z.string().optional(),
+      child: z.string().optional(),
+    }),
+  },
+  Metric: {
+    description:
+      "A key metric display with label, value, and optional trend indicator.",
+    props: z.object({
+      label: z.string(),
+      value: z.string(),
+      trend: z.enum(["up", "down", "neutral"]).optional(),
+      trendValue: z.string().optional(),
+    }),
+  },
+  PieChart: {
+    description: "A pie or donut chart.",
+    props: z.object({
+      data: z.array(
+        z.object({
+          label: z.string(),
+          value: z.number(),
+          color: z.string().optional(),
+        }),
+      ),
+      innerRadius: z.number().optional(),
+    }),
+  },
+  BarChart: {
+    description: "A bar chart.",
+    props: z.object({
+      data: z.array(z.object({ label: z.string(), value: z.number() })),
+      color: z.string().optional(),
+    }),
+  },
+  Badge: {
+    description: "A small status badge.",
+    props: z.object({
+      text: z.string(),
+      variant: z
+        .enum(["success", "warning", "error", "info", "neutral"])
+        .optional(),
+    }),
+  },
+  DataTable: {
+    description: "A data table with columns and rows.",
+    props: z.object({
+      columns: z.array(z.object({ key: z.string(), label: z.string() })),
+      rows: z.array(z.record(z.any())),
+    }),
+  },
+  Button: {
+    description: "An interactive button with an action event.",
+    props: z.object({
+      child: z.string(),
+      variant: z.enum(["primary", "secondary", "ghost"]).optional(),
+      action: z
+        .union([
+          z.object({
+            event: z.object({
+              name: z.string(),
+              context: z.record(z.any()).optional(),
+            }),
+          }),
+          z.null(),
+        ])
+        .optional(),
+    }),
+  },
+  FlightCard: {
+    description: "A rich flight result card.",
+    props: z.object({
+      airline: DynString,
+      airlineLogo: DynString,
+      flightNumber: DynString,
+      origin: DynString,
+      destination: DynString,
+      date: DynString,
+      departureTime: DynString,
+      arrivalTime: DynString,
+      duration: DynString,
+      status: DynString,
+      statusColor: DynString.optional(),
+      price: DynString,
+      action: z
+        .union([
+          z.object({
+            event: z.object({
+              name: z.string(),
+              context: z.record(z.any()).optional(),
+            }),
+          }),
+          z.null(),
+        ])
+        .optional(),
+    }),
+  },
+};
+
+export type DemonstrationCatalogDefinitions =
+  typeof demonstrationCatalogDefinitions;