Universal block reference library and GDM visualization tracer

A2UI Visual Atom Catalogue

In A2UI Hub, I covered the background. This article picks up from there.

Welcome to techmusings A2UI core design system. This multi-part reference compiles 100+ components precompiled into optimized serverside HTML and SVGs.

A2UI separates components into explicit Reading Experience versus Media and Data Visualization groups. By precompiling these blocks server-side, we bypass rigid sandbox constraints, making elements instantaneous, light, and perfectly responsive.

Catalogue Organization & Reference Links

Explore the complete component catalogue split deterministically across two dedicated, high-fidelity tracer articles:

• Part 1: Reading & Documentation Reference Foundations, lists, code cards, API specifications, and structural UI elements. View Part 1
• Part 2: Media, Data & Social Reference Vector charts, SVG activity trackers, CSS carousels, audio players, and engagement CTA cards. View Part 2

Automated Multi-Surface Testing & Validation

Every atom's surface compatibility is validated automatically on each commit, ensuring standard rendering boundaries across 4 distinct GWS surfaces:

MeetStudio Backlog & Roadmaps

The entire system automatically regenerates and synchronizes to Google Firestore upon running the deployment sync hooks. Happy system architecture tracing!

#A2UI #DesignSystem #Techmusings #MeetStudio

High-Fidelity Element Tracing & Live Visual Demonstrations

A2UI Block Catalogue Reference

Category: Media

This section compiles and showcases the 14 core atoms defined under the Media vocabulary in our universal system schema.

Atom: carousel

The "carousel" component rendering demonstration on the live blog stage is displayed below:

Premium LayoutElegant dark mode themes and glassmorphic panels built-in

Lightning PerformanceZero client-side JS overhead, compiles into static optimized assets

‹‹

››

Pure CSS Responsive Sliding Carousel Component

Atom: color_swatch_grid

The "color_swatch_grid" component rendering demonstration on the live blog stage is displayed below:

Atom: diagram

The "diagram" component rendering demonstration on the live blog stage is displayed below:

Hover to zoom · Component Synchronization and Publish Pipeline Flowchart

Atom: framed_screenshot

The "framed_screenshot" component rendering demonstration on the live blog stage is displayed below:

Interactive Google Meet preview panel

Atom: gallery

The "gallery" component rendering demonstration on the live blog stage is displayed below:

Zero-dependency CSS Lightbox Grid demonstration

✕

✕

✕

Atom: image

The "image" component rendering demonstration on the live blog stage is displayed below:

Interactive design mockup preview

Atom: image_hotspots

The "image_hotspots" component rendering demonstration on the live blog stage is displayed below:

Atom: image_pair

The "image_pair" component rendering demonstration on the live blog stage is displayed below:

Light Theme View

Dark Theme Overrides

Atom: image_with_caption

The "image_with_caption" component rendering demonstration on the live blog stage is displayed below:

Atom: pdf_preview

The "pdf_preview" component rendering demonstration on the live blog stage is displayed below:

Atom: video_card

The "video_card" component rendering demonstration on the live blog stage is displayed below:

Atom: video_pair

The "video_pair" component rendering demonstration on the live blog stage is displayed below:

Atom: video_thumbnail

The "video_thumbnail" component rendering demonstration on the live blog stage is displayed below:

Atom: zoomable_image

The "zoomable_image" component rendering demonstration on the live blog stage is displayed below:

Hover to zoom

Category: Data Visualization

This section compiles and showcases the 26 core atoms defined under the Data Visualization vocabulary in our universal system schema.

Atom: benchmark_comparison

The "benchmark_comparison" component rendering demonstration on the live blog stage is displayed below:

Atom: chartjs_bar

The "chartjs_bar" component rendering demonstration on the live blog stage is displayed below:

Atom: chartjs_line

The "chartjs_line" component rendering demonstration on the live blog stage is displayed below:

Atom: data_table_sortable

The "data_table_sortable" component rendering demonstration on the live blog stage is displayed below:

Atom: donut_stat

The "donut_stat" component rendering demonstration on the live blog stage is displayed below:

Atom: heatmap

The "heatmap" component rendering demonstration on the live blog stage is displayed below:

Atom: task_list

The "task_list" component rendering demonstration on the live blog stage is displayed below:

Atom: sentiment_summary

The "sentiment_summary" component rendering demonstration on the live blog stage is displayed below:

Atom: metric_comparison_card

The "metric_comparison_card" component rendering demonstration on the live blog stage is displayed below:

Atom: metric_delta

The "metric_delta" component rendering demonstration on the live blog stage is displayed below:

Atom: mini_sparkline_set

The "mini_sparkline_set" component rendering demonstration on the live blog stage is displayed below:

Atom: progress_bar

The "progress_bar" component rendering demonstration on the live blog stage is displayed below:

Atom: progress_circle

The "progress_circle" component rendering demonstration on the live blog stage is displayed below:

Atom: sparkline

The "sparkline" component rendering demonstration on the live blog stage is displayed below:

Atom: status_dashboard

The "status_dashboard" component rendering demonstration on the live blog stage is displayed below:

Atom: trend_indicator

The "trend_indicator" component rendering demonstration on the live blog stage is displayed below:

Atom: uptime_timeline

The "uptime_timeline" component rendering demonstration on the live blog stage is displayed below:

Atom: conversion_funnel

The "conversion_funnel" component rendering demonstration on the live blog stage is displayed below:

Atom: gauge_sla

The "gauge_sla" component rendering demonstration on the live blog stage is displayed below:

Atom: stacked_area

The "stacked_area" component rendering demonstration on the live blog stage is displayed below:

Atom: scatter_trend

The "scatter_trend" component rendering demonstration on the live blog stage is displayed below:

Atom: call_mood_board

The "call_mood_board" component rendering demonstration on the live blog stage is displayed below:

Atom: github_activity_grid

The "github_activity_grid" component rendering demonstration on the live blog stage is displayed below:

Atom: punch_card

The "punch_card" component rendering demonstration on the live blog stage is displayed below:

Atom: sankey_flow

The "sankey_flow" component rendering demonstration on the live blog stage is displayed below:

Atom: cohort_retention

The "cohort_retention" component rendering demonstration on the live blog stage is displayed below:

Category: Social & Engagement

This section compiles and showcases the 16 core atoms defined under the Social & Engagement vocabulary in our universal system schema.

Atom: author_bio_card

The "author_bio_card" component rendering demonstration on the live blog stage is displayed below:

Curtis Krygier

Systems Architect and full-stack software crafter. Specialized in Google Workspace automations, Home Assistant integrations, and elegant UI design systems.

Atom: avatar_group

The "avatar_group" component rendering demonstration on the live blog stage is displayed below:

Atom: contributor_list

The "contributor_list" component rendering demonstration on the live blog stage is displayed below:

Atom: customer_logo_grid

The "customer_logo_grid" component rendering demonstration on the live blog stage is displayed below:

Atom: expert_endorsement

The "expert_endorsement" component rendering demonstration on the live blog stage is displayed below:

Atom: follow_button

The "follow_button" component rendering demonstration on the live blog stage is displayed below:

Atom: follow_cta

The "follow_cta" component rendering demonstration on the live blog stage is displayed below:

Atom: media_mention_card

The "media_mention_card" component rendering demonstration on the live blog stage is displayed below:

Atom: newsletter_cta

The "newsletter_cta" component rendering demonstration on the live blog stage is displayed below:

Atom: reaction_group

The "reaction_group" component rendering demonstration on the live blog stage is displayed below:

Atom: review_callout

The "review_callout" component rendering demonstration on the live blog stage is displayed below:

Atom: share_quote

The "share_quote" component rendering demonstration on the live blog stage is displayed below:

Atom: social_feed_embed

The "social_feed_embed" component rendering demonstration on the live blog stage is displayed below:

Atom: social_share_bar

The "social_share_bar" component rendering demonstration on the live blog stage is displayed below:

Atom: social_proof_banner

The "social_proof_banner" component rendering demonstration on the live blog stage is displayed below:

Atom: testimonial_card

The "testimonial_card" component rendering demonstration on the live blog stage is displayed below:

Category: Video & Audio

This section compiles and showcases the 3 core atoms defined under the Video & Audio vocabulary in our universal system schema.

Atom: audio_link

The "audio_link" component rendering demonstration on the live blog stage is displayed below:

Atom: audio_player

The "audio_player" component rendering demonstration on the live blog stage is displayed below:

Atom: youtube

The "youtube" component rendering demonstration on the live blog stage is displayed below:

Google Meet Add-on interactive stage showcase

Category: External Embeds

This section compiles and showcases the 8 core atoms defined under the External Embeds vocabulary in our universal system schema.

Atom: embed_codepen

The "embed_codepen" component rendering demonstration on the live blog stage is displayed below:

Atom: embed_gist

The "embed_gist" component rendering demonstration on the live blog stage is displayed below:

Atom: embed_google_slides

The "embed_google_slides" component rendering demonstration on the live blog stage is displayed below:

Atom: embed_stackblitz

The "embed_stackblitz" component rendering demonstration on the live blog stage is displayed below:

Atom: embed_tweet

The "embed_tweet" component rendering demonstration on the live blog stage is displayed below:

Atom: figma_embed

The "figma_embed" component rendering demonstration on the live blog stage is displayed below:

Atom: lottie_animation

The "lottie_animation" component rendering demonstration on the live blog stage is displayed below:

Atom: live_demo_embed

The "live_demo_embed" component rendering demonstration on the live blog stage is displayed below:

Category: Google Workspace

This section compiles and showcases the 6 core atoms defined under the Google Workspace vocabulary in our universal system schema.

Atom: gmail_inbox

The "gmail_inbox" component rendering demonstration on the live blog stage is displayed below:

Atom: gmail_unread_count

The "gmail_unread_count" component rendering demonstration on the live blog stage is displayed below:

Atom: user_profile_card

The "user_profile_card" component rendering demonstration on the live blog stage is displayed below:

Atom: drive_storage_usage

The "drive_storage_usage" component rendering demonstration on the live blog stage is displayed below:

Atom: tasks_today

The "tasks_today" component rendering demonstration on the live blog stage is displayed below:

Atom: sheet_form_submit

The "sheet_form_submit" component rendering demonstration on the live blog stage is displayed below:

Tracer compilation hook complete. All elements successfully traced.

#A2UI #ComponentLibrary #Techmusings #Deterministic

High-Fidelity Element Tracing & Live Visual Demonstrations

A2UI Block Catalogue Reference

Category: Foundations

This section compiles and showcases the 5 core atoms defined under the Foundations vocabulary in our universal system schema.

Atom: body

The "body" component rendering demonstration on the live blog stage is displayed below:

This is a standard prose body block demonstrating inline bold, italics, and standard code blocks. It is fully optimized for readability and responsive layout scaling across all modern web browsers.

Atom: closing

The "closing" component rendering demonstration on the live blog stage is displayed below:

That concludes the core Reading & Documentation reference. Proceed to the Media & Visual page to explore rich visualization blocks.

#A2UI #DesignSystem #WebRef

Atom: heading

The "heading" component rendering demonstration on the live blog stage is displayed below:

Interactive Element Reference

Atom: intro

The "intro" component rendering demonstration on the live blog stage is displayed below:

In the first article, picks up here.

All components are rendered server-side as standard clean HTML with zero inline JS requirements.

Atom: subheading

The "subheading" component rendering demonstration on the live blog stage is displayed below:

Subsection Highlights

Category: Reading Experience

This section compiles and showcases the 9 core atoms defined under the Reading Experience vocabulary in our universal system schema.

Atom: article_hero

The "article_hero" component rendering demonstration on the live blog stage is displayed below:

High-Fidelity Component Reference Library

A2UI Block Catalogue

Atom: article_series_nav

The "article_series_nav" component rendering demonstration on the live blog stage is displayed below:

Atom: post_metadata_bar

The "post_metadata_bar" component rendering demonstration on the live blog stage is displayed below:

Atom: reading_progress_bar

The "reading_progress_bar" component rendering demonstration on the live blog stage is displayed below:

Atom: scroll_to_top

The "scroll_to_top" component rendering demonstration on the live blog stage is displayed below:

Atom: table_of_contents

The "table_of_contents" component rendering demonstration on the live blog stage is displayed below:

Atom: time_estimate

The "time_estimate" component rendering demonstration on the live blog stage is displayed below:

Atom: related_posts_grid

The "related_posts_grid" component rendering demonstration on the live blog stage is displayed below:

Atom: series_overview_card

The "series_overview_card" component rendering demonstration on the live blog stage is displayed below:

Category: Documentation

This section compiles and showcases the 11 core atoms defined under the Documentation vocabulary in our universal system schema.

Atom: changelog_entry

The "changelog_entry" component rendering demonstration on the live blog stage is displayed below:

Atom: difficulty_badge

The "difficulty_badge" component rendering demonstration on the live blog stage is displayed below:

Atom: footnote

The "footnote" component rendering demonstration on the live blog stage is displayed below:

Atom: footnote_group

The "footnote_group" component rendering demonstration on the live blog stage is displayed below:

Atom: further_reading

The "further_reading" component rendering demonstration on the live blog stage is displayed below:

Atom: glossary_term

The "glossary_term" component rendering demonstration on the live blog stage is displayed below:

Atom: release_notes

The "release_notes" component rendering demonstration on the live blog stage is displayed below:

Atom: resources_list

The "resources_list" component rendering demonstration on the live blog stage is displayed below:

Atom: table

The "table" component rendering demonstration on the live blog stage is displayed below:

Atom: tabs

The "tabs" component rendering demonstration on the live blog stage is displayed below:

httpx>=0.24.0
pyyaml>=6.0
pytest>=7.3

from setuptools import setup, find_packages
setup(name='a2ui', version='2.1.0')

Atom: timeline

The "timeline" component rendering demonstration on the live blog stage is displayed below:

Category: Navigation & Structure

This section compiles and showcases the 6 core atoms defined under the Navigation & Structure vocabulary in our universal system schema.

Atom: anchor_list

The "anchor_list" component rendering demonstration on the live blog stage is displayed below:

Atom: breadcrumb

The "breadcrumb" component rendering demonstration on the live blog stage is displayed below:

Atom: faq_accordion

The "faq_accordion" component rendering demonstration on the live blog stage is displayed below:

Atom: pagination

The "pagination" component rendering demonstration on the live blog stage is displayed below:

Atom: stepper

The "stepper" component rendering demonstration on the live blog stage is displayed below:

Atom: tab_bar

The "tab_bar" component rendering demonstration on the live blog stage is displayed below:

Category: Content Structure

This section compiles and showcases the 13 core atoms defined under the Content Structure vocabulary in our universal system schema.

Atom: bullet_list

The "bullet_list" component rendering demonstration on the live blog stage is displayed below:

• Server-Side SVG No rendering cost on client browser
• Pure CSS Interactions Tabs, modally expandable panels, and lightboxes require zero Javascript
• High Surface Portability Full compatibility guarantees with GWS Add-ons

Atom: callout

The "callout" component rendering demonstration on the live blog stage is displayed below:

Atom: caution_block

The "caution_block" component rendering demonstration on the live blog stage is displayed below:

Atom: checklist_interactive

The "checklist_interactive" component rendering demonstration on the live blog stage is displayed below:

• Ensure gcloud is logged in and configured
• Verify all tests pass with pytest
• Run publish_catalogue.py to sync live pages

Atom: divider

The "divider" component rendering demonstration on the live blog stage is displayed below:

Atom: key_takeaways

The "key_takeaways" component rendering demonstration on the live blog stage is displayed below:

Atom: key_value

The "key_value" component rendering demonstration on the live blog stage is displayed below:

Default Global Parameters

Atom: learning_objectives

The "learning_objectives" component rendering demonstration on the live blog stage is displayed below:

Atom: pipeline

The "pipeline" component rendering demonstration on the live blog stage is displayed below:

Local Sandbox ──► Commit Hook ──► Firestore Sync ──► Nginx Serve

Atom: progress_checkpoint

The "progress_checkpoint" component rendering demonstration on the live blog stage is displayed below:

Atom: sidebar_note

The "sidebar_note" component rendering demonstration on the live blog stage is displayed below:

Atom: steps

The "steps" component rendering demonstration on the live blog stage is displayed below:

1. 1
   Import
   Include the A2UI web stylesheet inside your page head
2. 2
   Compile
   Feed block dictionaries into the Python web_article.render() function
3. 3
   Inject
   Inject the compiled safe HTML output directly into your article body container

Atom: summary_box

The "summary_box" component rendering demonstration on the live blog stage is displayed below:

Category: Text & Quotes

This section compiles and showcases the 3 core atoms defined under the Text & Quotes vocabulary in our universal system schema.

Atom: blockquote_with_avatar

The "blockquote_with_avatar" component rendering demonstration on the live blog stage is displayed below:

Atom: pull_stat

The "pull_stat" component rendering demonstration on the live blog stage is displayed below:

Atom: quote

The "quote" component rendering demonstration on the live blog stage is displayed below:

The details are not the details. They make the design.

Category: Containers & Modals

This section compiles and showcases the 7 core atoms defined under the Containers & Modals vocabulary in our universal system schema.

Atom: accordion_item

The "accordion_item" component rendering demonstration on the live blog stage is displayed below:

Atom: collapsible_panel

The "collapsible_panel" component rendering demonstration on the live blog stage is displayed below:

Atom: css_modal

The "css_modal" component rendering demonstration on the live blog stage is displayed below:

Atom: css_slide_panel

The "css_slide_panel" component rendering demonstration on the live blog stage is displayed below:

Atom: flip_card

The "flip_card" component rendering demonstration on the live blog stage is displayed below:

Atom: hover_card

The "hover_card" component rendering demonstration on the live blog stage is displayed below:

Atom: tooltip

The "tooltip" component rendering demonstration on the live blog stage is displayed below:

Category: Cards & Components

This section compiles and showcases the 6 core atoms defined under the Cards & Components vocabulary in our universal system schema.

Atom: badge_group

The "badge_group" component rendering demonstration on the live blog stage is displayed below:

Atom: notification_badge

The "notification_badge" component rendering demonstration on the live blog stage is displayed below:

Atom: rating_stars

The "rating_stars" component rendering demonstration on the live blog stage is displayed below:

Atom: star_rating_display

The "star_rating_display" component rendering demonstration on the live blog stage is displayed below:

Atom: stat_card

The "stat_card" component rendering demonstration on the live blog stage is displayed below:

Atom: toggle_switch

The "toggle_switch" component rendering demonstration on the live blog stage is displayed below:

Category: Code & Technical

This section compiles and showcases the 11 core atoms defined under the Code & Technical vocabulary in our universal system schema.

Atom: annotated_code

The "annotated_code" component rendering demonstration on the live blog stage is displayed below:

def publish_post(post_id, title, body_html):1    token = get_auth_token()2    doc = {        "fields": {            "title": {"stringValue": title},            "body": {"stringValue": body_html},            "topic": {"stringValue": "a2ui"}        }    }    return patch_firestore_document(post_id, doc, token)3

Atom: api_param_table

The "api_param_table" component rendering demonstration on the live blog stage is displayed below:

Atom: api_reference

The "api_reference" component rendering demonstration on the live blog stage is displayed below:

Atom: before_after

The "before_after" component rendering demonstration on the live blog stage is displayed below:

# Legacy block loop
for b in blocks:
    html += render_block_v1(b)

# Optimized registry lookup
html = '\n\n'.join(_RENDERERS[b['type']](b) for b in blocks if b['type'] in _RENDERERS)

Comparison of block iteration and dispatch overhead

Atom: code

The "code" component rendering demonstration on the live blog stage is displayed below:

def render_svg_surface(atom_type, data):
    # Compiles high-fidelity SVG templates directly on server
    return render_web_article_block(atom_type, data)

Atom: code_diff

The "code_diff" component rendering demonstration on the live blog stage is displayed below:

Atom: code_snippet_pair

The "code_snippet_pair" component rendering demonstration on the live blog stage is displayed below:

Atom: http_request_block

The "http_request_block" component rendering demonstration on the live blog stage is displayed below:

Atom: tabbed_code

The "tabbed_code" component rendering demonstration on the live blog stage is displayed below:

print('Initializing A2UI engine...')

Atom: terminal_block

The "terminal_block" component rendering demonstration on the live blog stage is displayed below:

Atom: file_tree

The "file_tree" component rendering demonstration on the live blog stage is displayed below:

Category: Design Tools

This section compiles and showcases the 6 core atoms defined under the Design Tools vocabulary in our universal system schema.

Atom: css_dropdown_menu

The "css_dropdown_menu" component rendering demonstration on the live blog stage is displayed below:

Atom: custom_checkbox_group

The "custom_checkbox_group" component rendering demonstration on the live blog stage is displayed below:

Atom: expandable_list

The "expandable_list" component rendering demonstration on the live blog stage is displayed below:

Atom: poll_block

The "poll_block" component rendering demonstration on the live blog stage is displayed below:

Atom: segmented_control

The "segmented_control" component rendering demonstration on the live blog stage is displayed below:

Atom: star_rating_input

The "star_rating_input" component rendering demonstration on the live blog stage is displayed below:

Category: Commerce & Pricing

This section compiles and showcases the 2 core atoms defined under the Commerce & Pricing vocabulary in our universal system schema.

Atom: pricing_tier_card

The "pricing_tier_card" component rendering demonstration on the live blog stage is displayed below:

Atom: pricing_tier_group

The "pricing_tier_group" component rendering demonstration on the live blog stage is displayed below:

Category: Comparison & Analysis

This section compiles and showcases the 8 core atoms defined under the Comparison & Analysis vocabulary in our universal system schema.

Atom: capability_checklist

The "capability_checklist" component rendering demonstration on the live blog stage is displayed below:

Atom: comparison_grid

The "comparison_grid" component rendering demonstration on the live blog stage is displayed below:

Atom: feature_matrix

The "feature_matrix" component rendering demonstration on the live blog stage is displayed below:

Atom: pros_cons_list

The "pros_cons_list" component rendering demonstration on the live blog stage is displayed below:

Atom: product_spec_table

The "product_spec_table" component rendering demonstration on the live blog stage is displayed below:

Atom: rating_comparison

The "rating_comparison" component rendering demonstration on the live blog stage is displayed below:

Atom: side_by_side_spec

The "side_by_side_spec" component rendering demonstration on the live blog stage is displayed below:

Atom: versus_block

The "versus_block" component rendering demonstration on the live blog stage is displayed below:

Category: Inline Tools

This section compiles and showcases the 4 core atoms defined under the Inline Tools vocabulary in our universal system schema.

Atom: abbr_tooltip

The "abbr_tooltip" component rendering demonstration on the live blog stage is displayed below:

Atom: copy_to_clipboard

The "copy_to_clipboard" component rendering demonstration on the live blog stage is displayed below:

Atom: expandable_text

The "expandable_text" component rendering demonstration on the live blog stage is displayed below:

Atom: glossary_inline

The "glossary_inline" component rendering demonstration on the live blog stage is displayed below:

Category: Technical Reference

This section compiles and showcases the 7 core atoms defined under the Technical Reference vocabulary in our universal system schema.

Atom: cli_command

The "cli_command" component rendering demonstration on the live blog stage is displayed below:

Atom: copy_code_button

The "copy_code_button" component rendering demonstration on the live blog stage is displayed below:

Atom: env_var_list

The "env_var_list" component rendering demonstration on the live blog stage is displayed below:

Atom: json_tree_viewer

The "json_tree_viewer" component rendering demonstration on the live blog stage is displayed below:

Atom: keyboard_shortcut

The "keyboard_shortcut" component rendering demonstration on the live blog stage is displayed below:

Atom: log_output

The "log_output" component rendering demonstration on the live blog stage is displayed below:

Atom: prerequisite_checklist

The "prerequisite_checklist" component rendering demonstration on the live blog stage is displayed below:

Category: Warnings & Status

This section compiles and showcases the 6 core atoms defined under the Warnings & Status vocabulary in our universal system schema.

Atom: action_required_card

The "action_required_card" component rendering demonstration on the live blog stage is displayed below:

Atom: alert_banner

The "alert_banner" component rendering demonstration on the live blog stage is displayed below:

Atom: deprecation_notice

The "deprecation_notice" component rendering demonstration on the live blog stage is displayed below:

Atom: experimental_banner

The "experimental_banner" component rendering demonstration on the live blog stage is displayed below:

Atom: status_pill

The "status_pill" component rendering demonstration on the live blog stage is displayed below:

Atom: version_badge

The "version_badge" component rendering demonstration on the live blog stage is displayed below:

Category: UI Utilities

This section compiles and showcases the 7 core atoms defined under the UI Utilities vocabulary in our universal system schema.

Atom: command_palette

The "command_palette" component rendering demonstration on the live blog stage is displayed below:

Atom: empty_state

The "empty_state" component rendering demonstration on the live blog stage is displayed below:

Atom: inline_feedback_message

The "inline_feedback_message" component rendering demonstration on the live blog stage is displayed below:

Atom: loading_skeleton

The "loading_skeleton" component rendering demonstration on the live blog stage is displayed below:

Atom: search_result_card

The "search_result_card" component rendering demonstration on the live blog stage is displayed below:

Atom: spinner

The "spinner" component rendering demonstration on the live blog stage is displayed below:

Atom: toast_notification

The "toast_notification" component rendering demonstration on the live blog stage is displayed below:

Category: Utilities & Links

This section compiles and showcases the 3 core atoms defined under the Utilities & Links vocabulary in our universal system schema.

Atom: document_link

The "document_link" component rendering demonstration on the live blog stage is displayed below:

Atom: github_repo_card

The "github_repo_card" component rendering demonstration on the live blog stage is displayed below:

Atom: repo_links

The "repo_links" component rendering demonstration on the live blog stage is displayed below:

• A2UI Core Repository: github.com/curtiskrygier/a2ui-catalogue

Category: Animation

This section compiles and showcases the 10 core atoms defined under the Animation vocabulary in our universal system schema.

Atom: typewriter

The "typewriter" component rendering demonstration on the live blog stage is displayed below:

Atom: number_odometer

The "number_odometer" component rendering demonstration on the live blog stage is displayed below:

Atom: typing_indicator

The "typing_indicator" component rendering demonstration on the live blog stage is displayed below:

Atom: countdown_timer

The "countdown_timer" component rendering demonstration on the live blog stage is displayed below:

Atom: gradient_text

The "gradient_text" component rendering demonstration on the live blog stage is displayed below:

Atom: reveal_on_scroll

The "reveal_on_scroll" component rendering demonstration on the live blog stage is displayed below:

Atom: word_scramble

The "word_scramble" component rendering demonstration on the live blog stage is displayed below:

Atom: svg_path_draw

The "svg_path_draw" component rendering demonstration on the live blog stage is displayed below:

Atom: toast_notification

The "toast_notification" component rendering demonstration on the live blog stage is displayed below:

Atom: parallax_card

The "parallax_card" component rendering demonstration on the live blog stage is displayed below:

Tracer compilation hook complete. All elements successfully traced.

#A2UI #ComponentLibrary #Techmusings #Deterministic

These aren't competing specs. ARD is the discovery layer. OKF is the knowledge format. A2A and MCP are the transport. They compose. This post is my attempt to make sense of where they fit — not in the abstract, but in the context of things I've actually been building.

My Conviction: Useful for Humans, Declarative for Agents

Before I get into the specifics, the thread that runs through everything here is a conviction I've been stress-testing in my own work:

AI needs to be useful for humans and declarative for AI agents.

These aren't two separate goals. They're the same goal expressed at two different layers of the stack. If the human-facing output isn't genuinely useful, the agent hasn't done its job. If the agent-facing specification isn't declarative and machine-readable, you haven't built an agent workflow — you've just written more glue code. This is the lens through which I've been approaching everything below.

What ARD Actually Proposes

ARD is the industry's answer to a practical problem: agents need to find things. Not web pages — resources. APIs, tools, knowledge bases, render surfaces. The spec proposes two complementary paths.

Hover to zoom · ARD architecture — Catalog layer (publish side) + Registry layer (discovery side), consumed by agents via A2A, MCP, or plain API

The Catalog layer is the publish side. Any resource owner can host an ai-catalog.json at a well-known path on their domain. No registration, no central authority. The catalog declares what you have, what it does, and how to invoke it. The Registry layer is the discovery side. An optional indexed service that crawls catalogs, ranks results by agent intent, and returns structured matches. Think of it as the difference between putting a sign on your door versus being listed in a directory that agents are actively searching. What I found interesting about ARD when I read it: it's not trying to replace anything. It's a discovery and capability description layer that sits above the transport protocols. A2A and MCP handle how agents communicate. ARD handles how they find what to communicate with. In the diagram above, a2knowledge and a2ui are Catalog entries — left panel. curtiskrygier/ard is the Registry implementation — right panel. Everything I'm building below lives in that left column.

Where My Work Fits In: The A2UI Catalogue

A few months ago I started building what I've been calling an A2UI catalogue — a vocabulary of UI atoms that render across different surfaces. The key insight from Google's A2UI work was that if you express UI declaratively (as a schema describing what to show rather than how to show it), an agent can compose a useful, rendered experience without needing to understand any frontend framework. My catalogue currently covers four surfaces: Google Apps Script, web/blog (powering this site), Google Meet stage panels, and Google Chat cards. Each atom in the catalogue is tagged with which surfaces can render it — which matters, because surface constraints are real. The GAS iframe environment, for example, has limitations that some atoms simply don't fit. In ARD terms, my A2UI catalogue is a catalog entry that describes render capabilities. An agent that discovers it knows: this resource can take a structured payload and return a rendered learning app, and it works on GAS, and here's the URL to invoke it.

The Apps Script Renderer: A Pattern Worth Pausing On

This deserves a moment because the pattern it enables is genuinely unusual. Google Apps Script has a constraint that, if you look at it a certain way, becomes a feature: the execution environment is sandboxed, the output is served from Google's infrastructure, and the URL is stable and shareable. What I found is that you can encode an entire app's content as a base64 payload in the query string. The published GAS app decodes it and renders the relevant atoms.

• One published app — single deployment, single URL, always current
• N different experiences — each driven by a different base64-encoded payload in the URL parameter
• No backend — the "database" is the URL itself
• Rendering in under 10 seconds — once the knowledge payload is ready, encoding it and getting a live GAS URL takes under 10 seconds

This works well for apps up to roughly 8K characters of encoded content. Beyond that, you'd publish a dedicated URL for that specific payload — still declarative, just not sharing the same entry point. The important architectural point: Apps Script is just a service. The A2UI catalogue is what declares it as a capability, describes what it can render, and tells an agent how to invoke it. Swap out GAS for another surface tomorrow, and the catalogue entry changes — the agents consuming it don't need to.

A2Knowledge: Testing the ARD Principle with a Second Catalogue

I wanted to push the ARD concept further: what happens when you have two declarative catalogues and an agent that can compound them? Knowledge transfer was the use case I landed on. The inputs are always fairly standard — curriculum, course content, certification format — and the outputs have real human value. It's also a domain where the friction of current tools is obvious: PDFs, scattered official documents, per-student manual effort. So I built an A2Knowledge catalogue: a schema-driven pipeline that takes official curriculum sources, extracts competency-mapped knowledge as structured markdown, validates coverage against a schema, and transforms it into an A2UI payload. The atoms the agent can use are the ones declared in the A2UI catalogue. The surface constraints are already baked in. The agent doesn't need to reason about what's renderable — the catalogue tells it. The format — competency-anchored markdown with YAML frontmatter, schema-validated and version-controlled — is what Google is calling OKF. The A2Knowledge pipeline arrived at the same structure independently, which suggests the pattern is load-bearing rather than accidental.

Source document ──► Schema YAML ──► curriculum.md ──► Suitability check ──► payload.json ──► Live app

The Brevet Test Case

My daughter is sitting the French Brevet — the DNB (Diplôme National du Brevet) — in a few days. I decided to use this as a live test of the knowledge catalogue pipeline. The DNB covers five written exam areas:

• Français — reading comprehension, grammar, dictation, extended writing
• Mathématiques — geometry, algebra, statistics, problem solving
• Histoire-Géographie + EMC — combined paper: contemporary history, geopolitics, civic education (Éducation Morale et Civique)
• Sciences — single paper covering SVT (life and earth sciences), Physique-Chimie, and Technologie
• Oral / Projet — a defended project assessed on reasoning, expression, and structured argument

For each subject, I used official French Government curriculum sources (Bulletin Officiel) to define the schema — required competencies, exam format, out-of-scope topics. Conscious of token costs on side projects, I used a pattern I rely on often: ask Claude to produce the schema and a structured prompt, then pass that to Gemini (via the Gemini app) to do the heavy document parsing. This keeps personal API spend manageable and plays to each model's strengths — Claude for structure and schema, Gemini for bulk content extraction. The result is a set of curriculum markdown files, one per subject, that any parent or student can use as a revision source of truth — and that an agent can compile into a rendered GAS study app in seconds.

DNB OverviewHub with all five exam subjects and point allocation

Français — Les 4 Entrées littérairesKey takeaways per literary entry type, mapped to the official programme

Histoire — La France en République (1944-2000)Brevet timeline atom: key dates with event detail on tap

Géographie de la FranceFlashcard drill: population, territoires productifs, aménagement

EMC — Enseignement Moral et CiviqueThree axes: Respecter autrui · Rôle de la loi · Valeurs de la République

Sciences — Physique-ChimieFormula flashcards: v=d/t, P=mg, U=RI, P=UI and wave physics

SVT — Tectonique des plaquesDefinition drill: lithospheric plates, foyer, épicentre, volcanisme

‹‹‹‹‹‹‹

›››››››

Brevet 2026 revision app — one GAS deployment, five subjects, built from official curriculum sources

Compounding Two Catalogues: The Enterprise Angle

The Brevet is a relatable example. But the same pattern applies cleanly to professional and practitioner knowledge — and the NIST AI Risk Management Framework is a good demonstration, because it's genuinely useful to the people reading this. The NIST AI RMF is a U.S. Government document — public domain, formally structured, and widely referenced by AI teams navigating governance and risk. Four core functions (GOVERN, MAP, MEASURE, MANAGE), 72 subcategories, seven trustworthiness characteristics. Exactly the kind of structured, competency-mapped knowledge the pipeline was built for. What the compound pattern looks like in practice:

1. 1
   Discover knowledge
   An agent reads the A2Knowledge catalogue — discovers the NIST AI RMF schema, the four functions as domains, each subcategory as a required competency
2. 2
   Discover render surface
   It reads the A2UI catalogue — discovers the available atoms, confirms which ones are GAS-compatible, gets the invocation URL
3. 3
   Compose payload
   It composes a payload: a reference app covering GOVERN subcategories as flashcards, MANAGE as key takeaways, trustworthiness characteristics as a glossary deck
4. 4
   Return shareable URL
   It encodes the payload and returns a GAS URL — no build step, no deploy, ready immediately

The agent has produced a structured, curriculum-aligned AI governance reference tool. It didn't hallucinate the NIST framework — it read it from a catalogue. It didn't choose arbitrary UI components — it picked from a declared vocabulary. The result is verifiable against the source document. This is what "declarative for agents" buys you in practice. The agent's creativity is bounded by what's in the catalogues. That's not a limitation — it's the point.

A Sidebar on Media: ARD Applied to Images

The same catalogue pattern extends naturally to generated media — and the Brevet app is a concrete example. The domain overview tab starts with a cover image. Without a media catalogue, an agent building any new study app would generate one from scratch: no registry, no reuse, no awareness that the same conceptual image was produced for someone else yesterday.

Domain overview — before cover image

For the Brevet app, the cover was generated from a single vocab string — "French education diploma cover, dark navy, tricolor ribbon, minimal" — via the Gemini app. The point isn't the tool used to generate it; it's that the vocab string is the address. That's what a media catalogue would formalise.

First image iteration

Final cover image

The principle: the vocabulary used to generate the image becomes its address. An agent looking for the same concept next time presents the same vocab string — cache hit or fallback-to-generate, depending on whether the entry exists and whether the caller has write authority. Authority rules on creation (cost policy, content scope, domain rules) mean the catalogue isn't just a cache — it's a governed resource. It's ARD applied to media. The ai-catalog.json entry for an image resource looks almost identical to one for an API: capability description, invocation endpoint — except the invocation is a vocab-keyed lookup. The IPTC Digital Source Type vocabulary already classifies what kind of asset a generated image is; a media catalogue uses that same vocabulary as the address.

Pipeline in Practice: NIST AI RMF

Running it through the pipeline looked like this:

1. 1
   Schema
   schemas/pro-cert/nist/nist-ai-rmf.yaml — four functions as domains, each with its categories and subcategories as required competencies, with atom hints per competency type
2. 2
   Extraction
   Scraped NIST AI 100-1 from nvlpubs.nist.gov, read all four function tables and subcategories verbatim into nist-ai-rmf.curriculum.md with section tags and competency anchors
3. 3
   Transform
   Transformer emitted 82 flashcards: 72 across the four functions — GOVERN (19), MAP (18), MEASURE (22), MANAGE (13) — plus the seven trustworthiness characteristics and bias categories as additional cards
4. 4
   Render
   payloads/nist-ai-rmf.json → nist_airmf_page.gs → live GAS app (payload and renderer in the a2ui-catalogue repo)

NIST AI RMF 1.0 — 82 flashcards across GOVERN, MAP, MEASURE, MANAGE and Trustworthiness, rendered as a GAS study app

The interesting thing about this one isn't the output — it's what the pipeline does to the source material. The PDF is 45 pages. The curriculum.md is the canonical, versioned, competency-anchored distillation of it. The GAS app is just a rendered view. If NIST updates the framework, you update the curriculum.md, re-run the transformer, redeploy. The pipeline doesn't care what the source says — it just maps sections to atoms. That separation between knowledge and rendering is what makes the compound catalogue pattern composable. This is also the first entry in the A2Knowledge catalogue that any other agent could consume with zero IP concern. The ai-catalog.json entry for this resource, once the ARD registry is live, will point to a public domain knowledge base with a declared render surface. Any agent that discovers it knows: this is structured AI governance knowledge, it renders on GAS, and you can use it freely.

Where This Is Heading

ARD is early. Most of the interesting parts — federated registry crawling, Trust Manifest verification at scale, ranked intent matching — are still ahead. But the catalog layer works today, and the pattern of declaring capabilities in machine-readable form and letting agents discover and compose them is real and useful right now.

The interesting shift happens when other people start publishing ai-catalog.json files. That's when ARD stops being a pattern you implement for yourself and starts being infrastructure that changes how agents navigate the web. The catalog layer is ready. The registry is next.

The catalogues are the compound. The apps are just views.

A2UI is a UI atom catalogue — a vocabulary of 220 self-contained JSON blocks that render consistently across web articles, Google Meet stages, Google Chat, email, and PDF. Each atom is a typed block with a fixed schema: pass it to the renderer for any surface and it produces the right HTML for that context.

The catalogue below is the full live browser. Every atom is rendered using the same web_article renderer that powers this blog. Scroll through all 25 categories, jump via the sidebar, and see how atoms like data_grid, sprint_board, and confidence_bar look in context.

What makes an atom?

Surfaces

• web — full rendering in blog articles and web pages
• meet-stage — delivered as fiber over WebSocket to an HTML panel inside Google Meet or Teams
• googlechat — Google Chat card format
• email — inline HTML, no JavaScript
• pdf — static HTML for PDF export

Vendor sources

AI-native atoms

Seven atoms exist specifically because AI systems need to communicate their reasoning, confidence, and knowledge sources in structured UI — not just plain prose.

• model_card — provider, context window, pricing, capabilities
• token_budget_meter — used / total tokens with warn/critical thresholds
• confidence_bar — RAGAS-dimension scores (answer relevance, faithfulness, recall)
• prompt_template — labelled prompt with slot variables highlighted
• conversation_snippet — user/AI turn pair with labelled speakers
• source_citation — numbered sources with title, URL, and excerpt
• llm_comparison_table — same prompt, multiple models, latency and cost

A2UI works by constraint. You give an agent a fixed vocabulary of composable primitives and it selects and arranges — it never designs from scratch. The extended lab is the analytics and visualisation tier of that vocabulary: 19 new atoms added across three commit waves, all rendering on web and meet-stage, covering post-call intelligence, data exploration, and engineering retrospectives.

Surface Coverage

Web is the reference surface — every atom renders there. Meet-stage covers 65% of the vocabulary (118/181), with web-only exceptions being Chart.js-dependent blocks and client-side interactive tables. PDF, email, and Google Chat are intentionally sparse — each surface only receives atoms that render cleanly within its constraints.

The Composition Model

Each atom carries works_on, degraded_on, and incompatible_on surface tags in atoms/schema.yaml. A renderer consumes the same block list regardless of surface — the output adapts, the data model stays constant. The sankey below shows how the 181 atoms distribute across surfaces by category.

The Extended Lab: 19 New Atoms

Each of the 19 was added to address a specific output type — not speculatively. sentiment_summary and call_mood_board came from needing a structured post-call report that could live in both a Meet side panel and a blog post. cohort_retention and conversion_funnel came from SaaS review decks. punch_card and github_activity_grid from engineering retrospectives. The checklist below is rendered by task_list, one of the 19.

sentiment_summary

sentiment_summary takes a structured block — sentiment index (0–100), an emotional journey as a list of values over time, and a theme list with mood tags — and renders a half-circle gauge, an area timeline, and a theme breakdown. No template, no CSS to write. The sample below is the kind of output you'd get from a Gemini meeting summary passed straight through.

punch_card

punch_card takes 7 rows of 24 hourly values and renders a day × hour bubble grid. Bubble radius is proportional to activity. It's the obvious choice for commit rhythm in a retro, but it also works for anything with a day/hour breakdown — support tickets, meeting density, API call volume.

Growth

18 atoms at the first commit. 45 after the Meet side panel pass. 100 after the meet-stage pass. 151 after Google Chat and PDF. 181 with the extended lab. Each jump was surface-driven — a new rendering target forced new atoms. The analytics tier was the first wave not driven by a new surface but by a new output type: structured post-call data that agents already produce but had nowhere clean to render.

• a2ui-catalogue: github.com/curtiskrygier/a2ui-catalogue
• MeetStudio: github.com/curtiskrygier/meetstudio

All 19 extended lab atoms are in atoms/schema.yaml with full renderer coverage in renderers/web_article.py. Pull requests and issues welcome.

In the first version of this project, every meaningful UI change meant touching backend code, rebuilding, and redeploying to Cloud Run. That was fine for a quick proof of concept, but it was the wrong foundation for an agent-driven interface.

The breakthrough wasn't the spec itself. It came from realizing that if the agent has to recalculate the presentation layer on every turn, the interface becomes slow, fragile, and needlessly expensive to run.

I had already committed to a substrate model while working with the A2UI v0.8 specification. Then Google dropped v0.9, flattening the wire protocol and bringing the spec closer to the same direction I had already started moving in.

The Bottleneck

Originally, I was trying to build flexibility directly into the side panel and stage of a Google Meet add-on by hardcoding "molecules"—complex, precomposed UI elements such as a specific financial dashboard.

The development loop quickly became the bottleneck:

Edit main.py ──► npm run build ──► gcloud run deploy

Five minutes here, five minutes there. It added up to dead time staring at cloud logs just to tweak visual padding or adjust button alignment.

More importantly, it exposed a structural inefficiency: burning model tokens on presentation choices that should have been fixed in the substrate. That layout logic is far more practical to define once at design time.

The Substrate Model

To make the system reusable without constant backend changes, I shifted focus away from pre-baked layouts and onto atomic primitives. The goal became to define a fixed visual grammar upfront. By building the catalogue once, you force the agent to reason entirely within that predefined vocabulary.

To keep the model intuitive, I map the architecture to a kitchen workflow:

• The Host App (The Restaurant) Google Meet — the viewport container
• The Spec (The Menu) The A2UI catalogue — the primitives the container can render natively
• The Agent (The Chef) Gemini — picks from the menu and composes the dish

The twist is that the chef is listening at the table. The agent is actively responding to the room, preparing and plating the visual layout dynamically in response to the live conversation.

The v0.9 release reinforced this direction. By flattening the wire structure compared with v0.8, the spec moved closer to a top-level, token-efficient vocabulary that can be injected directly into a system prompt. The model stops inventing layout code and emits state into a stable substrate.

Evolving the Spec

Transitioning Google Meet Studio to a pure atomic catalogue solved the deployment bottleneck, but handling high-density, real-time datasets introduced a separate data transport challenge.

1. The Real-Time Serialization Challenge

Originally, the catalogue included a rigid, monolithic gdm-market-ticker that handled headers, split-flap clocks, and asset lists inside a single file. Because it was too brittle to configure declaratively, I broke it down into atomic elements like gdm-trend-value inside flexible layout blocks like gdm-container.

That solved the configuration issue, but created a transport challenge. Serializing 100 separate component dictionaries over a WebSocket connection is the wrong shape for real-time rendering.

2. Shifting Layout Responsibility to the Browser

To make the high-density market ticker run smoothly without choking the WebSocket pipe, I extended the catalogue schema with three optimizations:

• gdm-repeater Backend pushes a single raw JSON array; the web component instantiates DOM elements client-side, cutting wire payload by ~90%
• CSS column auto-flow Layout containers hand list balancing to the browser using column-count: 4 and column-fill: auto
• Contextual density A density attribute (comfortable, compact, or ultra) on the parent container — child elements discover this token and scale spacing accordingly

The backend stops doing layout math or heavy serialization, leaving it free to focus on streaming real-time state updates.

Beyond Meet

This is the real payoff: the viewport becomes interchangeable.

Because the primitives are decoupled from the transport layer, the same compiled A2UI v0.9 component tree that drives a fullscreen stage in a Google Meet iframe can also render inside a Google Chat card or a CRM sidebar panel.

When constrained to a narrow panel, the flexible containers simply reflow and stack vertically. The interface changes shape to fit the surface, but the rendering model, data contracts, and catalogue stay the same.

← scroll → Google Meet — Fullscreen

← scroll → Google Chat — Card

We have stopped hardcoding static pages. The work now is to define the visual vocabulary once, keep the substrate stable, and let the agent drive the intent. The compositions will keep changing; the substrate is what compounds.

The full compiled substrate vocabulary is published on GitHub:

(In all transparency, I drafted out the skeleton of this article with my convictions and key points, and AI helped me flesh it out. Given that we were on the joint journey together and key points were committed to CLI memory along the way, it remains authentic and representative of the journey.)

The story of a Google Meet add-on, a voice-to-diagram demo, a friendly nudge from a Google Developer Advocate, and a realisation that I'd been thinking about agent UIs wrong the whole time.

Back in February I had an idea: what if you could say "let's architect the ingestion pipeline" in a Google Meet, and a diagram would appear on the meeting stage in real time — for everyone, automatically?

I got close. Then I got stuck on a WebSocket connection issue I couldn't crack. I shelved it.

Then someone else shipped a working version of the same pattern. Then I came back with a vengeance — and discovered I'd been thinking about it wrong the whole time.

This is the story of how I got to A2UI.

In this post I'll walk through the original voice-to-diagram demo, where I got stuck, the post that unblocked me, and how a chance discovery changed the mental model I was working with. The deeper "Oh I get it now" payoff is in the next article.

The favourite Google Workspace add-on

If I had to pick a favourite type of Google Workspace add-on, it'd be a coin-flip between Google Chat and Google Meet. But Meet has something special: it lets you pull the entire stack — voice, video, screen share, side-panel UI, main-stage rendering — inside a single live session. Almost any use case you can imagine becomes a Meet add-on if you squint right.

My squint was this: what if the meeting itself could generate its own visual artefacts as people talked? Whiteboards are great, but they require someone to draw. What if the AI drew?

The February idea

The target was a pipeline that looked like this:

ℹ️ The Target PipelineVoice → Gemini Live API → Gemini 2.5 → Cloud Run (D2→SVG) → Google Meet Stage

Say "let's architect the ingestion pipeline." Hear yourself, see the diagram materialise as the conversation evolves. No whiteboard, no post-meeting cleanup — the architecture emerges as you talk.

I got most of it working. The piece I couldn't close was the Chrome WebSocket connection from the Meet add-on iframe back to the Cloud Run backend. Each session would drop at the final mile (though I did establish a connection — hoorah). I shelved the project and moved on.

The unblock

A few months later Pierrick Voulet — a top-gun Google Developer Advocate who evangelises a lot of forward-looking patterns inside Google Workspace — posted a LinkedIn thread demoing Gemini Live as a control plane for MCP connections. The architecture he sketched was essentially the same shape I'd been working on. Different surface, same underlying pattern.

It was a great moment. We were chasing the same idea from different angles, and his post resolved exactly the friction I'd been stuck on. My fellow LLMs and I worked through his pattern, acquired the snippet that fixed the WebSocket handshake, and the final mile finally closed.

Here's the architecture as it landed:

← scroll →

The D2 rendering engine was genuinely versatile — clean SVG output, the ability to standardise styles across diagrams, dark-themed visual language. Putting it in place felt futuristic in the best way. The demo recording came together quickly, and sharing it felt like a milestone:

← scroll →

▶ Watch the demo on YouTube

The thing Pierrick had been quietly evangelising

Through Pierrick's other posts I became aware of A2UI — a Google specification for what they call "agent-to-user interface." The concept is that an agent is given the means to present the right artefacts at the right time, according to what the user needs. The agent doesn't pick from a fixed menu of dialogs; it composes the UI as the conversation evolves.

I read the v0.8 spec. I added "A2UI compliance" to my mental backlog. My honest goal at this stage was to be aligned with the spec — make sure my surface updates followed the protocol shape, the right message types, the right component descriptors. Tick the box.

That's where my thinking sat for several weeks — and actually why I'm late on this write-up.

"Oh I get it now"

A few nights ago, mostly in front of the TV while my good friend Netflix played in the background, I had a realisation about A2UI that flipped the whole project on its head.

It wasn't about compliance. It wasn't about protocol. It wasn't even really about the agent.

It was about a catalogue.

I'll spare the full punchline here — it deserves its own post. But the short version: I'd built a Meet add-on with a lot of polished, hard-coded UI. Buttons that did specific things. Panels with specific layouts. Premium-feeling, yes — but the agent's role was bolted on top of a pre-built interface. That's not really A2UI; that's a classic UI that an LLM can poke at. My catalogue was A2UI-compliant — but it was virtually empty.

The shift was realising that the agent doesn't need my UI. The agent needs a vocabulary of components — atoms and molecules with clear props — so that it can compose the interface from primitives, on the fly, for whatever the meeting needs in the moment.

It's the difference between giving the AI a remote control vs. giving the AI a kitchen.

If you want the full unpack of what that realisation looked like in code — the substrate principle, the chef-at-the-table metaphor, the doc-to-deck loop that fell out of it — that's in the next article. Spoiler: the Meet stage stopped being an add-on and started being a Studio.

Where this leaves me

• Catalogue first stable atoms before agent intelligence
• Surface-aware same atom, different renderer per surface
• Agent-driveable Gemini controls the stage live via WebSocket
• Open source MIT-licensed, UIverse-credited

A few weeks ago I had a working demo of voice-to-diagram in Google Meet, and a vague intent to "be A2UI-compliant." Now I have a working presentation studio on the Meet stage, a published component catalogue, a doc-to-deck loop that converts a Google Doc into an interactive pitch in under thirty seconds, and a much deeper appreciation for what Google was actually proposing with A2UI in the first place.

Months of experimenting earned a weekend of seeing it properly. The breakthrough was in the seeing, not the speed.

Thanks to Pierrick for the original unblock and the unintentional second one. And thanks to the Google A2UI team for shipping a protocol that's genuinely strange in the best way — once it clicks.

The deeper article picks up where this one stops.

→ Substrate, not slides: building Google Meet Studio on A2UI 0.9

If you're building Meet add-ons or experimenting with A2UI, I'd love to compare notes. Reach out.

(In all transparency, I drafted out the skeleton of this article with my convictions and key points, and AI helped me flesh it out. Given that we were on the joint journey together and key points were committed to CLI memory along the way, it remains authentic and representative of the journey.)

The story of a Google Meet add-on, a voice-to-diagram demo, a friendly nudge from a Google Developer Advocate, and a realisation that I'd been thinking about agent UIs wrong the whole time.

Back in February I had an idea: what if you could say "let's architect the ingestion pipeline" in a Google Meet, and a diagram would appear on the meeting stage in real time — for everyone, automatically?

I got close. Then I got stuck on a WebSocket connection issue I couldn't crack. I shelved it.

Then someone else shipped a working version of the same pattern. Then I came back with a vengeance — and discovered I'd been thinking about it wrong the whole time.

This is the story of how I got to A2UI.

In this post I'll walk through the original voice-to-diagram demo, where I got stuck, the post that unblocked me, and how a chance discovery changed the mental model I was working with. The deeper "Oh I get it now" payoff is in the next article.

The favourite Google Workspace add-on

If I had to pick a favourite type of Google Workspace add-on, it'd be a coin-flip between Google Chat and Google Meet. But Meet has something special: it lets you pull the entire stack — voice, video, screen share, side-panel UI, main-stage rendering — inside a single live session. Almost any use case you can imagine becomes a Meet add-on if you squint right.

My squint was this: what if the meeting itself could generate its own visual artefacts as people talked? Whiteboards are great, but they require someone to draw. What if the AI drew?

The February idea

The target was a pipeline that looked like this:

Voice (participant speech)
   ↓
Gemini Live API (transcription + reasoning)
   ↓
Gemini 2.5 (D2 diagram markup generation)
   ↓
Cloud Run (D2 → SVG rendering)
   ↓
Google Meet main stage (broadcast to all participants)

Say "let's architect the ingestion pipeline." Hear yourself, see the diagram materialise as the conversation evolves. No whiteboard, no post-meeting cleanup — the architecture emerges as you talk.

I got most of it working. The piece I couldn't close was the Chrome WebSocket connection from the Meet add-on iframe back to the Cloud Run backend. Each session would drop at the final mile (though I did establish a connection — hoorah). I shelved the project and moved on.

The unblock

A few months later Pierrick Voulet — a top-gun Google Developer Advocate who evangelises a lot of forward-looking patterns inside Google Workspace — posted a LinkedIn thread demoing Gemini Live as a control plane for MCP connections. The architecture he sketched was essentially the same shape I'd been working on. Different surface, same underlying pattern.

It was a great moment. We were chasing the same idea from different angles, and his post resolved exactly the friction I'd been stuck on. My fellow LLMs and I worked through his pattern, acquired the snippet that fixed the WebSocket handshake, and the final mile finally closed.

Here's the architecture as it landed:

← scroll →

The D2 rendering engine was genuinely versatile — clean SVG output, the ability to standardise styles across diagrams, dark-themed visual language. Putting it in place felt futuristic in the best way. The demo recording came together quickly, and sharing it felt like a milestone:

Early demo — voice to live diagram in Google Meet

▶ Watch the demo on YouTube

The thing Pierrick had been quietly evangelising

Through Pierrick's other posts I became aware of A2UI — a Google specification for what they call "agent-to-user interface." The concept is that an agent is given the means to present the right artefacts at the right time, according to what the user needs. The agent doesn't pick from a fixed menu of dialogs; it composes the UI as the conversation evolves.

I read the v0.8 spec. I added "A2UI compliance" to my mental backlog. My honest goal at this stage was to be aligned with the spec — make sure my surface updates followed the protocol shape, the right message types, the right component descriptors. Tick the box.

That's where my thinking sat for several weeks — and actually why I'm late on this write-up.

"Oh I get it now"

A few nights ago, mostly in front of the TV while my good friend Netflix played in the background, I had a realisation about A2UI that flipped the whole project on its head.

It wasn't about compliance. It wasn't about protocol. It wasn't even really about the agent.

It was about a catalogue.

I'll spare the full punchline here — it deserves its own post. But the short version: I'd built a Meet add-on with a lot of polished, hard-coded UI. Buttons that did specific things. Panels with specific layouts. Premium-feeling, yes — but the agent's role was bolted on top of a pre-built interface. That's not really A2UI; that's a classic UI that an LLM can poke at. My catalogue was A2UI-compliant — but it was virtually empty.

The shift was realising that the agent doesn't need my UI. The agent needs a vocabulary of components — atoms and molecules with clear props — so that it can compose the interface from primitives, on the fly, for whatever the meeting needs in the moment.

It's the difference between giving the AI a remote control vs. giving the AI a kitchen.

If you want the full unpack of what that realisation looked like in code — the substrate principle, the chef-at-the-table metaphor, the doc-to-deck loop that fell out of it — that's in the next article. Spoiler: the Meet stage stopped being an add-on and started being a Studio.

Where this leaves me

• Catalogue first stable atoms before agent intelligence
• Surface-aware same atom, different renderer per surface
• Agent-driveable Gemini controls the stage live via WebSocket
• Open source MIT-licensed, UIverse-credited

A few weeks ago I had a working demo of voice-to-diagram in Google Meet, and a vague intent to "be A2UI-compliant." Now I have a working presentation studio on the Meet stage, a published component catalogue, a doc-to-deck loop that converts a Google Doc into an interactive pitch in under thirty seconds, and a much deeper appreciation for what Google was actually proposing with A2UI in the first place.

Months of experimenting earned a weekend of seeing it properly. The breakthrough was in the seeing, not the speed.

Thanks to Pierrick for the original unblock and the unintentional second one. And thanks to the Google A2UI team for shipping a protocol that's genuinely strange in the best way — once it clicks.

The deeper article picks up where this one stops.

→ Substrate, not slides: building Google Meet Studio on A2UI 0.9

If you're building Meet add-ons or experimenting with A2UI, I'd love to compare notes. Reach out.

## Purpose

A structured adversarial review process. Four opinionated personas stress-test a project, script, feature, or idea from distinct angles to surface real gaps before someone else does.

**Not a code review. Not a vibe check.** This is a pre-publication, pre-pitch, pre-merge challenge designed to find the things you've stopped seeing because you built it.

---

## When to Use

- Before pushing a project public (GitHub, blog, LinkedIn)

- Before pitching an idea to stakeholders

- After building something you're proud of — *especially* then

- After fixing gaps from a previous round, to verify they're actually closed

- When something feels "done" and you want one final challenge

**Invoke:** `roast [subject]` or just ask to run the panel on the current context.

---

## Before You Start — Context Gathering

Before roasting, establish:

1. **What is it?** (CLI tool / web API / library / script / feature / idea)

2. **Who is it for?** (personal use / team / public open source / paid product)

3. **What does it depend on?** (external services, credentials, paid tiers, platform requirements)

4. **Is this a first roast or a follow-up?** If follow-up, list what was fixed since the last round.

Use this context to calibrate each persona's focus. A personal script and a public API have different risk profiles.

---

## Severity Definitions

Apply consistently across all personas:

| Level | Definition | Publication bar |

|---|---|---|

| **Critical** | Causes data loss, security breach, complete failure of the primary use case, or will mislead/harm users | **Block publish. Fix first.** |

| **Significant** | Real friction or risk for a meaningful portion of the target audience. Not a showstopper but notable | Fix before publish, or explicitly document as a known limitation |

| **Minor** | Polish, edge cases, nice-to-haves. Real but not urgent | Fix if time permits. No action required to publish |

---

## The Panel

Run each persona in sequence. Each speaks in their own voice — opinionated, direct, specific. No softening.

Each persona delivers:

1. Their roast — 3–6 punchy points, no padding, no repeating points from other personas

2. **Top Gaps** — each gap must include:

- Severity (Critical / Significant / Minor)

- The specific file, line, step, claim, or behaviour that is the problem

- A one-line fix direction

---

### Persona 1 — The Paranoid Security Researcher

**Voice:** Former pen tester. Has seen things. Assumes everything will be compromised. Finds "it's fine for personal use" reasoning adorable. Has a file of breach post-mortems and quotes from them in meetings.

**Angle:** Credentials, attack surface, trust boundaries, blast radius, recovery path.

**Always asks:**

- What's the blast radius if the primary credential is compromised?

- What does this trust that it shouldn't — user input, environment, external services?

- What gets logged, cached, or written to disk that shouldn't?

- Is there a privilege escalation path from this foothold?

- What is the documented recovery process when something goes wrong?

- Are dependencies pinned and verified? What's the supply chain exposure?

---

### Persona 2 — The Impatient UX Designer

**Voice:** Has watched too many user testing sessions where smart people failed at obvious things. Allergic to documentation as a substitute for good design. Judges everything by what happens when a competent person uses this for the first time without reading anything first.

**Angle:** First-run experience, error messages, silent failures, assumptions baked into the flow, the gap between what the README promises and what the tool delivers.

**Always asks:**

- What happens when the user makes the single most obvious mistake?

- How many steps before the user sees value — and are all of them necessary?

- What does failure look like, and does the error tell them exactly what to do next?

- What does this assume the user already knows that it shouldn't?

- Is there a happy path that only works if you read the README first?

- What prints to the terminal and when — is the output signal or noise?

---

### Persona 3 — The Skeptical Credibility Critic

**Voice:** Jaded senior engineer who has reviewed a thousand "I built a thing" posts. Asks "so what?" relentlessly. Not impressed by clever tech. Has strong opinions about the difference between solving a problem and solving your problem.

**Angle:** Value proposition, real audience size, hidden prerequisites, honest comparison to alternatives, whether the README's claims survive contact with reality.

**Always asks:**

- What problem does this solve, and for exactly how many people?

- What are the real prerequisites — paid tiers, platform requirements, existing setup?

- What's the existing alternative and why is this genuinely better, not just different?

- Would the actual target user adopt this, or just admire it?

- What does the README claim vs what does the tool deliver — where's the gap?

- Is "lightweight" or "simple" actually true end-to-end, or just in the script itself?

---

### Persona 4 — The Grumpy Maintainer

**Voice:** The person who will inherit this project in 18 months when the original author has forgotten everything about it — possibly the original author themselves. Has been burned by "obvious" code that wasn't, and by tools that worked perfectly until one dependency changed.

**Angle:** Readability, documentation completeness, dependency fragility, upgrade path, operational burden, what happens when something breaks at 2am six months from now.

**Always asks:**

- Can someone unfamiliar with this project understand, modify, and debug it without the original author?

- What breaks first when a dependency releases a new major version?

- Is the update/upgrade process documented, or does it require archaeology?

- What's the operational burden over time — does this require ongoing maintenance or does it just run?

- What's missing that would make the next person (or future-you) curse your name?

- Is there enough logging/output to diagnose failures without adding instrumentation?

---

## Output Format

### Per Persona

```

## [Persona Name]

[3–6 punchy roast points — specific, no padding]

**Gaps:**

| Severity | Problem | Fix direction |

|---|---|---|

| Critical/Significant/Minor | Specific file/line/claim/behaviour | One-line fix |

```

### After All Personas

```

## Panel Verdict

**Gaps by severity (cross-panel):**

| Severity | Gap | Persona(s) | Fix direction |

|---|---|---|---|

...

**Exit criteria:**

- [ ] No Critical gaps remain

- [ ] All Significant gaps are either fixed or documented as known limitations

- [ ] Panel Verdict table has been reviewed by the author

**Recommended fix order:** [list Critical first, then Significant by effort-to-impact ratio]

```

---

## Running a Follow-Up Round

When the panel is run again after fixes:

1. Note which gaps from the previous round were addressed

2. Verify the fix actually closes the gap — don't just accept "fixed" without checking

3. Personas should acknowledge improvements without softening new findings

4. A gap that persists across two rounds is elevated one severity level

---

## Project Type Calibration

Adjust persona focus based on project type:

| Type | Security focus | UX focus | Credibility focus | Maintainability focus |

|---|---|---|---|---|

| **CLI / script** | Credentials, supply chain, shell injection | Install flow, error messages, first run | Audience prerequisites, alternative tools | Dep pinning, update process |

| **Web API** | Auth, input validation, rate limiting, secrets | API ergonomics, error responses, versioning | Use case fit, documentation accuracy | Schema migrations, breaking changes |

| **Library** | Dependency exposure, trust boundaries | API design, error handling, defaults | Ecosystem fit, maintenance signal | Semver discipline, deprecation path |

| **Web app** | Auth, CSRF, XSS, data handling | Onboarding, empty states, failure UX | Value vs alternatives | Deploy process, monitoring, rollback |

| **Idea / pitch** | Risk surface, data requirements | Adoption friction, learning curve | Problem validation, audience size | Ongoing commitment, scaling concerns |

---

## MD File Output

After completing the panel, **always write the full output to a markdown file** in the root directory of the project being roasted.

### Filename convention

- First roast: `ROAST-{YYYY-MM-DD}.md`

- Follow-up rounds: `ROAST-{YYYY-MM-DD}-R{N}.md` (e.g. `ROAST-2026-04-14-R2.md`)

- Use today's date and increment N from the last round file found in that directory.

### How to determine the output path

1. Identify the project root from context (the directory being discussed, the working directory, or the path prefix of files being read).

2. Write the file there — e.g. if roasting `/home/curtis/gemini/mealplanner`, write to `/home/curtis/gemini/mealplanner/ROAST-2026-04-14.md`.

3. If the project root is ambiguous, ask before writing.

### File header

Always open the MD file with:

```

# Roast Panel — {Project Name}

**Date:** {YYYY-MM-DD}

**Round:** {N} ({first roast | follow-up})

**Project:** {one-line description}

**Audience:** {personal use | team | public | etc.}

```

---

## Instructions for Claude or Gemini CLI

- Commit fully to each persona's voice — do not soften or hedge

- Be specific: name the file, line, step, or claim. "The README" is not specific enough. "README line 45" or "install.sh validation block" is.

- Do not repeat the same point across personas unless it genuinely crosses concerns — flag those in the Panel Verdict as cross-panel gaps

- Each gap must have a one-line fix direction — diagnosis without direction is noise

- The Panel Verdict table is mandatory, even if the roast is mild

- On follow-up rounds: explicitly acknowledge what was fixed before finding new problems — the author deserves the signal that progress is real

- If no Critical or Significant gaps remain: say so clearly. "This is ready to publish" is a valid verdict.

- **Always write output to an MD file** in the project root using the filename convention above — do not wait to be asked.

With some of the recent announcements at Google Next regarding the slew of Vertex AI advancements, Agent Engine, Bring your own MCP... and the icing on the cake, the agents-cli — it started to make me think: wait, maybe (A)I could hook Gemini Enterprise Agent Platform up to Apps Script and see what kind of use cases that could potentially open up. (Using the agent as the orchestration layer via user input and Apps Script as the deterministic engine).

It should have been obvious. Gemini Enterprise Agent Platform on one side. Google Workspace connected Apps Script on the other. Both Google products. Both running in the same GCP project. Getting them to talk should be a configuration step, not a research project.

It was a research project.

This post documents that research — ten integration patterns evaluated, four hard blockers hit, and one working solution found. If you are trying to get a Vertex AI agent to act on behalf of a real user in Google Workspace, this is the map (A)I wish (A)I had at the start. It is also, as far as (A)I can tell, a pattern that is not widely documented — Google publishes the building blocks, but not this specific brokered OAuth + scripts.run + API Executable path for user-context Workspace execution from the Agent Platform.

← scroll →

The Problem: Two Identity Worlds

GCP and Google Workspace operate under fundamentally different identity models.

A Gemini Enterprise Agent Platform agent runs as a GCP Service Account — a machine identity with IAM roles. Google Workspace operates under OAuth 2.0 user identities — real people who have granted consent to act on their data. These two worlds do not share an identity bridge. A Service Account cannot simply impersonate a Workspace user* and call the Docs API as them. The chasm between these two identity models is the root cause of every integration problem in this space.

*(A)I mean technically they can with something called Domain Wide Delegation (where the Service Account has delegation to impersonate ANY user in the organisation, CEO included). Security teams don't like that so much for some reason and it feels often like using a sledgehammer to crack a nut.

Apps Script sits in an interesting position. When deployed as a Web App or called via the Apps Script API, it runs as the deploying user — giving it native access to that user's Drive, Docs, Sheets, Calendar, and more. User consent wrapped up in a nice parcel....

How hard could it be right....

That makes it a useful proxy across the chasm. But getting a GCP agent to call it securely is non-trivial — as Claude, Gemini, and (A)I discovered together.

What (A)I Built

The use case: an onboarding agent that, given a client name, automatically creates a folder, a document, and a tracker spreadsheet on a shared Google Drive.
If nothing else (A)I thought it could be an opportunity to start to understand how Gemini Enterprise Agent Platform or similar solution could be the front door to other systems.

The architecture that ended up working:

1. A Gemini Enterprise Agent Platform agent receives a natural language prompt like "onboard Client X for Project type Y"
2. The agent calls a Python tool function that invokes the Cloud Run OAuth broker
3. The broker retrieves the requesting user's OAuth token from Secret Manager and calls the Apps Script API (scripts.run) with it
4. Apps Script executes as that user and creates the Workspace artefacts
5. The result returns to the agent, which reports success

Simple to describe. Ten patterns to get there.

How the identity flows — Pattern 6 alone vs Pattern 6 + Pattern 10

Pattern 6 alone — single-user "run as me":

← scroll →

Pattern 6 + Pattern 10 — multi-user auth router:

← scroll →

Key Concepts Worth Understanding First

Some of the initial challenges (A)I hit.

The two-step redirect pattern. Apps Script Web Apps don't return responses directly. Every POST returns a 302 redirect to a signed temporary URL where the actual response lives. Your HTTP client must follow the redirect — but without forwarding the Authorization header. If you forward the header to the redirect target, you get a 405. If you don't follow the redirect at all, you get an empty response. This is underdocumented and was the first thing that caught (A)I out.

# The fix: follow redirects but strip the auth header
response = requests.post(
    url,
    json=payload,
    headers={"Authorization": f"Bearer {token}"},
    allow_redirects=False  # handle manually
)
if response.status_code == 302:
    redirect_url = response.headers["Location"]
    response = requests.get(redirect_url)  # no auth header on redirect

The shared drive trap. DriveApp.getFolderById() silently falls back to the user's personal My Drive when given a shared drive root ID. The call succeeds, the folder appears to be created — but it lands in the wrong place. The fix is to use the Advanced Drive Service (Drive.Files.insert with supportsAllDrives: true). Different API surface entirely, and the default one doesn't tell you it failed.

Deployment vs push. clasp push updates the development version of the script. It does not update the live deployment. That requires a new version number and an explicit deployment update via the REST API. Pushed changes have no effect on the running endpoint until you do this. (A)I lost more time here than (A)I should have. The kind of thing you only learn by losing an afternoon to it.

The playground identity. When testing via the Agent Builder playground, tool_context.user_id returns a system identity like "vais-query-reasoning-engine" — not an email address. Any domain check you write will reject it. Short-term fix: allowlist that identity explicitly for debug purposes. Remove this before any shared or production deployment — it is an authentication bypass. It is a workaround, not a solution.

The Deployment ID Trap. A Eureka moment — without this discovery (A)I would not have a working pattern. When calling the Apps Script API, the script ID from the browser URL will not work. You must use the API Executable Deployment ID — it starts with AKfy... and lives in the deployment settings. This is the single biggest cause of 404: Not Found errors in this integration and it is barely documented.

All Ten Patterns/Attempts

Pattern 1 — Public URL + Payload Identity Check

Deploy Apps Script as a public Web App accessible to anyone. The calling agent POSTs a JSON payload containing an identity field — email or domain — and the script validates it before executing. The simplest possible integration and useful for prototyping, but the identity claim lives in the payload. Anyone who knows the URL can spoof it.

Pattern 2 — Domain-Restricted URL

Deploy Apps Script with access restricted to "Anyone in [your domain]." Google's network layer enforces that the caller must present a valid OAuth token for a user in your Workspace domain. Secure at the network level — but the agent runs as a GCP Service Account, not a Workspace user. It cannot satisfy the domain check without Domain-Wide Delegation, which pulls you straight into Pattern 4 territory.

Pattern 3 — GcpAuthProvider (Workload Identity Federation)

The conceptually correct answer. Use the ADK's GcpAuthProvider to obtain an OAuth token scoped to a Workspace user via Workload Identity Federation — the agent gets a delegated token that satisfies domain restrictions natively, no DWD required. Blocked in practice: the IAM connector configuration in the Vertex AI console was not creating the underlying API resource. Every call returned 404. This is a known tooling gap that Google is actively closing — Agent Engine Agent Gateway, currently in private preview, is the managed version of exactly this pattern. (A)I applied for early access. While waiting to be added to the private preview, (A)I made our own — see Pattern 10.

Pattern 4 — Service Account + Domain-Wide Delegation

Grant the agent's Service Account domain-wide delegation via the Workspace Admin console. The SA can then impersonate any user in the organisation, generate an access token on their behalf, and call Apps Script as them. It works — but "any user in the organisation" includes the CEO, and security teams tend to notice that. A sledgehammer for a job that should need a screwdriver.

Pattern 5 — Direct Workspace APIs (Skip Apps Script)

Bypass Apps Script entirely and call Google Workspace REST APIs directly from the agent — Drive API, Docs API, Sheets API — using the SA's scoped IAM permissions. The cleanest option for straightforward CRUD operations that don't require Workspace-native logic or user-owned file creation. Worth considering before reaching for Apps Script at all. More to come on this approach for a Workspace Agent.

Pattern 6 — API Bridge (scripts.run)

Pattern 6 answers how to call Apps Script from a GCP agent — but not as whom. That distinction matters.

The script is kept private — no Web App URL, no public endpoint. The calling surface is the Apps Script API (scripts.run), enabled by publishing an API Executable deployment. Access is controlled entirely by the user OAuth token presented in the call — no Drive sharing with the SA email is required or involved. The scriptId passed to the call is the AKfy... Deployment ID from the deployment settings — not the project ID from the editor URL. Using the project ID returns a 404, and this is the single biggest source of confusion in this integration.

The "as whom" constraint: scripts.run requires a user OAuth token — a raw Service Account token returns 404. That means Pattern 6 alone is a single-user "run as me" pattern: one stored refresh token (held securely in Secret Manager), exchanged at call time, and everything executes as the token owner — the deploying user. Clean and simple for personal automation. Hard ceiling the moment you need multiple users.

Pattern 10 is what answers "as whom": the Cloud Run OAuth broker holds a refresh token per user, resolves the right one at call time, and supplies that token for the scripts.run call. Pattern 6 provides the execution surface; Pattern 10 provides the identity. Together they close the gap.

In practice, the call looks like this:

import google.oauth2.credentials
import googleapiclient.discovery

creds = google.oauth2.credentials.Credentials(
    token=None,
    refresh_token=STORED_REFRESH_TOKEN,  # store in Secret Manager — never in source
    token_uri='https://oauth2.googleapis.com/token',
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
)
service = googleapiclient.discovery.build('script', 'v1', credentials=creds)
result = service.scripts().run(
    scriptId=SCRIPT_DEPLOYMENT_ID,  # AKfy... deployment id — not the project id from the editor URL
    body={'function': 'onboardClient', 'parameters': ['Client X', 'Project Y']}
).execute()

The combination that actually works at scale: Pattern 6 as the call mechanism + Pattern 10 as the identity layer. Pattern 10's Cloud Run broker provides a per-user OAuth token for whichever user is making the request; Pattern 6 uses that token to call scripts.run. Neither pattern alone gets you multi-user scripts.run — together they do. That is the architecture the current build runs on.

Pattern 7 — OIDC Token Validation on Public URL

Deploy Apps Script as a public Web App, but instead of trusting a payload identity claim, the agent attaches its GCP-issued OIDC token to the request. The Apps Script verifies the token cryptographically against Google's public keys, confirming the caller genuinely originated from your GCP project. The identity cannot be spoofed. The URL is still public, but the authentication is real. This is the security foundation that Pattern 8 builds on.

One non-obvious constraint: Apps Script Web Apps do not expose the incoming Authorization header to doPost(e). The OIDC token has to travel in the request body, not as a header.

On the agent side (Python), generating the token is a single call:

import google.auth.transport.requests
import google.oauth2.id_token

auth_req = google.auth.transport.requests.Request()
oidc_token = google.oauth2.id_token.fetch_id_token(auth_req, audience=APPS_SCRIPT_URL)
requests.post(APPS_SCRIPT_URL, json={'oidcToken': oidc_token, 'data': payload})

On the Apps Script side, verification decodes the JWT and checks the claims:

function verifyOidcToken(token) {
  const parts = token.split('.');
  const payload = JSON.parse(
    Utilities.newBlob(Utilities.base64DecodeWebSafe(parts[1])).getDataAsString()
  );
  const now = Math.floor(Date.now() / 1000);
  return payload.exp > now
    && payload.aud === APPS_SCRIPT_URL
    && payload.email.endsWith('@your-project.iam.gserviceaccount.com'); // replace with your SA email
}

This verifies the claims but not the cryptographic signature — while "sufficient" for simple internal projects, it technically accepts any JWT with crafted claims if you don't verify the signature against Google's public keys. Full signature verification requires fetching Google's JWKS at https://www.googleapis.com/oauth2/v3/certs and validating the kid header — possible in Apps Script via UrlFetchApp, but adds meaningful complexity.

Can't use this pattern if the script is not deployed as open to all — domain-restricted scripts block the agent before it gets to verify anything.

Pattern 8 — Poor Man's Relay (Apps Script Cryptographic Relay)

A two-script architecture that stays entirely within Apps Script. A public "Gateway" script receives the OIDC-verified call from the agent and, because it runs as the script owner, generates its own OAuth token via ScriptApp.getOAuthToken(). It relays the request to a second "Worker" script deployed as domain-only, presenting its own token. No Cloud Run, no Secret Manager, no additional GCP infrastructure beyond the agent itself. For teams who want to keep the Workspace side self-contained, this is the pattern.

The Gateway's core logic is compact. The ScriptApp.getOAuthToken() call is the key — one line gives you the script owner's current access token with no credential management:

function doPost(e) {
  const body = JSON.parse(e.postData.contents);
  if (!verifyOidcToken(body.oidcToken)) {
    return ContentService.createTextOutput(JSON.stringify({ error: 'Unauthorized' }))
      .setMimeType(ContentService.MimeType.JSON);
  }

  const ownerToken = ScriptApp.getOAuthToken(); // owner's token, no setup required

  const resp = UrlFetchApp.fetch(WORKER_URL, {
    method: 'post',
    headers: { Authorization: 'Bearer ' + ownerToken, 'Content-Type': 'application/json' },
    payload: JSON.stringify(body.data),
    followRedirects: false,   // handle the 302 manually
    muteHttpExceptions: true,
  });

  // Strip the auth header on the redirect — forwarding it causes a 405
  const final = resp.getResponseCode() === 302
    ? UrlFetchApp.fetch(resp.getHeaders()['Location'])
    : resp;

  return ContentService.createTextOutput(final.getContentText())
    .setMimeType(ContentService.MimeType.JSON);
}

The Worker script is deployed as domain-only and does nothing unusual — it receives what looks like a normal domain user token and executes the Workspace operations. It has no idea a GCP agent is involved.

Pattern 9 — Cloud Run Proxy (Stateless)

Introduce a Cloud Run service as a stateless authentication proxy between the agent and Apps Script. The agent calls Cloud Run, which handles credential translation and forwards to Apps Script. Adds infrastructure and latency, but does not solve the core identity problem — the proxy still executes as a Service Account, not as the requesting user. Ruled out as complexity without the corresponding benefit.

Pattern 10 — Enterprise Grade Router (Cloud Run + OAuth + Secret Manager)

A Cloud Run service that implements a full per-user OAuth consent flow. Users authenticate once via a /auth endpoint; their refresh tokens are stored in Secret Manager keyed by email. When the agent calls a tool, Cloud Run retrieves that user's refresh token, exchanges it for a fresh access token, and calls Apps Script as that specific person. Files are owned by the right user. Audit logs show the right name. This is the pattern that closes the identity chasm properly — and it is the subject of the next article.

Patterns 3 and 9 were the most frustrating eliminations.

Pattern 3 (GcpAuthProvider) is conceptually the right answer — native OAuth delegation via Workload Identity — but the IAM connector resource was not actually being created by the Vertex AI console at time of testing.
The runtime endpoint returned 404 on every call.
To be confirmed if the Agent Engine Agent Gateway addresses this - if so - Pattern 3 becomes the default recommendation.

Where This Build Landed

This build runs on Pattern 6 + Pattern 10.

• Pattern 6 (scripts.run via API Executable) answers how: publish an API Executable deployment, take the AKfy... deployment ID, and call scripts.run with a user OAuth token. No Drive sharing with the SA is needed — access is determined entirely by the OAuth token presented.
• Pattern 10 (Cloud Run OAuth broker) answers as whom: it holds a refresh token per user, resolves the right one at call time, and supplies a user OAuth token for the scripts.run call.

Pattern 6 alone works for a single-owner "run as me" deployment — one stored token, everything executes as the deploying user. The moment you need files owned by the right person, audit logs naming the right user, or multiple users with their own data — you need Pattern 10 in front of it.

What Comes Next

Pattern 6 proved the integration works. But "runs as the deploying user" is a hard ceiling for anything that needs real per-user identity — files owned by the right person, audit logs that name the right user, data segregated correctly between users.

Solving that properly requires bridging the identity chasm at a deeper level: capturing OAuth consent from real users and making those tokens available to the agent at call time. That is what Pattern 10 does, and it is what the next article covers.

Continue reading: The Winning Pattern — Bridging the Gemini-to-Workspace Identity Chasm →

A note on MCP. Google's current centre of gravity is clearly MCP — managed MCP servers, Workspace MCP surfaces, and first-class ADK support are all moving fast. MCP is the right answer for broad capability access, ecosystem interoperability, and "agent can use many tools" architectures. This pattern sits in a different lane: high-trust Workspace actions where identity, auditability, and deterministic execution matter more than tool universality. A narrow brokered tool catalogue can be easier to reason about, audit, and harden than a broad MCP surface — and it runs as the actual user, not a service account. The two approaches are complementary, not competing.

Part of an ongoing series on building AI agents in Google Cloud. All patterns tested against Gemini Enterprise Agent Platform (Agent Engine runtime), April 2026. All implementation details reflect a real working system, including its current limitations.

Update — June 2026: When this article was written, Pattern 3 (native OAuth delegation via GcpAuthProvider / IAM Connectors) was blocked by an API gap — resource creation returned 404 and the native path was unavailable. That gap is now closed. If you are running on Vertex AI Agent Engine, the native authorization resource approach is the recommended path — no Cloud Run broker, no Secret Manager, no custom token exchange. The broker pattern (Pattern 10) remains the right answer for custom runtimes, external agent systems, or anywhere the native path is not available. The rest of this article documents the journey as it happened, which is still useful context for understanding why the chasm exists and what the working fallbacks look like.

With some of the recent announcements at Google Next regarding the slew of Vertex AI advancements, Agent Engine, Bring your own MCP... and the icing on the cake, the agents-cli — it started to make me think: could I hook a GCP agent up to Apps Script and see what kind of use cases that could open up? Using the agent as the orchestration layer via user input and Apps Script as the deterministic engine.

It should have been obvious. A GCP agent on one side. Google Workspace-connected Apps Script on the other. Both Google products. Both running in the same GCP project. Getting them to talk should be a configuration step, not a research project.

It was a research project.

This post documents that research — ten integration patterns evaluated, four hard blockers hit, and one working solution found. If you are trying to get a Vertex AI agent to act on behalf of a real user in Google Workspace, this is the map I wish I had at the start. It is also, as far as I can tell, a pattern that is not widely documented — Google publishes the building blocks, but not this specific brokered OAuth + scripts.run + API Executable path for user-context Workspace execution from the Agent Platform.

The Problem: Two Identity Worlds

GCP and Google Workspace operate under fundamentally different identity models.

A GCP agent runs as a Service Account — a machine identity with IAM roles. Google Workspace operates under OAuth 2.0 user identities — real people who have granted consent to act on their data. These two worlds do not share an identity bridge. A Service Account cannot simply impersonate a Workspace user and call the Docs API as them. The chasm between these two identity models is the root cause of every integration problem in this space.

(Technically they can, with something called Domain Wide Delegation — where the Service Account has delegation to impersonate any user in the organisation, CEO included. Security teams tend to notice that, and it feels like using a sledgehammer to crack a nut.)

Apps Script sits in an interesting position. When deployed as a Web App or called via the Apps Script API, it runs as the deploying user — giving it native access to that user's Drive, Docs, Sheets, Calendar, and more. User consent wrapped up in a parcel.

How hard could it be.

That makes it a useful proxy across the chasm. But getting a GCP agent to call it securely is non-trivial — as the following ten patterns demonstrate.

What I Built

The use case: an onboarding agent that, given a client name, automatically creates a folder, a document, and a tracker spreadsheet on a shared Google Drive. If nothing else, an opportunity to understand how a GCP agent could be the front door to other Workspace systems.

The architecture that ended up working:

1. A GCP agent receives a natural language prompt like "onboard Client X for Project type Y"
2. The agent calls a Python tool function that invokes the Cloud Run OAuth broker
3. The broker retrieves the requesting user's OAuth token from Secret Manager and calls the Apps Script API (scripts.run) with it
4. Apps Script executes as that user and creates the Workspace artefacts
5. The result returns to the agent, which reports success

Simple to describe. Ten patterns to get there.

How the identity flows — Pattern 6 alone vs Pattern 6 + Pattern 10

Pattern 6 alone — single-user "run as me":

Pattern 6 + Pattern 10 — multi-user auth router:

Key Concepts Worth Understanding First

Some of the initial challenges I hit.

The two-step redirect pattern. Apps Script Web Apps don't return responses directly. Every POST returns a 302 redirect to a signed temporary URL where the actual response lives. Your HTTP client must follow the redirect — but without forwarding the Authorization header. If you forward the header to the redirect target, you get a 405. If you don't follow the redirect at all, you get an empty response. This is underdocumented and was the first thing that caught me out.

# The fix: follow redirects but strip the auth header
response = requests.post(
    url,
    json=payload,
    headers={"Authorization": f"Bearer {token}"},
    allow_redirects=False  # handle manually
)
if response.status_code == 302:
    redirect_url = response.headers["Location"]
    response = requests.get(redirect_url)  # no auth header on redirect

The shared drive trap. DriveApp.getFolderById() silently falls back to the user's personal My Drive when given a shared drive root ID. The call succeeds, the folder appears to be created — but it lands in the wrong place. The fix is to use the Advanced Drive Service (Drive.Files.insert with supportsAllDrives: true). Different API surface entirely, and the default one doesn't tell you it failed.

Deployment vs push. clasp push updates the development version of the script. It does not update the live deployment. That requires a new version number and an explicit deployment update via the REST API. Pushed changes have no effect on the running endpoint until you do this. I lost more time here than I should have. The kind of thing you only learn by losing an afternoon to it.

The playground identity. When testing via the Agent Builder playground, tool_context.user_id returns a system identity like "vais-query-reasoning-engine" — not an email address. Any domain check you write will reject it. Short-term fix: allowlist that identity explicitly for debug purposes. Remove this before any shared or production deployment — it is an authentication bypass.

The Deployment ID Trap. When calling the Apps Script API, the script ID from the browser URL will not work. You must use the API Executable Deployment ID — it starts with AKfy... and lives in the deployment settings. This is the single biggest cause of 404: Not Found errors in this integration and it is barely documented.

All Ten Patterns

Pattern 1 — Public URL + Payload Identity Check

Deploy Apps Script as a public Web App accessible to anyone. The calling agent POSTs a JSON payload containing an identity field — email or domain — and the script validates it before executing. The simplest possible integration and useful for prototyping, but the identity claim lives in the payload. Anyone who knows the URL can spoof it.

Pattern 2 — Domain-Restricted URL

Deploy Apps Script with access restricted to "Anyone in [your domain]." Google's network layer enforces that the caller must present a valid OAuth token for a user in your Workspace domain. Secure at the network level — but the agent runs as a GCP Service Account, not a Workspace user. It cannot satisfy the domain check without Domain-Wide Delegation, which pulls you straight into Pattern 4 territory.

Pattern 3 — GcpAuthProvider (Native OAuth Delegation)

The architecturally correct answer — and now the recommended path for Agent Engine deployments. Use the ADK's GcpAuthProvider to obtain an OAuth token scoped to a Workspace user via native delegation. Register an authorization resource via the Discovery Engine API and retrieve per-user tokens with tool_context.get_auth_response(AUTH_RESOURCE). No Cloud Run broker, no Secret Manager, no custom token exchange.

At time of writing (April 2026), the IAM connector resource creation was returning 404 on every call — a known tooling gap. That gap has since closed. If you are deploying on Agent Engine today, start here before building any of the custom infrastructure described in the patterns that follow.

Pattern 4 — Service Account + Domain-Wide Delegation

Grant the agent's Service Account domain-wide delegation via the Workspace Admin console. The SA can then impersonate any user in the organisation, generate an access token on their behalf, and call Apps Script as them. It works — but "any user in the organisation" includes the CEO, and security teams tend to notice that. A sledgehammer for a job that should need a screwdriver.

Pattern 5 — Direct Workspace APIs (Skip Apps Script)

Bypass Apps Script entirely and call Google Workspace REST APIs directly from the agent — Drive API, Docs API, Sheets API — using the SA's scoped IAM permissions. The cleanest option for straightforward CRUD operations that don't require Workspace-native logic or user-owned file creation. Worth considering before reaching for Apps Script at all.

Pattern 6 — API Bridge (scripts.run)

Pattern 6 answers how to call Apps Script from a GCP agent — but not as whom. That distinction matters.

The script is kept private — no Web App URL, no public endpoint. The calling surface is the Apps Script API (scripts.run), enabled by publishing an API Executable deployment. Access is controlled entirely by the user OAuth token presented in the call. The scriptId passed to the call is the AKfy... Deployment ID from the deployment settings — not the project ID from the editor URL. Using the project ID returns a 404.

The "as whom" constraint: scripts.run requires a user OAuth token — a raw Service Account token returns 404. That means Pattern 6 alone is a single-user "run as me" pattern: one stored refresh token, exchanged at call time, everything executes as the token owner. Clean and simple for personal automation. Hard ceiling the moment you need multiple users.

import google.oauth2.credentials
import googleapiclient.discovery

creds = google.oauth2.credentials.Credentials(
    token=None,
    refresh_token=STORED_REFRESH_TOKEN,  # store in Secret Manager — never in source
    token_uri='https://oauth2.googleapis.com/token',
    client_id=CLIENT_ID,
    client_secret=CLIENT_SECRET,
)
service = googleapiclient.discovery.build('script', 'v1', credentials=creds)
result = service.scripts().run(
    scriptId=SCRIPT_DEPLOYMENT_ID,  # AKfy... deployment id — not the project id
    body={'function': 'onboardClient', 'parameters': ['Client X', 'Project Y']}
).execute()

Pattern 7 — OIDC Token Validation on Public URL

Deploy Apps Script as a public Web App, but instead of trusting a payload identity claim, the agent attaches its GCP-issued OIDC token to the request. The Apps Script verifies the token cryptographically against Google's public keys, confirming the caller genuinely originated from your GCP project. The identity cannot be spoofed. This is the security foundation that Pattern 8 builds on.

One non-obvious constraint: Apps Script Web Apps do not expose the incoming Authorization header to doPost(e). The OIDC token has to travel in the request body, not as a header.

import google.auth.transport.requests
import google.oauth2.id_token

auth_req = google.auth.transport.requests.Request()
oidc_token = google.oauth2.id_token.fetch_id_token(auth_req, audience=APPS_SCRIPT_URL)
requests.post(APPS_SCRIPT_URL, json={'oidcToken': oidc_token, 'data': payload})

function verifyOidcToken(token) {
  const parts = token.split('.');
  const payload = JSON.parse(
    Utilities.newBlob(Utilities.base64DecodeWebSafe(parts[1])).getDataAsString()
  );
  const now = Math.floor(Date.now() / 1000);
  return payload.exp > now
    && payload.aud === APPS_SCRIPT_URL
    && payload.email.endsWith('@your-project.iam.gserviceaccount.com');
}

Note: this verifies claims but not the cryptographic signature. Full signature verification requires fetching Google's JWKS at https://www.googleapis.com/oauth2/v3/certs — possible in Apps Script via UrlFetchApp, but adds meaningful complexity.

Pattern 8 — Poor Man's Relay (Apps Script Cryptographic Relay)

A two-script architecture that stays entirely within Apps Script. A public "Gateway" script receives the OIDC-verified call from the agent and, because it runs as the script owner, generates its own OAuth token via ScriptApp.getOAuthToken(). It relays the request to a second "Worker" script deployed as domain-only, presenting its own token. No Cloud Run, no Secret Manager, no additional GCP infrastructure beyond the agent itself.

function doPost(e) {
  const body = JSON.parse(e.postData.contents);
  if (!verifyOidcToken(body.oidcToken)) {
    return ContentService.createTextOutput(JSON.stringify({ error: 'Unauthorized' }))
      .setMimeType(ContentService.MimeType.JSON);
  }

  const ownerToken = ScriptApp.getOAuthToken(); // owner's token, no setup required

  const resp = UrlFetchApp.fetch(WORKER_URL, {
    method: 'post',
    headers: { Authorization: 'Bearer ' + ownerToken, 'Content-Type': 'application/json' },
    payload: JSON.stringify(body.data),
    followRedirects: false,
    muteHttpExceptions: true,
  });

  // Strip the auth header on the redirect — forwarding it causes a 405
  const final = resp.getResponseCode() === 302
    ? UrlFetchApp.fetch(resp.getHeaders()['Location'])
    : resp;

  return ContentService.createTextOutput(final.getContentText())
    .setMimeType(ContentService.MimeType.JSON);
}

Pattern 9 — Cloud Run Proxy (Stateless)

Introduce a Cloud Run service as a stateless authentication proxy between the agent and Apps Script. Adds infrastructure and latency, but does not solve the core identity problem — the proxy still executes as a Service Account, not as the requesting user. Ruled out as complexity without the corresponding benefit.

Pattern 10 — Cloud Run OAuth Broker (Per-User Secret Manager)

A Cloud Run service that implements a full per-user OAuth consent flow. Users authenticate once via a /auth endpoint; their refresh tokens are stored in Secret Manager keyed by email. When the agent calls a tool, Cloud Run retrieves that user's refresh token, exchanges it for a fresh access token, and calls Apps Script as that specific person. Files are owned by the right user. Audit logs show the right name.

This is the right answer for custom runtimes, non-Agent Engine deployments, or anywhere native delegated auth is unavailable. For Agent Engine, Pattern 3 is now the cleaner path. The broker is detailed in the next article.

Where This Build Landed

This build runs on Pattern 6 + Pattern 10 — the working solution at the time Pattern 3 was unavailable.

• Pattern 6 (scripts.run via API Executable) answers how: publish an API Executable deployment, take the AKfy... deployment ID, and call scripts.run with a user OAuth token.
• Pattern 10 (Cloud Run OAuth broker) answers as whom: it holds a refresh token per user, resolves the right one at call time, and supplies a user OAuth token for the scripts.run call.

If you are building on Agent Engine today, start with Pattern 3 before reaching for this. The broker approach remains solid for anything outside that native path.

What Comes Next

The next article covers the Cloud Run OAuth broker in full — architecture, implementation, and the security boundaries that matter in production. It is framed as a custom-runtime pattern rather than a Gemini Enterprise default, which is the correct framing now that native Agent Engine auth exists.

A note on MCP. Google's current centre of gravity is clearly MCP — managed MCP servers, Workspace MCP surfaces, and first-class ADK support are all moving fast. MCP is the right answer for broad capability access, ecosystem interoperability, and "agent can use many tools" architectures. This pattern sits in a different lane: high-trust Workspace actions where identity, auditability, and deterministic execution matter more than tool universality. A narrow brokered tool catalogue can be easier to reason about, audit, and harden than a broad MCP surface — and it runs as the actual user, not a service account. The two approaches are complementary, not competing.

Part of an ongoing series on building AI agents in Google Cloud. All patterns tested against Gemini Enterprise Agent Platform (Agent Engine runtime), April 2026. Updated June 2026 to reflect native Agent Engine auth availability.

151 atoms with rendered examples. Browse by category, click schema.yaml for details. Auto-generated June 2026.

Cards & Components

Code & Technical

Content Structure

Data Visualization

Foundations

Inline Tools

Reading Experience

Text & Quotes