{"id":35359,"date":"2026-11-12T01:22:27","date_gmt":"2026-11-12T00:22:27","guid":{"rendered":"https:\/\/www.angulararchitects.io\/blog\/fewer-tokens-faster-uis-a2ui-macros-for-local-and-cloud-models\/"},"modified":"2026-11-12T01:52:11","modified_gmt":"2026-11-12T00:52:11","slug":"fewer-tokens-faster-uis-a2ui-macros-for-local-and-cloud-models","status":"publish","type":"post","link":"https:\/\/www.angulararchitects.io\/en\/blog\/fewer-tokens-faster-uis-a2ui-macros-for-local-and-cloud-models\/","title":{"rendered":"Fewer Tokens, Faster UIs: A2UI Macros for Local and Cloud Models"},"content":{"rendered":"
\n\t\t\t\n\t\n\t\n\t\t

\n\t\t\tThis is post 12 of 12 in the series “Agentic UI with Angular”<\/em>\t\t<\/p>\n\t\t\t<\/label>\n\n\t\t\t

\n\t\t\t
    \n\t\t\t\t\t\t\t\t\t
  1. Understanding AG-UI: The Standard for Agentic User Interfaces<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  2. AG-UI in Practice: The SDK for TypeScript<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  3. AG-UI End to End: Connecting Server and Client<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  4. Agentic UI with Angular, CopilotKit, and AG-UI<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  5. A2UI in Angular: How AI Generates Dynamic UIs at Runtime<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  6. Integrating A2UI with AG-UI and CopilotKit in Angular<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  7. Custom Catalogs in A2UI: Your Own Components for AI-Generated UIs<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  8. A2UI with a DSL: Controllable Dashboards Optimized for Performance<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  9. Agentic UI with MCP Apps: Tool Results as Interactive Widgets<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  10. MCP Apps in Angular with CopilotKit: Rich Chat Interfaces Instead of Text Responses<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  11. A2UI Express: Token-Optimized Generative UIs for Local and Cloud Models<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  12. Fewer Tokens, Faster UIs: A2UI Macros for Local and Cloud Models<\/span><\/li>\n\t\t\t\t\t\t\t<\/ol>\n\t\t<\/div>\n\t<\/div>\n

    Coarse-grained building blocks instead of single widgets: how A2UI macros make Generative UIs faster and cheaper with cloud models and pave the way for local ones<\/em><\/p>\n

    A2UI describes user interfaces with simple building blocks such as Text<\/code>, Row<\/code>, Column<\/code>, and Button<\/code>. This fine granularity makes the protocol flexible. But it comes at a price: a dashboard with six tiles quickly consists of dozens of components. The model has to generate each of them token by token, which costs time and money. This applies to cloud models and even more to local models that run on your own hardware.<\/p>\n

    The solution is coarse-grained building blocks. Instead of describing every widget, the model only names the tiles it needs and their most important properties. The server then resolves these building blocks into regular A2UI. A2UI macros<\/a> build on this idea.<\/p>\n

    In this article, I show how A2UI macros work, how to use them with A2UI Express, and how a simple, generic macro mechanism brings them to TypeScript.<\/p>\n

    \ud83d\udcc2 Source code<\/a> (branch AGU-a2ui-express<\/code>)<\/p>\n

    \ud83d\udcc2 Source code updated for Gemma 4<\/a> (branch AGU-gemma<\/code>)<\/p>\n

    A Dashboard Made of Tiles<\/h2>\n

    The example application contains a dashboard that users describe in natural language. An agent assembles the requested tiles from this description:<\/p>\n

    \"A<\/p>\n

    In the first version, the model generated the entire A2UI itself. A single dashboard took about 40 seconds and consumed more than 46,000 tokens. The main drivers were a long prompt with examples and the extensive structure the model had to write.<\/p>\n

    A DSL on a higher level of abstraction is much more efficient. It describes each tile with a handful of properties, such as a route or a maximum number of rows. The model only generates this compact description, and code on the server translates it into A2UI. This brought the duration down to a few seconds and cut the token consumption by a factor of 30. An additional cache for the DSL brings recurring dashboards down to about 0.1 seconds:<\/p>\n

    \"The<\/p>\n

    My article How I Made My A2UI Dashboard 300 Times Faster<\/a> describes the details.<\/p>\n

    The DSL has also proven itself with local models. With it, moving the fairly complex dashboard to Gemma 4 took little effort. You can run this open-weight model on your own hardware. My article Optimizing Agentic Applications for Local Models<\/a> has more on this.<\/p>\n

    A2UI Macros: The DSL Comes to the A2UI SDKs<\/h2>\n

    You could always define your own DSL, but you had to specify it and translate it into A2UI yourself. The Python SDK for A2UI was the first to support such a DSL at SDK level, which simplifies the implementation. With macros, you define composite components on the server. <\/p>\n

    This article uses TypeScript, but a short look at the original Python API shows the idea behind macros. There, a macro is a function that returns a tree of base components:<\/p>\n

    # Example from the documentation of the A2UI Python SDK (shortened)\nfrom a2ui.builder.v1_0 import Action, Button, Card, Column, DynamicString, Text\nfrom a2ui.transformers.macros import macro\n\n@macro\ndef ProductCard(title: DynamicString, price: str, on_buy: Action) -> Card:\n    """Renders a product showcase card.\n\n    Args:\n        title: Display name of the product.\n        price: Formatted price string.\n        on_buy: Action triggered when the user clicks buy.\n    """\n    return Card(\n        child=Column(\n            children=[\n                Text(text=title, variant="body"),\n                Text(text=price, variant="caption"),\n                Button(child=Text(text="Buy Now"), action=on_buy),\n            ]\n        )\n    )<\/code><\/pre>\n
    A so-called MacroExpander<\/code> then resolves the macros into A2UI. It works recursively, so macros can build on other macros. The documentation on A2UI macros<\/a> has more details.<\/p>\n
    A Dashboard in A2UI Express<\/h3>\n
    The example application defines a macro for each tile. In A2UI Express, the compact inference format of A2UI, the model describes the dashboard from above like this:<\/p>\n
    <a2ui>\nroot = Dashboard([\n  BoardingPasses(2),\n  BookedFlightsList(showWeather=false),\n  FlightSearch("Graz", "Hamburg"),\n  RentalCars(),\n  Hotels(),\n  WeatherList()\n])\n<\/a2ui><\/code><\/pre>\n
    The macro calls take required arguments by position and optional arguments by name. Dashboard<\/code> is a macro itself and takes the tiles as children. The previous article<\/a> shows how A2UI Express works in detail.<\/p>\n
    These few lines expand into regular A2UI. The call BookedFlightsList(showWeather=false)<\/code> alone turns into 11 components:<\/p>\n
    "components": [\n  { "id": "root", "component": "Column", "children": ["root_children_0", "root_children_1", [...]] },\n  [...]\n  { "id": "root_children_1", "component": "Card", "child": "root_children_1-body" },\n  { "id": "root_children_1-body", "component": "Column", "children": ["root_children_1-title", "root_children_1-list", "root_children_1-empty"] },\n  { "id": "root_children_1-title", "component": "Text", "text": "My booked flights", "variant": "h2" },\n  {\n    "id": "root_children_1-list",\n    "component": "Column",\n    "children": { "componentId": "root_children_1-row", "path": "\/root_children_1\/flights" }\n  },\n  { "id": "root_children_1-row", "component": "Row", "align": "start", "children": ["root_children_1-row-col"] },\n  { "id": "root_children_1-row-col", "component": "Column", "weight": 3, "children": ["root_children_1-row-route", "root_children_1-row-meta", "root_children_1-row-btn"] },\n  { "id": "root_children_1-row-route", "component": "Text", "text": { "path": "route" }, "variant": "h3" },\n  { "id": "root_children_1-row-meta", "component": "Text", "text": { "path": "meta" }, "variant": "body" },\n  { "id": "root_children_1-empty", "component": "Text", "text": { "path": "\/root_children_1\/emptyMessage" }, "variant": "body" },\n  {\n    "id": "root_children_1-row-btn",\n    "component": "Button",\n    "child": "root_children_1-row-btn-label",\n    "action": {\n      "event": {\n        "name": "checkIn",\n        "context": { "flightId": { "path": "id" } }\n      }\n    }\n  },\n  { "id": "root_children_1-row-btn-label", "component": "Text", "text": "Check in" },\n  [...]\n]<\/code><\/pre>\n
    The column root_children_1-list<\/code> uses a template: the client repeats the row root_children_1-row<\/code> for each entry of the list \/root_children_1\/flights<\/code> in the data model. Inside the template, relative paths such as route<\/code> refer to the current entry.<\/p>\n
    The entire dashboard consists of 45 components. As compact JSON, this structure takes about 1,300 tokens, the Express code with macros fewer than 50. I counted with OpenAI's tokenizer o200k_base<\/code>. These numbers do not include the data itself, as the components get it via data binding.<\/p>\n
    <\/p>\n
    Agentic UI with Angular<\/h3>\n
    If you want to embed Generative UIs cleanly into larger Angular applications rather than just here and there: In my book Agentic UI with Angular, I cover the underlying patterns and trade-offs in depth, including DSLs, caching, and open standards such as AG-UI, A2UI, and MCP.<\/p>\n
    \"Cover<\/a><\/p>\n
    More about the eBook \u2192<\/a>\n<\/div>\n<\/p>\n
    Implementation with TypeScript<\/h2>\n
    When I wrote this article, the TypeScript SDK @a2ui\/agent<\/code> did not support macros yet. The example application therefore combines the Express parser of the SDK with a simple, generic macro mechanism of its own. It consists of about 170 lines and knows nothing about the dashboard.<\/p>\n
    In this article, I treat this macro mechanism as a black box and only show how the application uses it. If you are interested in its implementation, you find it in the example repository<\/a>. The following diagram shows how the parser and the macro mechanism work together:<\/p>\n
    \"The<\/p>\n
    Defining Macros<\/h3>\n
    A macro consists of a Zod schema for its arguments, an optional function load<\/code> for its data, and a function render<\/code> that returns the components replacing the macro. For each tile, a Zod schema describes the arguments:<\/p>\n
    \/\/ ai-server\/src\/mastra\/dashboard-dsl\/dashboard-spec.ts\nimport { z } from 'zod';\n\nimport type { MacroInput } from '..\/a2ui\/simple-macros\/macro.js';\n\nconst positiveInt = z.number().int().positive();\n\n[...]\n\nexport const bookedFlightsListSchema = z.object({\n  component: z.literal('BookedFlightsList'),\n  showCheckInButton: z\n    .boolean()\n    .optional()\n    .describe(\n      'Whether to render a "Check in" button per booked flight. Defaults to true.',\n    ),\n  showWeather: z\n    .boolean()\n    .optional()\n    .describe(\n      'Whether to enrich each flight entry with a weather forecast for the destination. Defaults to true.',\n    ),\n  maxRows: positiveInt\n    .optional()\n    .describe(\n      'Maximum number of booked flights to list. Defaults to no limit.',\n    ),\n});\n\nexport type BookedFlightsListNode = MacroInput<typeof bookedFlightsListSchema>;\n\n[...]\n\nexport const dashboardSchema = z.object({\n  component: z.literal('Dashboard'),\n  children: z\n    .array(z.string())\n    .meta({ $ref: 'common_types.json#\/$defs\/ChildList' }),\n});\n\nexport type DashboardNode = MacroInput<typeof dashboardSchema>;<\/code><\/pre>\n
    As with every A2UI component, the property component<\/code> defines the name. The descriptions end up in the JSON schema of the catalog. For the children, the schema dashboardSchema<\/code> refers to the type ChildList<\/code> from the common types of A2UI. This way, the parser treats the calls in this list as child components.<\/p>\n
    The type MacroInput<\/code> of the macro mechanism describes a macro call as a node: an object with the arguments and the id that the Express parser assigns to the call. The functions load<\/code> and render<\/code> receive such a node.<\/p>\n
    The object dashboardMacros<\/code> combines each schema with a loader and a renderer:<\/p>\n
    \/\/ ai-server\/src\/mastra\/dashboard-dsl\/dashboard-macros.ts\nimport { defineMacro } from '..\/a2ui\/simple-macros\/macro.js';\n[...]\n\nexport const dashboardMacros = {\n  Dashboard: defineMacro({\n    schema: dashboardSchema,\n    render: (node) => {\n      return buildDashboard(node);\n    },\n  }),\n  [...]\n  BookedFlightsList: defineMacro({\n    schema: bookedFlightsListSchema,\n    load: (node) => {\n      return loadBookedFlightsList(node);\n    },\n    render: (node) => {\n      return buildBookedFlightsList(node);\n    },\n  }),\n  [...]\n};<\/code><\/pre>\n
    The function defineMacro<\/code> returns the macro unchanged. It only exists so that TypeScript derives the type of the node from the schema.<\/p>\n
    Loading and Rendering<\/h3>\n
    The root component Dashboard<\/code> is a macro, too. It needs no data, and its renderer turns it into a Column<\/code> with the same children:<\/p>\n
    \/\/ ai-server\/src\/mastra\/dashboard-dsl\/dashboard-renderers.ts\nexport function buildDashboard(node: DashboardNode): A2uiComponent[] {\n  return [{ id: node.id, component: 'Column', children: node.children }];\n}<\/code><\/pre>\n
    The loader of the tile BookedFlightsList<\/code> returns the booked flights in the shape the components bind to:<\/p>\n
    \/\/ ai-server\/src\/mastra\/dashboard-dsl\/dashboard-loaders.ts (simplified)\nexport async function loadBookedFlightsList(\n  node: BookedFlightsListNode,\n): Promise<BookedFlightsListData> {\n  const flights = [\n    { id: 1, route: 'Graz \u2192 Hamburg', meta: '2026-11-20 \u00b7 On time' },\n    { id: 2, route: 'Hamburg \u2192 Graz', meta: '2026-11-20 \u00b7 On time' },\n    { id: 516, route: 'Graz \u2192 Paris', meta: '2026-11-21 \u00b7 On time' },\n    { id: 50, route: 'Wien \u2192 Klagenfurt', meta: '2026-11-24 \u00b7 Delayed by 30 min' },\n  ];\n  const selected = node.maxRows ? flights.slice(0, node.maxRows) : flights;\n  const emptyMessage =\n    selected.length === 0 ? 'You have no booked flights.' : '';\n  return { flights: selected, emptyMessage };\n}<\/code><\/pre>\n
    To keep the example simple, this version returns hardcoded flights. The example application loads the booked flights via HTTP instead and adds a weather forecast for the destination if showWeather<\/code> is true<\/code>.<\/p>\n
    Its renderer returns the components shown above:<\/p>\n
    \/\/ ai-server\/src\/mastra\/dashboard-dsl\/dashboard-renderers.ts\nexport function buildBookedFlightsList(\n  node: BookedFlightsListNode,\n): A2uiComponent[] {\n  const id = node.id;\n  const bodyId = `${id}-body`;\n  [...]\n  const listId = `${id}-list`;\n  const rowId = `${id}-row`;\n  [...]\n\n  const components: A2uiComponent[] = [\n    { id, component: 'Card', child: bodyId },\n    [...]\n    {\n      id: listId,\n      component: 'Column',\n      children: { componentId: rowId, path: `\/${id}\/flights` },\n    },\n    [...]\n  ];\n\n  [...]\n  return components;\n}<\/code><\/pre>\n
    The renderer does not receive the loaded data. The components it returns refer to the data via data binding. This keeps structure and data apart. Every renderer follows three rules:<\/p>\n