feat(agno): port a2ui-fixed-schema demo

Adds a dedicated A2UI fixed-schema cell for the Agno integration:
backend `a2ui_fixed_agent.py` ships `flight_schema.json` +
`booked_schema.json` and a single `display_flight` tool that emits
an `a2ui_operations` container directly (no secondary LLM).
Frontend ports `page.tsx` + Zod definitions / renderers / catalog
from the langgraph-python reference. Dedicated runtime route at
`/api/copilotkit-a2ui-fixed-schema` runs the A2UI middleware with
`injectA2UITool: false` so the agent owns its rendering tool.

Author: AlemTuzlak

showcase/integrations/agno/PARITY_NOTES.md

@@ -89,6 +89,18 @@ See `manifest.yaml` for the authoritative list.
   + `byoc_json_render_agent.py` whose system prompt steers the LLM toward
   the json-render flat element-tree spec (`{ root, elements }`).
 
+### Sixth pass (A2UI fixed schema)
+
+- `a2ui-fixed-schema` — dedicated `/api/copilotkit-a2ui-fixed-schema`
+  runtime with `injectA2UITool: false`. New `a2ui_fixed_agent.py`
+  mounted at `/a2ui-fixed-schema/agui` ships
+  `flight_schema.json` + `booked_schema.json` and a single
+  `display_flight` tool that emits an `a2ui_operations` container
+  *directly* — no secondary LLM call — so the LLM only fills in data
+  (origin/destination/airline/price). `booked_schema.json` is shipped
+  as a sibling for when the SDK exposes per-button action handlers
+  for fixed-schema surfaces.
+
 ### Third pass (state + multi-agent recovery)
 
 - `shared-state-read-write` — bidirectional shared state with the UI
@@ -153,10 +165,6 @@ follow-up parity pass rather than faked in.
   an Agno agent
 - `agent-config` — dedicated `/api/copilotkit-agent-config` runtime with typed
   config forwarding; needs Agno dynamic-system-prompt wiring per-request
-- `declarative-gen-ui` (A2UI dynamic) — dedicated runtime + frontend A2UI
-  catalog; the existing Agno `main` agent already exposes `generate_a2ui`,
-  but the declarative-gen-ui cell expects a different runtime surface
-- `a2ui-fixed-schema` — dedicated runtime + fixed-schema catalog
 - `mcp-apps` — requires Agno MCP client/server wiring; Agno has
   `agno.tools.mcp.MCPTools` but integration with the AGUI adapter's
   activity-message surface wasn't verified

showcase/integrations/agno/manifest.yaml

@@ -57,6 +57,7 @@ features:
   - headless-complete
   - auth
   - beautiful-chat
+  - a2ui-fixed-schema
 not_supported_features:
   - gen-ui-interrupt
   - interrupt-headless
@@ -491,6 +492,23 @@ demos:
       - src/app/demos/byoc-json-render/charts/bar-chart.tsx
       - src/app/demos/byoc-json-render/charts/pie-chart.tsx
       - src/app/api/copilotkit/route.ts
+  - id: a2ui-fixed-schema
+    name: "A2UI Fixed Schema"
+    description: Schema is authored ahead of time as JSON; the agent only streams data into the data model. `display_flight` emits an a2ui_operations container directly with no secondary LLM call
+    tags:
+      - generative-ui
+      - a2ui
+    route: /demos/a2ui-fixed-schema
+    animated_preview_url:
+    highlight:
+      - src/agents/a2ui_fixed_agent.py
+      - src/agents/a2ui_schemas/flight_schema.json
+      - src/agents/a2ui_schemas/booked_schema.json
+      - src/app/demos/a2ui-fixed-schema/page.tsx
+      - src/app/demos/a2ui-fixed-schema/a2ui/catalog.ts
+      - src/app/demos/a2ui-fixed-schema/a2ui/definitions.ts
+      - src/app/demos/a2ui-fixed-schema/a2ui/renderers.tsx
+      - src/app/api/copilotkit-a2ui-fixed-schema/route.ts
 managed_platform:
   name: Agent OS
   url: https://os.agno.com

showcase/integrations/agno/src/agent_server.py

@@ -42,6 +42,7 @@
 from starlette.middleware.base import BaseHTTPMiddleware
 from starlette.responses import JSONResponse
 
+from agents.a2ui_fixed_agent import agent as a2ui_fixed_agent
 from agents.agent_config_agent import (
     agent as agent_config_agent,
     build_agent as build_agent_config_agent,
@@ -277,6 +278,7 @@ async def _gen():
 agent_os = AgentOS(
     agents=[
         main_agent,
+        a2ui_fixed_agent,
         agent_config_agent,
         byoc_hashbrown_agent,
         byoc_json_render_agent,
@@ -306,6 +308,10 @@ async def _gen():
         # BYOC: json-render — agent emits a json-render spec the frontend
         # renderer mounts against a Zod-validated catalog.
         AGUI(agent=byoc_json_render_agent, prefix="/byoc-json-render"),
+        # A2UI fixed schema — agent's `display_flight` tool emits an
+        # `a2ui_operations` container directly (no secondary LLM) bound to
+        # the pre-authored `flight_schema.json`.
+        AGUI(agent=a2ui_fixed_agent, prefix="/a2ui-fixed-schema"),
     ],
 )
 app = agent_os.get_app()

showcase/integrations/agno/src/agents/a2ui_fixed_agent.py

@@ -0,0 +1,105 @@
+"""Agno agent for the Declarative Generative UI (A2UI Fixed Schema) demo.
+
+Fixed-schema A2UI: the component tree (schema) is authored ahead of time
+as JSON and shipped with the backend. The agent only streams *data* into
+the data model at runtime via the `display_flight` tool. The frontend
+registers a matching catalog (see
+`src/app/demos/a2ui-fixed-schema/a2ui/catalog.ts`).
+
+Mirrors the langgraph-python `a2ui_fixed.py` reference. The dedicated
+runtime route at `api/copilotkit-a2ui-fixed-schema/route.ts` runs the
+A2UI middleware with `injectA2UITool: false` because the backend owns
+the rendering tool itself — it emits an `a2ui_operations` container
+directly without a secondary LLM call.
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from agno.agent.agent import Agent
+from agno.models.openai import OpenAIChat
+from agno.tools import tool
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+CATALOG_ID = "copilotkit://flight-fixed-catalog"
+SURFACE_ID = "flight-fixed-schema"
+
+_SCHEMAS_DIR = Path(__file__).parent / "a2ui_schemas"
+
+
+def _load_schema(filename: str) -> list[dict]:
+    """Load an A2UI fixed schema from the local schemas directory."""
+    with open(_SCHEMAS_DIR / filename, "r", encoding="utf-8") as fh:
+        return json.load(fh)
+
+
+FLIGHT_SCHEMA = _load_schema("flight_schema.json")
+# `booked_schema.json` is shipped alongside `flight_schema.json` so the
+# schema is ready to wire up once the SDK exposes per-button action handlers
+# for fixed-schema surfaces (matching the langgraph-python reference).
+BOOKED_SCHEMA = _load_schema("booked_schema.json")
+
+
+@tool
+def display_flight(origin: str, destination: str, airline: str, price: str):
+    """Show a flight card for the given trip.
+
+    Emits an `a2ui_operations` container directly — NO secondary LLM
+    call. The runtime A2UI middleware detects the container in the tool
+    result and forwards the surface to the frontend renderer. The
+    frontend catalog resolves component names against the local React
+    components.
+
+    Args:
+        origin (str): Origin airport code (e.g. "SFO").
+        destination (str): Destination airport code (e.g. "JFK").
+        airline (str): Airline name (e.g. "United").
+        price (str): Price string (e.g. "$289").
+
+    Returns:
+        str: A2UI operations as JSON.
+    """
+    operations = [
+        {
+            "type": "create_surface",
+            "surfaceId": SURFACE_ID,
+            "catalogId": CATALOG_ID,
+        },
+        {
+            "type": "update_components",
+            "surfaceId": SURFACE_ID,
+            "components": FLIGHT_SCHEMA,
+        },
+        {
+            "type": "update_data_model",
+            "surfaceId": SURFACE_ID,
+            "data": {
+                "origin": origin,
+                "destination": destination,
+                "airline": airline,
+                "price": price,
+            },
+        },
+    ]
+    return json.dumps({"a2ui_operations": operations})
+
+
+SYSTEM_PROMPT = (
+    "You help users find flights. When asked about a flight, call "
+    "display_flight with origin (3-letter code), destination (3-letter "
+    "code), airline, and price (e.g. '$289'). Keep any chat reply to one "
+    "short sentence."
+)
+
+
+agent = Agent(
+    model=OpenAIChat(id="gpt-4o-mini", timeout=120),
+    tools=[display_flight],
+    tool_call_limit=4,
+    description=SYSTEM_PROMPT,
+)

showcase/integrations/agno/src/agents/a2ui_schemas/booked_schema.json

@@ -0,0 +1,20 @@
+[
+  {
+    "id": "root",
+    "component": "Column",
+    "gap": 8,
+    "children": ["title", "detail"]
+  },
+  {
+    "id": "title",
+    "component": "Text",
+    "text": { "path": "/title" },
+    "variant": "h2"
+  },
+  {
+    "id": "detail",
+    "component": "Text",
+    "text": { "path": "/detail" },
+    "variant": "body"
+  }
+]

showcase/integrations/agno/src/agents/a2ui_schemas/flight_schema.json

@@ -0,0 +1,77 @@
+[
+  {
+    "id": "root",
+    "component": "Card",
+    "child": "content"
+  },
+  {
+    "id": "content",
+    "component": "Column",
+    "children": ["title", "route", "meta", "bookButton"]
+  },
+  {
+    "id": "title",
+    "component": "Title",
+    "text": "Flight Details"
+  },
+  {
+    "id": "route",
+    "component": "Row",
+    "justify": "spaceBetween",
+    "align": "center",
+    "children": ["from", "arrow", "to"]
+  },
+  {
+    "id": "from",
+    "component": "Airport",
+    "code": { "path": "/origin" }
+  },
+  {
+    "id": "arrow",
+    "component": "Arrow"
+  },
+  {
+    "id": "to",
+    "component": "Airport",
+    "code": { "path": "/destination" }
+  },
+  {
+    "id": "meta",
+    "component": "Row",
+    "justify": "spaceBetween",
+    "align": "center",
+    "children": ["airline", "price"]
+  },
+  {
+    "id": "airline",
+    "component": "AirlineBadge",
+    "name": { "path": "/airline" }
+  },
+  {
+    "id": "price",
+    "component": "PriceTag",
+    "amount": { "path": "/price" }
+  },
+  {
+    "id": "bookButton",
+    "component": "Button",
+    "variant": "primary",
+    "child": "bookButtonLabel",
+    "action": {
+      "event": {
+        "name": "book_flight",
+        "context": {
+          "origin": { "path": "/origin" },
+          "destination": { "path": "/destination" },
+          "airline": { "path": "/airline" },
+          "price": { "path": "/price" }
+        }
+      }
+    }
+  },
+  {
+    "id": "bookButtonLabel",
+    "component": "Text",
+    "text": "Book flight"
+  }
+]

showcase/integrations/agno/src/app/api/copilotkit-a2ui-fixed-schema/route.ts

@@ -0,0 +1,53 @@
+// Dedicated runtime for the A2UI — Fixed Schema cell. Splitting into its
+// own endpoint lets us set `a2ui.injectA2UITool: false` — the backend Agno
+// agent owns the `display_flight` tool which emits its own
+// `a2ui_operations` container directly in the tool result (no secondary
+// LLM call).
+//
+// Reference:
+// - showcase/integrations/langgraph-python/src/app/api/copilotkit-a2ui-fixed-schema/route.ts
+// - src/agents/a2ui_fixed_agent.py (the Agno backend)
+
+import { NextRequest, NextResponse } from "next/server";
+import {
+  CopilotRuntime,
+  ExperimentalEmptyAdapter,
+  copilotRuntimeNextJSAppRouterEndpoint,
+} from "@copilotkit/runtime";
+import { HttpAgent } from "@ag-ui/client";
+
+const AGENT_URL = process.env.AGENT_URL || "http://localhost:8000";
+
+const a2uiFixedSchemaAgent = new HttpAgent({
+  url: `${AGENT_URL}/a2ui-fixed-schema/agui`,
+});
+
+const runtime = new CopilotRuntime({
+  // @ts-ignore -- see main route.ts
+  agents: { "a2ui-fixed-schema": a2uiFixedSchemaAgent },
+  a2ui: {
+    // The backend agent emits its own `a2ui_operations` container inside
+    // `display_flight` (see src/agents/a2ui_fixed_agent.py). We still run
+    // the A2UI middleware so it detects the container in tool results and
+    // forwards surfaces to the frontend — but we do NOT inject a runtime
+    // `render_a2ui` tool on top of the agent's existing tools.
+    injectA2UITool: false,
+  },
+});
+
+export const POST = async (req: NextRequest) => {
+  try {
+    const { handleRequest } = copilotRuntimeNextJSAppRouterEndpoint({
+      endpoint: "/api/copilotkit-a2ui-fixed-schema",
+      serviceAdapter: new ExperimentalEmptyAdapter(),
+      runtime,
+    });
+    return await handleRequest(req);
+  } catch (error: unknown) {
+    const e = error as { message?: string; stack?: string };
+    return NextResponse.json(
+      { error: e.message, stack: e.stack },
+      { status: 500 },
+    );
+  }
+};