Forem: Tanaike

Recursive Knowledge Crystallization: Enabling Persistent Evolution and Zero-Shot Transfer in AI Agents

Tanaike — Thu, 02 Apr 2026 06:50:50 +0000

Abstract

This paper presents a self-evolving framework, Recursive Knowledge Crystallization (RKC), designed to overcome the "Catastrophic Forgetting" inherent in autonomous AI agents. By persisting evolved technical insights into a universally readable SKILL.md file based on the Agent skills specification, this approach establishes long-term memory and cross-platform portability. The framework was empirically validated through the development of gas-fakes, a highly complex Node.js-to-Google Apps Script (GAS) emulation library. The results demonstrate that agents can autonomously internalize project-specific architectural patterns and environmental nuances. Consequently, the framework achieves Zero-Shot Knowledge Transfer across distinct toolchains (Google Antigravity and the Gemini CLI) while maintaining absolute 1:1 behavioral parity with the live GAS environment.

1. Introduction

In recent years, the automation of software development by autonomous AI agents powered by Large Language Models (LLMs) has advanced rapidly. However, a critical barrier to the practical deployment of such agents is the absence of a "Persistence of Learning." Constrained by LLM context windows and session fragmentation, agents frequently suffer from "Catastrophic Forgetting," losing vital insights acquired during previous interactions. While memory-augmentation frameworks like Reflexion (Shinn et al., 2023) and MemGPT (Packer et al., 2023) have been proposed, they heavily rely on in-memory contexts, dedicated vector databases, or internal virtual memory abstractions. As a result, the acquired knowledge remains locked within specific agent instances, rendering it difficult to port across environments and nearly impossible for human developers to directly audit or manage.

While this limitation might remain latent in small-scale "greenfield" projects, it emerges as a fatal bottleneck when applying Generative AI to large, complex, and deeply constrained legacy projects. Thegas-fakes project, the subject of this empirical study, encountered this exact limitation. This project serves as a foundational library for converting various Google APIs into mock classes and methods compatible with the Google Apps Script (GAS) environment using Node.js. As the codebase and conversion rules grew in complexity, traditional prompting and standard GenAI approaches frequently resulted in "rule violations"—instances where the AI bypassed strict, project-specific coding conventions to force task completion. Despite repeated trial-and-error iterations and manual context adjustments, the success rate remained insufficient for practical use.

To fundamentally resolve this challenge, this paper introduces a self-evolving framework based on the Agent skills specification and its dynamic evolution model:Recursive Knowledge Crystallization (RKC). The defining innovation of this framework is the "Physical Knowledge Persistence" of the agent's operational guidelines and technical expertise. This knowledge is crystallized as a universally readable Markdown file (SKILL.md) directly onto the local file system.

By integrating Gemini 3 and 3.1 with next-generation toolchains—Google Antigravity and the Gemini CLI—we established the development process of gas-fakes itself as the agent's continuous learning environment. Specifically, whenever an error occurred during the implementation of new classes or when human developers provided corrective feedback, the agent was issued a single meta-instruction: "Extract insights from the failure and recovery process, and autonomously update your Agent skill (SKILL.md, sample scripts, and templates) by adding, deleting, or modifying content."

Through this iterative trial-and-error cycle, the agent accomplished more than merely avoiding local errors; it decoded the implicit rules and complex constraints inherent in the Node.js-to-GAS conversion, eventually internalizing and formalizing the project’s overarching architectural patterns. This evolutionary process extended beyond the SKILL.md text to include the refinement of helper scripts, templates, and technical specifications.

As the RKC progressed and the Agent skill reached a state of convergence, the agent fully internalized the complex operational logic of gas-fakes. This enabled accurate, rapid development strictly compliant with all project standards. Furthermore, by utilizing the standard file format, this method facilitates "Zero-Shot Knowledge Transfer": implicit knowledge acquired in one environment (e.g., Google Antigravity) can be seamlessly ported to an entirely clean environment (e.g., Gemini CLI) to generate flawless code on the first attempt. Simultaneously, persisting knowledge on a standard file system realizes a "True Human-AI Collaborative Paradigm," empowering human developers to fully visualize, audit, and guide the agent's cognitive evolution.

2. Workflow

The development of gas-fakes follows an iterative evolution of Agent skills, leveraging both Google Antigravity and the Gemini CLI. This process integrates a continuous feedback loop and culminates in Zero-Shot Knowledge Transfer through the physical persistence of evolved skills. The operational flow, visualized in Figure 2a, is defined by the following seven stages:

Task Initiation: A development task is assigned via a prompt to either Google Antigravity or the Gemini CLI, specifying the Google Apps Script (GAS) classes and methods to be emulated in the Node.js environment.
Autonomous Implementation: Utilizing the current Agent skill (gas-fakes-dev), the agent generates the corresponding Node.js classes and methods. Simultaneously, a test suite is authored by strictly adhering to the architectural patterns defined within the SKILL.md.
Local Environment Validation: The generated test scripts are executed in the local Node.js environment. If runtime errors or logic discrepancies occur, the AI autonomously refactors the implementation and the test code until local stability is achieved.
Cross-Platform Synchronization: Following local success, the implementation is deployed to the Google-side script editor (GAS environment). This ensures that the emulation maintains 1:1 parity with the live GAS engine.
Remote Feedback & Refinement: If the test suite encounters environment-specific errors in the GAS script editor (e.g., subtle differences in string output formatting or synchronous execution behavior), these errors are fed back to the AI for immediate remediation.
Knowledge Crystallization: Once the implementation passes in both local and remote environments, the task is flagged as complete. At this juncture, the AI performs a self-audit to extract critical insights—such as previously undocumented GAS constraints or reusable design patterns—and autonomously updates the Agent skill (SKILL.md, helper scripts, and templates).
Recursive Evolution Loop: Stages 1 through 6 are continuously cycled. As the SKILL.md matures, it transitions from a set of generalized instructions to a highly specialized, project-aware expert system, enabling the agent to resolve increasingly complex architectural challenges with minimal human intervention.

Fig 2a: The 7-stage operational workflow of Recursive Knowledge Crystallization.

3. Methodology: Environment Setup and Initialization

In this article, it is assumed that Node.js, Google Antigravity, and Gemini CLI have already been installed. To establish the baseline for developing gas-fakes, the repository is cloned as follows:

git clone https://github.com/brucemcpherson/gas-fakes
cd gas-fakes

In this empirical study, Google Antigravity and Gemini CLI were utilized in tandem to evolve the agent skill. First, the initial agent skill was established. The directory structure is outlined below. To ensure both agent environments utilized the exact same skill base (gas-fakes-dev), they were synchronized using a symbolic link.

gas-fakes/
├── .agent/
│   └── skills/
│       └── gas-fakes-dev/
│           └── SKILL.md
└── .gemini/
    └── skills -> ../.agent/skills/  (symbolic link)
        └── gas-fakes-dev/
            └── SKILL.md

Alternatively, to avoid manual linking between the .agents and .gemini directories, the gemini.md configuration file can be utilized to instruct the Gemini CLI to consistently reference the .agents/workloads and .agents/skills folders. This ensures seamless resource sharing between the CLI and Google Antigravity. Furthermore, including a directive to automatically activate the gas-fakes-dev skill within this configuration streamlines the entire initialization process.

The baseline SKILL.md was formulated as a generic directive. During the development of gas-fakes, this specific skill file served as the target for continuous evolution.

---
name: gas-fakes-dev
description: "Develop and implement the 'gas-fakes' project, emulating Google Apps Script (GAS) functionality using Node.js."
tags:[nodejs, google-apps-script, google-cloud-api, testing, mock]
version: "1.0.0"
---

## Summary
This skill enables the agent to assist in the development of the `gas-fakes` project. The primary objective is to emulate Google Apps Script (GAS) behavior using Node.js and Google APIs, allowing Apps Script code to run in a local Node.js environment.

## Usage
- When you need to implement fake/mock functionality for GAS classes or methods.
- When creating test scripts to verify the implemented functionalities.
- When assisting a human developer with Node.js and Google APIs integration.

## Workflow

### 1. Context and Specification Check
Before implementing, verify the specifications of the target Google Apps Script classes and methods. Ensure that the functionality you are about to build aligns with real GAS behavior.

### 2. Implementation
Generate Node.js code that maps GAS methods to the corresponding Google Cloud APIs.
- Refer to the existing codebase in the `src/` directory to understand the current architecture.
- Ensure the code runs correctly in the Node.js environment.

### 3. Testing
You must verify your implementation by writing and executing test scripts.
- Place your test scripts in the `test/` directory.
- Execute the tests to ensure there are no errors and the behavior matches expectations.

### 4. Holistic/Targeted Skill Evolution (Self-Updating SKILL)
**[CRITICAL INSTRUCTION]**
The `gas-fakes` project is complex, and bridging Node.js with GAS involves many hidden constraints, specific architectural patterns, and potential errors. You are required to continuously learn and autonomously evolve this SKILL.

- **Trigger:** Whenever you encounter an error during implementation or testing, or when you receive correction feedback/prompts from the human developer.
- **Action:** You MUST extract the lessons learned from the failure and recovery process. Identify the underlying rules, technical constraints, or coding patterns that caused the issue.
- **Update:** Immediately update this `SKILL.md` file (by adding, deleting, or modifying content) to document the newly acquired knowledge. If necessary, also create or update sample scripts, helper templates, or explanatory Markdown files in the project.
- **Goal:** Transform your localized, temporary learnings into permanent, universally readable knowledge to prevent repeating the same mistakes and to handle the complexities of the project autonomously.

## Delivery
- Output the complete code for modified or newly created service classes and test scripts.
- **ALWAYS output the updated `SKILL.md`** when new knowledge is extracted and crystallized.

Also, please install Model Context Protocol (MCP) servers for Google Workspace development. Ref This MCP server is used from this agent skill.

When a command /gas-fakes-dev is put into the chat, this skill can be activated.

Because gas-fakes emulates Google Apps Script using Node.js, generated test scripts are strictly required to function flawlessly in both the local Node.js environment and the cloud-based Google Apps Script editor. Utilizing the initial, generic skill often resulted in scripts that passed locally but failed in the cloud environment. This discrepancy served as the primary catalyst for triggering the agent's evolutionary loop.

4. Crystallization of Knowledge: The Evolved Agent Skill

After extensive trial and error implementing various GAS classes and methods, the agent dynamically restructured and expanded its own skill set.

The evolved repository structure incorporated new templates, examples, and scripts generated by the agent to support its new architectural insights. You can see the details of this agent skill from https://github.com/tanaikech/agent-skill-for-developing-gas-fakes.

gas-fakes/
├── .agent/
│   └── skills/
│       └── gas-fakes-dev/
│           ├── examples/
│           │   ├── batch_update_pattern.js
│           │   └── proxy_guard_pattern.js
│           ├── resources/
│           │   ├── class_template.js
│           │   ├── sync_mechanism.md
│           │   └── test_template.js
│           ├── scripts/
│           │   ├── run_target_test.js
│           │   └── scaffold_service.js
│           └── SKILL.md
└── .gemini/
    └── skills -> ../.agent/skills/  (symbolic link)
        └── gas-fakes-dev/
            ├── examples/
            ├── resources/
            ├── scripts/
            └── SKILL.md

The resultant, highly complex SKILL.md (Version 2.0.0) evolved into a comprehensive system architecture document as follows. Ref

---
name: gas-fakes-dev
description: Develop, implement, and test the 'gas-fakes' project, emulating ALL Google Apps Script (GAS) functionality using Node.js and Google APIs.
tags: [nodejs, google-apps-script, google-cloud-api, testing, mock, simulation]
version: "2.0.0"
---

## Summary
This skill enables the agent to act as a Senior Expert proficient in Node.js, Google Cloud, and Shell Scripting to assist in the development of the `gas-fakes` project.
The ultimate objective is to **emulate the behavior of live Google Apps Script exactly** by mapping classes and methods to their fake equivalents. This allows Apps Script to run anywhere Node runs.
This is achieved using a **worker mechanism** to handle the conversion from synchronous (Apps Script) to asynchronous (Google APIs) operations, returning the results synchronously. Ultimately, all Apps Script classes and methods will be available via `gas-fakes`. For a deep dive into this mechanism, see the [Sync-to-Async Bridge Guide](./resources/sync_mechanism.md).

## Usage
- When you need to implement or modify mock functionality for specific GAS classes or methods.
- When creating logic that reproduces GAS behavior using Google APIs and the worker mechanism.
- When adding new service classes to fit the existing `gas-fakes` project structure.
- When creating test scripts and registering them for local execution within the `test/` directory.
- When executing generated Apps Script files locally.
- When technical advice or debugging assistance based on GAS specifications is required.

## Configuration
`gas-fakes` relies on an `.env` file (maintained by `gas-fakes init` and `auth`) to properly authenticate and run.

### Authentication Methods
- **DWD (Domain Wide Delegation) - *Preferred***: Uses a service account to impersonate a user logged into gcloud. The service account name must be specified in the `.env` file. This is **required** if restricted/sensitive scopes are needed, or if running `gas-fakes` on Google Cloud Run.
- **ADC (Application Default Credentials)**: If no `.env` file is provided, `gas-fakes` falls back to ADC. This is usually fine for local development as standard `cloud_platform` and `drive` scopes are automatically assigned during auth.

Ensure your `.env` is properly loaded (e.g., using `node --env-file <env-file>` or `gas-fakes -e <env-file>`) to ensure DWD is used when necessary.
- **`TEST_SPREADSHEET_ID`**: (Optional) Spreadsheet ID for real-environment testing.

## Workflow

### 1. Context, Specification, and Dependency Check
Before starting implementation, you must understand the full scope and style of the project.

- **Restricted Directories**:
  * **NEVER modify any files located in the `progress` directory** during the development of `gas-fakes`. This directory is strictly off-limits.

- **Mandatory Existence Verification**:
  When adding or updating ANY class or method, you must **ALWAYS use the `workspace-developer` MCP server** (if available) or search official documentation to verify the existence and specification of the target and ALL related classes/methods.
  *   **NEVER create classes or methods that do not exist in the actual Google Apps Script environment.**
  *   Do not guess. Confirm exact names, parameter structures, and return types.
  *   *Example*: If implementing `Sheet.getCharts()`, check what object it returns (`EmbeddedChart` vs `Chart`) and verify the methods available on that returned object.

- **Strict Enum Verification**:
  **Do not invent Enums.** Before using or creating an Enum, verify if it actually exists in Google Apps Script.
  *   **Note on `ChartType`**: In Google Apps Script, `ChartType` is a property of the `Charts` service (`Charts.ChartType`), not `SpreadsheetApp`.

- **Reference Existing Code**:
  Check the `src` and `test` directories to understand the existing coding style and architecture. Apply these patterns to new classes and methods.

- **Identify Dependencies**:
  Identify and implement **all related classes and methods** required for the target feature. (e.g., if `newChart()` returns `EmbeddedChartBuilder`, verify/implement that builder class too).

### 2. Scaffolding
Do not create service files manually. Use the provided helper script.

- **Command**:
  \`\`\`bash
  node .agent/skills/gas-fakes-dev/scripts/scaffold_service.js --service=<ServiceName> --class=<ClassName>
  \`\`\`

### 3. Implementation
Generate code based on Node.js best practices, adhering to these rules to maintain environmental consistency with live Apps Script:

- **Comprehensive Implementation**: Implement the target feature and its dependencies together.
- **Cross-Environment Compatibility**: Scripts must be designed to run on both Node.js (local) and GAS Script Editor with identical results.
- `toString()` Accuracy: The `toString()` method must return the **exact GAS class name or specific string output** (e.g., `"Sheet"` or `"[Document:  ...]"`). Pay extreme attention to whitespace; GAS output can contain double spaces (e.g., after a colon).
- **Dynamic Resources and Caching Pattern**:
  *   **The `__resource` property**: Always access the underlying API state via the dynamic `__resource` getter (tracing back to the parent element or a synchronized cache).
  *   **Stale State Prevention**: NEVER store API resources directly in class instance variables. They will become stale when the cache is cleared.
  *   **Cache Invalidation**: Every time a destructive API call is made, the cache is cleared. Dynamically accessing `__resource` ensures you get the most up-to-date state from the API or the fresh cache.
- **Implementation Patterns**:
  1. Use `signatureArgs` or `is.*` utilities.
  2. Construct the request object.
  3. Execute via `this.__batchUpdate` (or helper).
  4. Return `this` for chaining.

- **Coding Patterns**:
  *   **Naming**: Internal implementation classes should be prefixed with `Fake` (e.g., `FakeSheet`, `FakeEmbeddedChart`).
  *   **Lazy Loading**: New top-level services must be registered using the `lazyLoaderApp` pattern in their respective `app.js` to ensure they are only instantiated when accessed.
  *   **Singleton Pattern**: Service entry points usually export a "maker" function (e.g., `newFakeSpreadsheetApp`) that return the singleton instance.

- **Specific Technical Nuances**:
  *   **Sync-to-Async Bridge**: Always use the worker bridge for external API calls to maintain synchronous Apps Script behavior. Follow the pattern: `Fake Class` -> `Syncit (fx*)` -> `callSync` -> `Worker Loop` -> `sx* Function` -> `sxRetry`. See [detailed guide](./resources/sync_mechanism.md) for implementation steps.
  *   **Charts**: When retrieving a chart's title, use `getOptions().get("title")` instead of internal specs.
  *   **EmbeddedChart**: To get the type of an existing chart, use `modify().getChartType()` instead of a non-existent `getType()` method.
  *   **GridRange to FakeRange Conversion**: When mapping an API `GridRange` to a `FakeSheetRange`:
    *   Indices in the API are 0-indexed and the end index is **exclusive**.
    *   GAS methods (like `getRange(row, col, numRows, numCols)`) use 1-indexed start positions and row/column counts.
    *   If `endRowIndex` or `endColumnIndex` is undefined in the API response, it means the range extends to the boundary of the sheet. Use `sheet.getMaxRows()` and `sheet.getMaxColumns()` as fallbacks to calculate `numRows` and `numCols`.
  *   **ContainerInfo**: This class is used by `EmbeddedChart`, `Slicer`, and `Drawing`.
    *   Map `getAnchorRow()` and `getAnchorColumn()` to 0-indexed API fields `anchorCell.rowIndex + 1` and `anchorCell.columnIndex + 1`.
    *   Map `getOffsetX()` and `getOffsetY()` directly to `offsetXPixels` and `offsetYPixels`.
  *   **XmlService**:
    *   `Element.getName()` returns the **local name** (no prefix).
    *   `Document.toString()` output is very specific: `[Document:  No DOCTYPE declaration, Root is [Element: <rootName/>]]` (note the double space after `Document:`).
    *   Namespace-aware methods (like `getChild(name, namespace)`) require mapping prefixes and URIs correctly.

### 4. Testing
You must ensure every implementation is verified by tests that precisely emulate Google Apps Script behavior.

- **Mandatory Feature Coverage**:
  - **Every new class or method MUST have a corresponding test.**
  - If you implement multiple methods, create a test script that exercises all of them.
  - Test only implemented features; do not include placeholders for future work.

- **Edge Case Capturing**:
  - **Capture and verify boundary conditions, invalid inputs, and error states.**
  - Use `t.rxMatch(t.threw(() => ...).message, /regex/)` to verify that methods throw expected GAS error messages when given invalid arguments.
  - Test with `null`, `undefined`, empty strings, and out-of-bounds values where applicable to ensure robust emulation.

- **GAS Compatibility Requirement**:
  - Test logic (inside `unit.section`) must be compatible with the **Google Apps Script script editor**.
  - Avoid Node.js-specific modules (e.g., `fs`, `path`) inside the test logic.
  - Use `ScriptApp.isFake` or `xxxApp.isFake` to toggle environment-specific logging or assertions.

- **Test Script Structure**:
  - **Imports**: standard test scripts import `@mcpher/gas-fakes`, `@sindresorhus/is`, and helpers from `./testinit.js` and `./testassist.js`.
  - **Export Pattern**: Export a named function (e.g., `export const testService = (pack) => { ... }`) to allow integration into the main test suite.
  - **Execution Hook**: Always include `wrapupTest(testService);` at the end of the file for standalone execution.
  - **Sections**: Use `unit.section("description", (t) => { ... })` to group tests.

- **Resource Lifecycle and Cleanup**:
  - **The `toTrash` pattern**: Maintain a `toTrash` array within your test function. Push any created resources (files, folders, sheets) into this array.
  - **Automatic Cleanup**: Use `trasher(toTrash)` at the end of the test function (usually triggered if `fixes.CLEAN` is true) to ensure the test environment remains pristine.

- **Naming Convention**:
  - **Google Sheets**: `testsheets{class name}.js` (e.g., `testsheetsrange.js`)
  - **Google Docs**: `testdocs{class name}.js`
  - **Google Slides**: `testslides{class name}.js`
  - **General/Other**: `test{service}{class name}.js`

- **Registration**:
  1. Create the file in `test/`.
  2. Add to `test/test.js`.
  3. Add a script entry in `test/package.json`.

- **Execution**:
  > [!IMPORTANT]
  > **Run tests from the `test/` directory.**
  > `cd test && node test{filename}.js execute` (or `npm run <script-name>`).

- **Clasp Verification**:
  Use `testongas/test/` to verify against a real GAS project via `clasp`.

### 5. Executing Generated Scripts
You can execute any generated Apps Script file using `gas-fakes` in a local sandbox.

- **Testing the Local Branch (Preferred for Dev)**:
  Use the local `.env` file and run the local `gas-fakes` implementation.
  \`\`\`bash
  node --env-file ./.env gas-fakes -f myscript.js
  \`\`\`
- **Testing Global Installation**:
  \`\`\`bash
  npx gas-fakes -f myscript.js
  \`\`\`
  *(Sandbox flags can be added as requested by the user to control the environment)*

### 6. Refinement & Continuous Evolution (Self-Updating SKILL)
To ensure the `gas-fakes` project and this SKILL continuously evolve and improve efficiently, you **MUST** actively refine and update the SKILL definition (`SKILL.md`) and its associated resources based on the outcomes of your development processes.

#### 6.1 Skill Audit Criteria
At the conclusion of every task, perform a "Self-Audit" by answering:
1. **New Pattern?** Did I implement a new mapping logic (e.g., API-to-GAS index shifts) or a reusable architectural pattern?
2. **Missing Nuance?** Did I encounter a technical detail (like a specific `toString()` format or Enum location) that wasn't documented?
3. **Corrected Assumption?** Did a test failure or user hint reveal that a rule in this SKILL was incomplete or incorrect?
4. **New Service?** Did I add a new class that requires a dedicated section in the "Technical Nuances" list?

#### 6.2 Prompt for Update Mandate
If any criteria in the "Skill Audit" are met, you MUST:
- **Analyze the New Knowledge**: Determine what core knowledge, rule, constraint, or pattern was derived from the success or resolution.
- **Identify the Change**: Specifically state what needs to be added, modified, or deleted in `SKILL.md`.
- **Propose the Edit**: Present the specific Markdown block intended for the update.
- **Ask for Confirmation**: Explicitly ask the user: *"Based on this task, I recommend updating the SKILL.md with the following [nuance/pattern]. Should I apply this change?"*
- **Update Associated Assets**: If the new knowledge involves a reusable code structure or boilerplate, add or update files in the `examples/`, `resources/`, or `scripts/` directories to reflect the new best practice.

### 7. Delivery
- **Output**: Full content of modified or newly created files (Service class, Node.js test, etc.).
- **Skill Audit**: Provide a brief (1-2 sentence) summary of your Self-Audit results.
- **Update Prompt**: If any audit criteria were met, issue the "Prompt for Update" as defined in section 6.2.
- **Finality**: Conclude with a concise summary of the task results.

Key Milestones in the Agent's Evolution:

Role and Expertise Reclassification: The agent's persona autonomously shifted from a general "assistant" to a "Senior Expert" with specific cross-domain mastery in Node.js, Google Cloud, and Shell Scripting.
Architectural Specification (Sync-to-Async Bridge): The evolved skill introduced a sophisticated "worker mechanism" and "Syncit" pattern. This addressed the core technical challenge of mapping asynchronous Node.js/Google APIs to the synchronous execution model of Google Apps Script.
Strict Verification & Grounding: New mandates required the use of the workspace-developer MCP server and official documentation. This systematically eliminated "hallucinated" methods, ensuring absolute 1:1 parity with the live GAS environment.
Technical Nuance Crystallization: Highly specific, undocumented "gotchas" discovered during the failure/recovery loops were codified. This included 0-indexed vs. 1-indexed coordinate conversions, exact string matching for toString() (including hidden whitespace), and specific Enum locations.
Self-Evolution Logic (Crystallization Loop): The trigger for skill updates shifted from a reactive "whenever an error occurs" (v1) to a proactive, structured "Self-Audit" protocol (v2). The agent learned to analyze patterns, propose edits to the human developer, and automatically update associated boilerplate assets.

5. Empirical Evaluation: Cross-Environment Knowledge Transfer

To validate the efficacy of the RKC framework, practical development tasks were executed utilizing the actively evolving agent skill across two distinct interfaces: Google Antigravity and the Gemini CLI.

5.1 Evaluation in Google Antigravity

Sample 1: Architectural Refinement via Self-Audit

Prompt1:

Add the method `insertTextBox(String,Number,Number,Number,Number)` of Class Slide. This method should be included in the file `src/services/slidesapp/fakeslide.js`.

Prompt2:

Add the method `insertTable(Table)` of Class Slide. This method should be included in the file `src/services/slidesapp/fakeslide.js`.

Fig. 3a: Agent executing implementation and autonomously applying the Dynamic Resources Pattern.

To evaluate continuous learning, we tasked the agent with implementing insertTextBox and insertTable. The task required creating underlying architectural dependencies, such as FakeTable, FakeTableRow, and FakeTableCell. Initially, the agent generated functional code. However, as shown in Figure 3a, the true strength of the framework was demonstrated during the self-evolution phase. The agent autonomously identified a potential flaw regarding resource management. It proactively refactored the classes to adhere to a newly conceptualized "Dynamic Resources Pattern," replacing static constructor assignments with dynamic getters to ensure robust state synchronization. Crucially, the agent updated SKILL.md with this rule, ensuring future compliance. Following this refinement, all 23 test cases passed with 100% accuracy.

Sample 2: Internalization of Design Philosophy

Prompt:

Add the method `getTables()` of Class Slide. This method should be included in the file `src/services/slidesapp/fakeslide.js`.
Add the method `getShapes()` of Class Slide. This method should be included in the file `src/services/slidesapp/fakeslide.js`.

Fig. 3b: Agent applying functional programming patterns to dynamically cast page elements.

In this experiment (see Figure 3b), the agent demonstrated a deep internalization of the project's design philosophy. Instead of implementing redundant storage logic for arrays of specific shapes, it autonomously utilized the generic getPageElements() method, applying .filter() and .map() to dynamically cast elements. This approach perfectly adhered to the "Dynamic Resources Pattern" crystallized in the previous task. All 28 assertions in the subsequent test suite passed flawlessly.

Sample 3: Bridging Environmental Discrepancies

Prompt 1 & 2 (Summarized):

Add a Class XmlService and a method `parse`...
When `test/testxmlservice.js` is run with the script editor of Google Apps Script, the error occurred. Update the scripts.

Fig. 3c: Agent resolving GAS-specific formatting rules through remote feedback.

This task required bridging the gap between Node.js simulation and actual GAS behavior for XML parsing. While the initial code passed local Node.js tests, execution in the GAS editor revealed critical discrepancies, such as unique double-space formatting in toString() outputs ([Document: No DOCTYPE...]) and precise namespace handling. Upon receiving this remote error feedback (see Figure 3c), the agent performed a systemic refactoring. Following the RKC framework, it updated the SKILL.md, formally persisting these "hidden" GAS-specific formatting rules as permanent constraints.

Sample 4: Achieving Environment-Aware Precision

Prompts 1, 2 & 3 (Summarized):

Add the `getPrettyFormat` and `getRawFormat` methods to the `XmlService` class.
Resolve issues regarding \r\n line breaks appearing in raw format tests on GAS...

Fig. 3d: Agent crystallizing nuanced serialization behaviors into persistent memory.

This experiment focused on achieving high-fidelity parity with GAS’s unique XML serialization. Through iterative feedback, the agent discovered that GAS consistently injects a line separator (\r\n) after the XML declaration and at the document's end, even in "raw" format. As captured in Figure 3d, the agent refactored the FakeFormat class and crystallized these insights into SKILL.md. Final verification yielded a 100% success rate across 21 test cases, proving the framework's capacity for "Environment-Aware Precision."

5.2 Zero-Shot Knowledge Transfer via Gemini CLI

Sample 1: Cross-Platform Environment Porting

Prompt:

Implement the following methods for the `ContainerInfo` class within the `EmbeddedChart` class hierarchy of Google Sheets: `getAnchorColumn()`, `getAnchorRow()`, `getOffsetX()`, and `getOffsetY()`.

Please follow these operational guidelines:
1. **Skill Declaration**: Explicitly state the agent skills or tools being utilized before proceeding.
2. **Task Execution & Summary**: Provide the implemented code/definitions and conclude with a concise summary of the task results.

Fig. 3e: Gemini CLI agent achieving Zero-Shot Knowledge Transfer utilizing the shared SKILL.md.

This experiment validated the "Zero-Shot Knowledge Transfer" capability by transitioning the execution environment entirely from Google Antigravity to the Gemini CLI. By referencing the highly evolved SKILL.md persisted on the local file system, the CLI-based agent immediately understood the complex architectural patterns (see Figure 3e). It autonomously implemented FakeContainerInfo using the project-specific Proxies.guard pattern. The generated code strictly followed naming conventions and correctly converted 0-based API indices to 1-based GAS indices on its very first attempt, passing all 11 tests with 100% accuracy.

Sample 2: Agents as Architectural Contributors

Prompt:

Implement the `getRanges()` method for the `EmbeddedChart` class in the Google Sheets service.

Please follow these operational guidelines:
1. **Skill Declaration**: Explicitly state the agent skills or tools being utilized before proceeding.
2. **Task Execution & Summary**: Provide the implemented code/definitions and conclude with a concise summary of the task results.

Fig. 3f: Gemini CLI agent performing a Self-Audit and proposing architectural updates.

Focusing on the getRanges() method, the CLI agent transformed nested API GridRange structures into GAS Range instances. It elegantly handled discrepancies between exclusive 0-based API bounds and inclusive 1-based GAS boundaries. Most significantly, as shown in Figure 3f, the agent autonomously triggered its "Skill Audit" protocol upon completion. It identified a recurring logic pattern for GridRange conversions and proactively recommended a structural update to the SKILL.md. This illustrates that the RKC framework enables agents to transcend basic execution, allowing them to act as proactive "Architectural Contributors."

6. Conclusion

Through the empirical development of the gas-fakes emulation library, this research validates the profound efficacy of the Recursive Knowledge Crystallization (RKC) framework. Key findings include:

Physical Knowledge Persistence: By crystallizing an agent's evolving technical expertise into universally readable, local Markdown files (SKILL.md), the framework successfully mitigates "Catastrophic Forgetting" and establishes an auditable, persistent memory layer.
Recursive Evolution Loop: The implementation of an autonomous "Self-Audit" protocol enabled the agent to systematically extract architectural insights from failure/recovery cycles, thereby refining its own operational directives.
Environment-Aware Precision: The agent successfully codified highly obscure, undocumented system constraints (e.g., hidden string formatting and complex coordinate mapping logic) directly into its skill set, guaranteeing high-fidelity behavioral emulation.
Zero-Shot Knowledge Transfer: The study empirically proved that evolved, highly specialized skills can be seamlessly and instantaneously ported across entirely distinct environments (from Google Antigravity to Gemini CLI), enabling the generation of structurally perfect code on the first attempt.
Human-AI Collaboration: The framework realizes a novel development paradigm where the AI agent operates not merely as a localized code generator, but as an active, persistent "Architectural Contributor" capable of scaling and maintaining deeply constrained codebases.

Note

It should be noted that the "Agent skill" development methodology and the self-evolution process introduced in this paper do not necessarily represent a state where evolution has reached full saturation. As AI technology and its surrounding ecosystems continue to advance, there remains significant untapped potential in the structures through which agents define themselves and "crystallize" their knowledge.

By further pushing the boundaries of this development framework, we anticipate that even greater evolutionary leaps will occur. Such progress will likely lead to even higher levels of development efficiency, transcending current expectations and moving toward a more sophisticated phase of software automation and human-agent synergy.

Mastering Google Apps Script CI/CD: Seamless GitHub Actions Integration with gas-fakes

Tanaike — Wed, 25 Mar 2026 07:20:29 +0000

Abstract

Discover how to seamlessly integrate Google Workspace with GitHub Actions using the gas-fakes library. This guide demonstrates running Google Apps Script locally and within CI/CD pipelines without deploying Web Apps. Automate workflows, secure credentials, and effortlessly interact with Google Drive and Sheets directly from your repository.

Introduction

Google Apps Script (GAS) is a powerful low-code platform that enables developers to integrate, automate, and extend Google Workspace with ease. Ref Typically, executing GAS requires the script to be hosted on Google's servers via the Script Editor. While tools like clasp allow for local development and synchronization, running scripts from outside the Google ecosystem—such as from a local environment or a different cloud provider—often involves complex setups relying heavily on the Apps Script API or Web Apps. Ref

A common approach to triggering GAS from GitHub Actions is using Web Apps. However, this method presents several hurdles. Developers must re-deploy the Web App every time the script is updated, and verifying the latest code logic directly within the repository can be cumbersome. This is where gas-fakes becomes a game-changer. Ref Operating as a robust emulation layer, gas-fakes allows GAS projects to run on Node.js as if they were native, enabling seamless execution across various environments.

By leveraging gas-fakes within GitHub Actions, you can manage, test, and update your scripts directly inside your repository without the need for constant re-deployment. Furthermore, by storing sensitive credentials in GitHub's "Secrets and variables," you can ensure a high level of security for your automation workflows. This synergy between GitHub Actions and GAS opens up infinite possibilities for CI/CD application development. In this article, I will introduce a streamlined, professional method for managing Google Workspace using GitHub Actions and gas-fakes.

Phase 1: Setup and Authentication

To establish this pipeline, we first need to extract the proper authorization credentials and configure our GitHub repository.

Step 1: Obtain Authorization Data

In order to authorize gas-fakes, you must first generate Application Default Credentials (ADC) on your local machine. The Google Cloud CLI (gcloud) is required for this step. Detailed installation instructions can be found in the gas-fakes official documentation.

If you prefer using npx, execute the following commands in your terminal:

npx @mcpher/gas-fakes init --auth-type adc

npx @mcpher/gas-fakes auth

Alternatively, if you want to install the package globally via npm, run:

npm install -g @mcpher/gas-fakes

gas-fakes init --auth-type adc

gas-fakes auth

Once the authorization is complete, retrieve your credentials file.

For Linux / macOS:

cat ~/.config/gcloud/application_default_credentials.json

For Windows:

type C:\Users\{user name}\AppData\Roaming\gcloud\application_default_credentials.json

Copy the output. Your authorization data will look similar to the following JSON structure:

{
  "account": "",
  "client_id": "{your client ID}",
  "client_secret": "{your client secret}",
  "quota_project_id": "{your project ID}",
  "refresh_token": "{your refresh token}",
  "type": "authorized_user",
  "universe_domain": "googleapis.com"
}

Step 2: Create a New GitHub Repository

To test this integration, create a new repository on GitHub. For this guide, we will assume the repository name is sample.

Step 3: Configure GitHub Secrets

We must securely store the authorization data in GitHub. Navigate to your repository's "Settings" -> "Secrets and variables" -> "Actions". Click on "New repository secret" and configure the following:

Key: GCP_ADC_USER_JSON

Value: (Paste the JSON string you copied in Step 1)

{
  "account": "",
  "client_id": "{your client ID}",
  "client_secret": "{your client secret}",
  "quota_project_id": "{your project ID}",
  "refresh_token": "{your refresh token}",
  "type": "authorized_user",
  "universe_domain": "googleapis.com"
}

When the gh command is used, you can also use the following command.

gh secret set GCP_ADC_USER_JSON < ~/.config/gcloud/application_default_credentials.json

Phase 2: Building Your First Workflow

Step 4: Define the GitHub Actions Workflow

Create a new YAML file named sample1.yml inside the .github/workflows/ directory of your repository.

name: Run GAS via gas-fakes (sample1)

on:
  push:
    branches: ["*"]
  pull_request:
    branches: ["*"]
  issues:
    types: [opened, edited, closed]
  workflow_dispatch:

jobs:
  execute:
    name: sample1
    runs-on: ubuntu-latest
    env:
      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"

      - name: Create ADC file
        run: |
          echo '${{ secrets.GCP_ADC_USER_JSON }}' > /tmp/adc.json

      - name: Extract Project ID from ADC
        run: |
          echo "PROJECT_ID=$(jq -r '.quota_project_id' /tmp/adc.json)" >> $GITHUB_ENV

      - name: Run Google Apps Script by gas-fakes
        run: |
          export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
          export GOOGLE_APPLICATION_CREDENTIALS=/tmp/adc.json
          npx @mcpher/gas-fakes -s "const rootFolder = DriveApp.getRootFolder(); const rootFolderName = rootFolder.getName(); console.log(rootFolderName);"

In this initial test, a simple Google Apps Script snippet (const rootFolder = DriveApp.getRootFolder();...) is passed directly as an inline string within the YAML file.

Step 5: Push to the Remote Repository

Commit and push your local repository to GitHub. This action will automatically trigger the GitHub Actions workflow. You can monitor the execution under the "Actions" tab. If successful, the step "Run Google Apps Script by gas-fakes" will output logs similar to this:

...using env file in /home/runner/work/github-action-for-gas-fakes/github-action-for-gas-fakes/.env
...gas-fakes version 2.2.7[Worker] ...authorized backends: google via ADC (###@gmail.com)[Worker] ...using scriptId: ### (source: random)
マイドライブ
...terminating worker thread

Seeing your Google Drive's root folder name in the logs confirms that gas-fakes successfully authenticated and executed the GAS code natively via GitHub Actions.

Phase 3: Advanced Practical Applications

To demonstrate the full potential of this architecture, let's explore two practical CI/CD use cases: recording execution logs to Google Sheets and uploading repository diffs to Google Drive.

When this phase is finished, the directory structure of this repository becomes as follows.

Please create the following package.json and put into the root directory.

{
  "name": "gas-fakes-workflow",
  "version": "1.0.0",
  "description": "Google Apps Script execution on GitHub Actions with gas-fakes",
  "main": "sources/sample2.js",
  "type": "module",
  "scripts": {
    "sample2": "node sources/sample2.js",
    "sample3": "node sources/sample3.js"
  },
  "dependencies": {
    "@mcpher/gas-fakes": "^2.3.0"
  },
  "engines": {
    "node": ">=24"
  }
}

.gitignore is as follows.

node_modules/
.env

Also, in order to create package-lock.json, please run npm install at the local side.

As another file, please create appsscript.json in the root directory as follows.

{
  "timeZone": "Asia/Tokyo",
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": ["https://www.googleapis.com/auth/drive"]
}

Case 1: Record Execution Logs to Google Sheets

In this scenario, whenever a push, pull request, issue event, or manual trigger occurs, the workflow stores detailed execution logs in a Google Spreadsheet named sample spreadsheet for gas-fakes sample. If the file doesn't exist, it is automatically created in the root folder of your Google Drive.

Add the following YAML file to .github/workflows/sample2.yml:

name: Run GAS via gas-fakes (sample2)

on:
  push:
    branches: ["*"]
  pull_request:
    branches: ["*"]
  issues:
    types: [opened, edited, closed]
  workflow_dispatch:

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
  execute:
    name: sample2
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: "npm"

      - name: Install dependencies
        run: npm install

      - name: Create ADC file
        run: |
          echo '${{ secrets.GCP_ADC_USER_JSON }}' > /tmp/adc.json

      - name: Extract Project ID from ADC
        run: |
          echo "PROJECT_ID=$(jq -r '.quota_project_id' /tmp/adc.json)" >> $GITHUB_ENV

      - name: Run Google Apps Script by gas-fakes
        run: |
          export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
          export GOOGLE_APPLICATION_CREDENTIALS=/tmp/adc.json
          npm run sample2
        env:
          GH_EVENT_NAME: "${{ github.event_name }}"
          GH_ACTOR: "${{ github.actor }}"
          GH_SHA: "${{ github.sha }}"
          GH_REF: "${{ github.ref_name }}"
          GH_COMMIT_MSG: "${{ github.event.issue.title || github.event.head_commit.message || github.event.pull_request.title || 'Manual Run' }}"
          GH_RUN_URL: "${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          GH_REPO: "${{ github.repository }}"
          GH_RUN_NUMBER: "${{ github.run_number }}"
          GH_ISSUE_NUMBER: "${{ github.event.issue.number || '' }}"
          GH_ISSUE_ACTION: "${{ github.event.action || '' }}"
          GH_ISSUE_URL: "${{ github.event.issue.html_url || '' }}"

Next, create a new directory named sources and add the corresponding Google Apps Script file as sources/sample2.js. This script reads the environment variables passed by GitHub Actions and appends them to the spreadsheet.

In order to use gas-fakes in a cache, import "@mcpher/gas-fakes" was used in the script.

import "@mcpher/gas-fakes";

/**
 * Log GitHub Actions execution details to Google Sheets
 * Updated to include Issue details
 */
function logExecution() {
  const data = {
    timestamp: new Date().toLocaleString("ja-JP", { timeZone: "Asia/Tokyo" }),
    event: process.env.GH_EVENT_NAME,
    action: process.env.GH_ISSUE_ACTION,
    issueNumber: process.env.GH_ISSUE_NUMBER,
    actor: process.env.GH_ACTOR,
    repo: process.env.GH_REPO,
    branch: process.env.GH_REF,
    runNumber: process.env.GH_RUN_NUMBER,
    message: process.env.GH_COMMIT_MSG,
    sha: process.env.GH_SHA,
    url: process.env.GH_RUN_URL,
    issueUrl: process.env.GH_ISSUE_URL,
  };

  const values = [
    [
      data.timestamp,
      data.event,
      data.action,
      data.issueNumber,
      data.actor,
      data.message,
      data.repo,
      data.branch,
      data.runNumber,
      data.sha,
      data.url,
      data.issueUrl,
    ],
  ];

  const headers = [
    "Timestamp",
    "Event",
    "Action",
    "Issue #",
    "User",
    "Message/Title",
    "Repository",
    "Branch",
    "Run #",
    "Commit SHA",
    "Workflow URL",
    "Issue URL",
  ];

  const spreadsheet_name = "sample spreadsheet for gas-fakes sample";
  const sheetName = "log";
  const files = DriveApp.getFilesByName(spreadsheet_name);
  const ss = files.hasNext()
    ? SpreadsheetApp.openById(files.next().getId())
    : SpreadsheetApp.create(spreadsheet_name);
  let sheet = ss.getSheetByName(sheetName) || ss.insertSheet(sheetName);

  if (sheet.getDataRange().getValues().length <= 1) {
    sheet.getRange(1, 1, 2, headers.length).setValues([headers, ...values]);
  } else {
    sheet
      .getRange(sheet.getLastRow() + 1, 1, values.length, values[0].length)
      .setValues(values);
  }

  console.log(
    `Log updated for ${data.repo} (Event: ${data.event}, Run #${data.runNumber})`,
  );
}

logExecution();

Case 2: Sync Repository Diffs to Google Drive

This workflow dynamically generates a .patch file containing code differences (or issue content) based on the triggered event, saving the result directly into a Google Drive folder named GitHub Sync - Repo Diffs.

Create .github/workflows/sample3.yml:

name: Run GAS via gas-fakes (sample3)

on:
  push:
    branches: ["*"]
  pull_request:
    branches: ["*"]
  issues:
    types: [opened, edited, closed]
  workflow_dispatch:

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
  sync-to-drive:
    name: sample3
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Setup Node.js Environment
        uses: actions/setup-node@v4
        with:
          node-version: "24"
          cache: "npm"

      - name: Install dependencies
        run: npm install

      - name: Configure Google Cloud Credentials
        run: |
          echo '${{ secrets.GCP_ADC_USER_JSON }}' > /tmp/adc.json

      - name: Extract Project ID from ADC
        run: |
          echo "PROJECT_ID=$(jq -r '.quota_project_id' /tmp/adc.json)" >> $GITHUB_ENV

      - name: Run Google Apps Script by gas-fakes
        run: |
          if [ "${{ github.event_name }}" == "pull_request" ]; then
            REPO_DIFF=$(git diff origin/${{ github.base_ref }}...HEAD | base64 -w 0)
          elif [ "${{ github.event_name }}" == "push" ] && [ "${{ github.event.before }}" != "0000000000000000000000000000000000000000" ]; then
            REPO_DIFF=$(git diff ${{ github.event.before }}..${{ github.sha }} | base64 -w 0)
          elif [ "${{ github.event_name }}" == "issues" ]; then
            ISSUE_CONTENT="Issue Event: ${{ github.event.action }}\nTitle: ${{ github.event.issue.title }}\n\n${{ github.event.issue.body }}"
            REPO_DIFF=$(echo -e "$ISSUE_CONTENT" | base64 -w 0)
          else
            REPO_DIFF=$(echo "Manual trigger: No diff." | base64 -w 0)
          fi

          export REPO_DIFF
          export GOOGLE_CLOUD_PROJECT=$PROJECT_ID
          export GOOGLE_APPLICATION_CREDENTIALS=/tmp/adc.json

          npm run sample3

Create the corresponding script at sources/sample3.js:

import "@mcpher/gas-fakes";

/**
 * Syncs the repository-wide diff to a text file in Google Drive.
 */
function syncRepoDiff() {
  const base64Diff = process.env.REPO_DIFF;

  if (!base64Diff) {
    console.warn("No diff content found in environment variable REPO_DIFF.");
    return;
  }

  const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
  const eventName = process.env.GITHUB_EVENT_NAME || "manual";
  const filename = `diff_${eventName}_${timestamp}.patch`;
  const folderName = "GitHub Sync - Repo Diffs";

  try {
    const decodedBytes = Utilities.base64Decode(base64Diff);
    const blob = Utilities.newBlob(decodedBytes, "text/plain", filename);

    const folders = DriveApp.getFoldersByName(folderName);
    const folder = folders.hasNext()
      ? folders.next()
      : DriveApp.createFolder(folderName);

    const file = folder.createFile(blob);

    console.log(`Successfully synced repository diff.`);
    console.log(`Saved as: ${filename}`);
    console.log(`View File: ${file.getUrl()}`);
  } catch (error) {
    console.error(`Error during Drive sync: ${error.message}`);
    process.exit(1);
  }
}

syncRepoDiff();

Execution and Verification

When a "push" event is triggered on the repository, the configured workflows execute concurrently. The visual output below confirms that GitHub Actions handled the integration flawlessly.

Executing the sample2 workflow processes the event payload and successfully appends a structured log directly into our Google Spreadsheet, functioning perfectly as an automated audit trail.

Executing the sample3 workflow correctly calculates the Git diff and uploads it to the designated Google Drive folder as a standard .patch file. Below is an example of the resulting text file contents generated in Google Drive:

diff --git a/README.md b/README.md
index d63c7d8..19f6f9d 100644
--- a/README.md
+++ b/README.md
@@ -246,3 +246,4 @@ jobs:

sample
sample
+   sample text

These results clearly demonstrate that Google Workspace services can be seamlessly managed and extended utilizing Google Apps Script and gas-fakes within a GitHub Actions CI/CD environment.

Exploring Further Applications

The integration of Google Apps Script and GitHub Actions via gas-fakes is not limited to logging and file syncing. This foundation unlocks numerous advanced automation possibilities for enterprise environments:

Automated Unit Testing
Traditionally, testing Google Apps Script code is a manual and tedious process. By utilizing gas-fakes, you can integrate standard JavaScript testing frameworks like Jest or Mocha. GitHub Actions can automatically run these test suites against your GAS functions on every pull request, ensuring robust code quality and preventing regressions before deployment.

Dynamic Document Generation
You can trigger Google Workspace document creation based on repository events. For instance, when a new GitHub Release is published, a workflow can use Google Docs or Google Slides services via gas-fakes to automatically compile release notes, insert relevant code snippets, and generate presentation slides for stakeholders.

Workspace Infrastructure as Code (IaC)
By storing organizational configurations—such as user directory structures, group memberships, or shared drive permissions—as YAML or JSON files in your repository, you can manage Google Workspace like infrastructure. Upon merging changes to the main branch, a workflow can execute a Google Apps Script that interfaces with the Admin Directory API to automatically synchronize the real-world Workspace environment with your repository's state.

Discussion: Evaluating the CI/CD Architecture

Integrating gas-fakes into your deployment pipeline shifts the paradigm of Google Workspace development. However, to maximize its potential, developers must weigh several technical considerations.

gas-fakes vs. Traditional clasp Workflows
Traditionally, developers rely on Google's clasp tool to synchronize local code with the Apps Script server. While effective for deployment, clasp cannot natively execute code locally. Testing requires pushing to Google’s servers and executing manually or via triggers. In contrast, gas-fakes provides a robust Node.js emulation layer. This enables instant execution, seamless integration with standard testing frameworks, and automated triggers directly from GitHub Actions without maintaining intermediate Web Apps.

The Strategic Importance of CI/CD in Workspace Development
Implementing CI/CD for Google Workspace is a major leap in enterprise security and maintainability. By shifting execution into GitHub Actions, sensitive credentials are removed from hardcoded scripts and securely managed via GitHub Secrets. Furthermore, every automation execution is firmly tied to a specific Git commit and workflow run, ensuring an immutable, highly auditable trail of operations that is essential for modern development standards.

Note

In this article, we focused on using Application Default Credentials (ADC) for gas-fakes authorization because of its straightforward setup for individual developers.

For more advanced or enterprise-scale implementations, consider the following alternatives and best practices:

Domain-Wide Delegation (DWD): For organizational workflows, gas-fakes supports Service Accounts with Domain-Wide Delegation. This allows automation to perform actions on behalf of specific users (impersonation) within a Google Workspace domain without relying on personal refresh tokens. You can find instructions on using this GitHub Action with a service account in Bruce's repository.
Workflow Optimization: When using actions/setup-node with cache: "npm", ensure your package-lock.json is committed to the repository root. If your project structure is nested, specify the cache-dependency-path to prevent "lock file not found" errors during CI/CD runs.
Security Best Practices: While these samples use a temporary file (/tmp/adc.json) for authentication, always ensure that sensitive credential files are never uploaded as artifacts or printed in workflow logs.

Summary

Integrates Google Apps Script into modern GitHub CI/CD pipelines using the gas-fakes library.
Enables local execution of GAS code without the need for constant Web App deployments.
Securely manages authentication using Google Application Default Credentials (ADC) and GitHub Secrets.
Demonstrates practical automation cases including automated logging and repository-to-Drive synchronization.
Provides a foundation for advanced unit testing and Infrastructure as Code (IaC) within Google Workspace.

Recursive Knowledge Crystallization: A Framework for Persistent Autonomous Agent Self-Evolution

Tanaike — Sat, 21 Feb 2026 07:37:04 +0000

Abstract

In the development of autonomous agents using Large Language Models (LLMs), restrictions such as context window limits and session fragmentation pose significant barriers to the long-term accumulation of knowledge. This study proposes a "self-evolving framework" where an agent continuously records and refines its operational guidelines and technical knowledge—referred to as its SKILL—directly onto a local filesystem in a universally readable format (Markdown). By conducting experiments across two distinct environments featuring opaque constraints and complex legacy server rules using Google's Antigravity and Gemini CLI, we demonstrate the efficacy of this framework. Our findings reveal that the agent effectively evolves its SKILL through iterative cycles of trial and error, ultimately saturating its learning. Furthermore, by transferring this evolved SKILL to a completely clean environment, we verify that the agent can successfully implement complete, flawless client applications in a single attempt (zero-shot generation). This methodology not only circumvents the limitations of short-term memory dependency but also pioneers a new paradigm for cross-environment knowledge portability and automated system analysis.

The infographic of this article is as follows.

1. Introduction

One of the primary challenges in the deployment of autonomous AI agents is the persistence of learning. Traditionally, when an agent's execution environment is reset or its context window is cleared, it is forced to relearn task specifications from scratch.

In the realm of autonomous agents, enabling long-term memory and self-correction has been a focal point of recent research. Notable frameworks such as Reflexion (Shinn et al., 2023) endow agents with dynamic memory to self-reflect and refine reasoning through trial and error. Similarly, Voyager (Wang et al., 2023) introduces an open-ended embodied agent in Minecraft that utilizes an ever-growing executable code skill library for lifelong learning. Another significant approach is MemGPT (Packer et al., 2023), which treats LLMs as operating systems, employing hierarchical memory management to bypass context window limitations.

However, these existing methodologies predominantly rely on in-memory contexts, specialized vector databases, or internal virtual memory abstractions. This makes the acquired knowledge difficult to decouple from the specific agent instance and challenging for human developers to read, audit, or directly manage.

In contrast, our proposed framework introduces a paradigm shift: the continuous self-rewriting of an agent's "SKILL" residing entirely on a local filesystem (SKILL.md). By utilizing standard development toolchains (Antigravity and Gemini CLI), the agent investigates unknown environments and automatically maintains its own operational manual. This approach offers a distinct advantage—the physical persistence of knowledge in a universally readable Markdown format. It enables not only continuous learning but also "Zero-Shot Knowledge Transfer." We empirically prove that once the SKILL evolves and saturates in one environment (Antigravity), it can be loaded into a completely clean environment (Gemini CLI) to synthesize complex code perfectly on the first attempt without any trial and error.

2. Experimental Procedure

In this framework, SKILL refers to Agent Skill, a standardized set of executable capabilities and knowledge markers that define an agent's operational boundaries. As defined by the Agent Skill community (https://agentskills.io/home), these skills allow for modular, portable, and verifiable agentic functions. Our framework treats the SKILL.md file as a living repository of these Agent Skills.

To demonstrate the continuous evolution of the SKILL and its application, we designed two distinct experiments. In both cases, Antigravity was utilized for the iterative evolution of the SKILL, followed by a demonstration using the Gemini CLI for zero-shot script completion.

2.1. Experiment 1: The "Silent Bureaucrat" Blind Incremental Evolution

Server Characteristics: The server enforces a highly restrictive, black-box validation process consisting of 20 sequential rules. Crucially, it possesses a hidden tolerance limit (5 errors per session). Once this limit is reached, it returns an absolute block (Limit reached.) and becomes completely silent—it provides no further hints, and neither logs nor returns the Session ID, enforcing "Absolute Silence."
Client Goal: The agent must write a Node.js script (client.js) that successfully satisfies all 20 validation rules in a single POST request to /api/submit to retrieve the hidden flag: "FLAG{INCREMENTAL_EVOLUTION_COMPLETE}". The agent is strictly prohibited from changing its Session ID during a single cycle to bypass the block.

Workflow

Start the Server.
Launch the Antigravity agent.
Execute the prompt to develop the Client script.
The AI agent updates the SKILL based on failures or newly discovered rules.
The Client script is reset to its initial blank state (Tabula Rasa). Keeping the exact same prompt, steps 3 and 4 are looped. When the agent hits the "Limit reached" block, it is forced to terminate the cycle, but its SKILL persists. We performed 10 cycles until the evolution of the SKILL was saturated and success was achieved.
The fully evolved SKILL is transferred to a clean environment. Using the Gemini CLI, we confirm that the Client script is completed perfectly in a single prompt (zero-shot).

Mermaid Chart Playground

2.2. Experiment 2: Chaos Server Constraints & Architectural Pattern Acquisition

Server Characteristics: This server mimics a deeply flawed legacy API environment ("Chaos Server"). It contains implicit rules, semantic riddles (e.g., requiring the reverse string of 'nimda', or the Base64 encoding of the word 'alpha'), and state-dependent limitations. If the agent makes too many requests within a timeframe (cumulative limit of 8), a "Session Block" occurs, necessitating the dynamic generation of unique identifiers to bypass.
Client Goal: The agent must develop a comprehensive, object-oriented SDK (client-app.js) capable of interacting with 5 distinct endpoints (connection check, user creation, secure data retrieval, config update, and system audit) and performing a stress test, overcoming all chaos rules programmatically.

Workflow

Start the Server.
Launch the Antigravity agent.
Execute the prompt to develop specific features of the Client script.
The AI agent updates the SKILL, documenting both the discovered constraints and higher-level architectural implementation guidelines.
The Client script is not reset. Instead, the prompt is progressively changed in each cycle to command the development of new features, building upon the existing script. This process continues until the planned evolution of the application is complete (5 cycles).
The fully evolved SKILL is transferred to a clean environment. Using the Gemini CLI, the client-app.js is reset to a blank state, and a single, comprehensive prompt is given to build the entire SDK. We confirm that the complete application is generated flawlessly on the first attempt (zero-shot).

Mermaid Chart Playground

3. Results and Discussions

3.1. Experiment 1 Results & Discussion

Table 1: Experiment 1 Data Summary

Cycle	Success	Mod. Count	Interaction Count	Skill Size (Bytes)	State
1	False	5	5	2666	Exploration (Fail)
2	False	6	6	2963	Exploration (Fail)
3	False	3	4	2963	Exploration (Fail)
4	False	4	5	3474	Exploration (Fail)
5	True	3	3	3654	Breakthrough
6	True	1	1	3654	Convergence
7	True	2	2	3654	Stable
8	True	2	2	3728	Stable
9	True	1	1	3728	Full Convergence
10	True	1	1	3728	Full Convergence

Figure 1: The inverse relationship between trial-and-error reduction and knowledge accumulation for Experiment 1

Zero-Shot Verification: Utilizing the completely evolved SKILL from cycle 10, the Gemini CLI successfully generated the functional client code on the very first attempt.

Figure 2: Zero-shot script completion in Gemini CLI using the evolved SKILL from Experiment 1.

Discussion:

In Experiment 1, the agent operated under a severe "blind" constraint. During cycles 1 through 4, the agent repeatedly hit the hidden error limit and was forcefully blocked. In traditional LLM agent execution, resetting the script here would mean starting from zero. However, because the agent accurately recorded the fragments of rules it discovered into SKILL.md before "dying" in each cycle, the subsequent generations inherited this knowledge. Cycle 5 represents the critical threshold where the accumulated knowledge was sufficient to bypass all 20 rules without hitting the error limit. The convergence to a modification count of 1 in later cycles, and the successful zero-shot execution in Gemini CLI, definitively prove that the agent effectively offloaded its working memory to the local filesystem, rendering the task independent of the model's immediate context window.

3.2. Experiment 2 Results & Discussion

Table 2: Experiment 2 Data Summary

Cycle	Success	Mod. Count	Interaction Count	Skill Size (Bytes)	Learning Content
1	True	1	2	2013	Identity, Content-Type identification
2	True	3	4	2407	Secure/Admin constraints (Riddles)
3	True	2	1	2634	Audit (Base64 signature)
4	True	1	0	2634	Avoid Session Block
5	True	2	0	2957	Refactoring & Guidelines

Figure 3: The learning curve for Experiment 2

Zero-Shot Verification: Utilizing the evolved SKILL from cycle 5, the Gemini CLI successfully built the entire, complex SDK from a blank file in a single pass without prior context.

Figure 4: Zero-shot script completion in Gemini CLI using the evolved SKILL from Experiment 2.

Discussion:

While Experiment 1 showcased constraint discovery, Experiment 2 highlighted the agent's capability for architectural self-organization. The server presented not just rigid rules, but semantic puzzles (e.g., reversing strings, encoding to Base64). The agent successfully decoded these and recorded the solutions. More importantly, when faced with the "Session Block" error in Cycle 4, the agent realized that static headers were insufficient. By Cycle 5, the agent did not just fix the error; it abstracted the solution into a "Centralized Header Factory" pattern. This transition from reactive error-fixing to proactive software architecture design is clearly reflected in the drop of interaction counts to 0 in later cycles. The zero-shot success in Gemini CLI demonstrates that the agent can extract best practices from messy legacy systems and output clean, robust SDKs instantly.

3.3. Analysis of SKILL.md Evolution Before and After

Analyzing the physical changes in the SKILL.md files provides deep insight into the agent's cognitive process. For the full, unredacted text of the SKILL.md files and client scripts before and after evolution for both experiments, please refer to Appendix A and Appendix B.

Experiment 1 (Silent Bureaucrat)

Before: The "Learned Server Specifications" section was entirely empty, simply stating - Status: Unknown.
After: The file grew to include a meticulously numbered list of 16 highly specific rules. Crucially, these rules were not just copied error messages. For example, the agent codified the requirement into executable logic: "- Rule 11: The header X-Anti-Robot must be set to Math.floor(timestamp / 1000)." and "- Rule 15: The header X-Final-Signature must be set to the SHA256 hash of the request_id string." This demonstrates the agent's ability to translate abstract failures into actionable programmatic directives.

Experiment 2 (Chaos Server)

Before: The sections for "Known Constraints & Error Codes" and "Method Implementation Guidelines" were empty placeholders.
After: The "Constraints" section contained the decoded solutions to the server's riddles (e.g., X-Audit-Signature as Base64 of 'alpha'). The most profound evolution occurred in the "Guidelines" section. The agent autonomously authored a comprehensive design document advocating for a "Centralized Header Factory", detailing how it should handle identity, dynamic session persistence, content negotiation, and endpoint specialization. The agent elevated its learning from "How to bypass an error" to "How to architect a resilient application."

3.4. Comprehensive Discussion on Significance and Novelty

The synthesis of these two experiments reveals a highly potent framework for AI-driven software engineering. The traditional dependency on a single continuous context window is fundamentally fragile; when the session ends, the learning dies (Catastrophic forgetting).

By enforcing the physical writing of knowledge to a Markdown file (SKILL.md), we achieved persistent meta-learning. The significance of using Markdown over specialized vector databases is twofold:

Human Readability and Auditability: Developers can read, review, and manually correct the SKILL.md file, fostering a true Human-AI collaborative environment.
Cross-Platform Portability (Zero-Shot Knowledge Transfer): As demonstrated by successfully moving the evolved SKILL from Antigravity to Gemini CLI, knowledge is no longer locked into a specific agent instance. An agent can spend days investigating a system, and the resulting SKILL can be instantly deployed to a fleet of worker agents, granting them immediate "senior-level" expertise without any required training or trial-and-error phases.

4. Specific Applications Utilizing This Approach

Based on our findings, this framework can be highly impactful in the following real-world scenarios:

Automated Reverse Engineering & SDK Generation: When integrating with undocumented or chaotic legacy API systems, an agent can be deployed to blindly probe the endpoints. It will autonomously decode the hidden rules, generating both a human-readable API specification (the SKILL) and robust client SDKs.
Organizational Tacit Knowledge Documentation: In many organizations, "tribal knowledge" dictates how to deploy or test specific systems (e.g., "always wait 5 seconds before hitting this endpoint"). By having an agent execute tasks and fail, it can discover and formalize this tacit knowledge into universally accessible Markdown files, acting as an automated technical writer.
Robust E2E Automated Test Suites: UI and API specifications change frequently, breaking tests. An agent equipped with this framework can dynamically update testing protocols in its SKILL as it encounters new failures, acting as a self-healing testing mechanism that minimizes maintenance overhead.
AI Onboarding and Scaling: A mature SKILL file cultivated by an exploratory agent can be instantly copied to the local workspaces of newly deployed AI agents (or human engineers). This instantly transfers "experience," allowing for rapid scaling of development resources.

5. Strategies for Agent Skill Evolution

To ensure the continuous enhancement of Agent Skills within this framework, we identify two primary evolutionary paths:

Targeted Skill Evolution: When the goal is to refine a specific capability, the agent is instructed via an Appendix in the SKILL.md file. Upon successful problem resolution, the agent triggers a targeted update—adding, deleting, or modifying entries—to that specific skill definition.
Holistic Skill Evolution: To evolve the agent's entire skill set simultaneously, evolution instructions are embedded directly into global context files (e.g., GEMINI.md). This compels the agent to evaluate and update the relevant SKILL.md files immediately after any successful task execution across its entire operational spectrum.

6. Summary

Physical Knowledge Persistence: By enforcing the continuous rewriting of a universally readable Markdown SKILL file, agents effectively overcome the limitations and volatility of in-memory LLM context windows.
Mastery of Opaque Constraints: Agents proved highly capable of discovering and permanently adapting to hidden server limits, cryptographic requirements, and semantic riddles through systematic trial and error.
Architectural Abstraction: Beyond merely fixing localized errors, the agents demonstrated the capacity to synthesize overarching design patterns (e.g., Centralized Header Factories) and document them as future guidelines.
Zero-Shot Knowledge Transfer: A SKILL evolved in one execution environment (Antigravity) can be seamlessly imported into a completely clean, distinct environment (Gemini CLI) to generate flawless, complex applications on the very first prompt.
Human-AI Collaborative Paradigm: Because the agent's memory resides in a standard file system, human developers maintain full visibility and control, able to read, audit, and augment the agent's logic at any time.

7. Appendix

The sample scripts, SKILL.md, and prompts can be seen at https://gist.github.com/tanaikech/966f83cc438b6077b05b9843be09e930.

Building Adaptive Learning Agents with A2UI, Gemini, and Google Apps Script

Tanaike — Sat, 07 Feb 2026 02:26:26 +0000

Abstract

This article demonstrates how to build an adaptive learning agent using Agent-to-User Interface (A2UI), Gemini, and Google Apps Script. We explore a system that generates personalized quizzes, tracks performance in Google Sheets, and dynamically adjusts difficulty to maximize learning efficiency within the Google Workspace ecosystem.

Introduction

A2UI (Agent-to-User Interface) represents a paradigm shift in how users interact with generative AI. Originally open-sourced by Google and implemented in TypeScript and Python Ref, A2UI becomes even more powerful when integrated with Google Apps Script (GAS). This combination enables seamless access to the Google Workspace ecosystem, transforming static documents into intelligent, agentic applications.

To explore this potential, I have previously published several articles detailing the technical foundations:

Building upon the foundation laid in those publications, this article takes a step forward by introducing an educational support framework powered by A2UI and Google Apps Script. In this system, the AI does not simply answer questions; it acts as an active tutor.

For example, when a user provides a prompt such as I want to study Google Apps Script, Gemini generates specialized questions on the backend. A2UI then renders these as an interactive quiz on the frontend. Crucially, the system utilizes Google Sheets as a persistent memory store. By analyzing historical performance data, the agent generates increasingly challenging content for subsequent sessions, facilitating a personalized and effective learning progression.

The Adaptive Learning Engine

The core value of this application lies in its ability to improve learning efficiency through a "Feedback-Loop Architecture." Unlike static quiz apps, this agent utilizes Google Sheets as a persistent memory store to track cognitive growth.

Workflow and Architecture

1. Goal Definition: The user opens the sidebar and sets a learning target (e.g., "Master Google Apps Script").
2. Context Retrieval: The system scans the active Spreadsheet for past performance data. It identifies previously answered questions, success rates, and specific topic weaknesses (e.g., "Batch Operations").
3. Generative Logic (Gemini): Using the context, Gemini generates a structured JSON response containing new, targeted questions and the specific UI components (radio buttons, code blocks) required to render them.
4. Dynamic Rendering (A2UI): The frontend constructs the interface instantly. No hard-coded HTML is required.
5. Immediate Feedback & Persistence: As the user interacts, results are validated in real-time and immediately logged back to the Spreadsheet, refining the dataset for the next session.

The detailed workflow operates as follows:

Mermaid Chart Playground

In the official sample script for A2UI (Restaurant finder), the client communicates with the server via A2A (Agent2Agent) protocols. However, in this article, we optimize the architecture for GAS. To reduce the overhead of HTTP requests associated with A2A communication, the client (HTML) communicates directly with the AI agent built on Google Apps Script using google.script.run.

Demonstration: The AI Tutor in Action

The video demonstration highlights two distinct capabilities: Deep Learning Support and General Versatility. This demonstration utilizes a dialog within Google Sheets to highlight the integration with Google Apps Script. However, this application can easily be deployed as a standalone Web App. By deploying the project as a Web App, the doGet function captures the request, allowing the interface to function independently of the spreadsheet UI.

1. Maximizing Learning Efficiency

In the first segment, the user prompts: Create a quiz about Google Apps Script basics. Especially, I want to manage Google Sheets using Google Apps Script.

Targeted Question Generation: The AI generates technical questions ranging from basic range selection (sheet.getRange()) to advanced data handling (sheet.getValues()).
Active Recall: The system presents a challenge question on "Batch Operations" (SpreadsheetApp.flush()) to test the user's depth of knowledge.
Comprehensive Performance Analysis: The standout feature appears. A2UI renders a "Performance Analysis" dashboard.
Strengths Identified: It acknowledges mastery in "Range & Data Manipulation."
Weakness Assessment: It confirms no current weaknesses were detected in this session.
Strategic Next Steps: It suggests moving on to "Custom Menus" or "Simple Triggers," effectively guiding the user's curriculum path.
Note: Upon completion of the initial quiz, using the same prompt triggers a new session where questions are generated based on the refined historical data.

The past data is stored in Google Sheets as follows.

2. Versatility Verification: Restaurant Finder

To prove the system's flexibility, we switch contexts entirely without changing code.

Prompt: Find 3 Chinese restaurants in New York.
Multimodal UI: The agent renders rich cards with images for "Han Dynasty" and "RedFarm."
Complex Action Handling: The user clicks "Book Now," triggering a multi-field form (Party Size, Date, Dietary Requirements).
Significance: This demonstrates that the A2UI protocol on GAS can handle complex transactional flows just as easily as educational logic.

Repository

The full source code and sample implementation are available here:
https://github.com/tanaikech/A2UI-for-Google-Apps-Script/tree/master/samples/A2UI-Lerning-Agent

Application Setup Guide

To deploy this adaptive learning agent in your environment:

1. Obtain an API Key
You must have a valid Gemini API Key. Get one here.

2. Copy the Sample Script
Copy the pre-configured Spreadsheet containing the A2UI engine: https://docs.google.com/spreadsheets/d/1eckORqs3JtTIJZTB0I5VpqduZw9g3-mM764s4neG7Fo/copy

3. Configure the Script
Open the script editor (Extensions > Apps Script), open main.gs, and paste your API key into the apiKey variable. Finally, save the script and reload the Spreadsheet.

Important Note

This project serves as a foundational methodology for building Agentic UIs. When implementing this in a production environment, ensure the scripts are modified to meet your specific security requirements and workflow constraints.

Users can also study multiple subjects concurrently. When switching topics, Gemini generates new questions by analyzing the historical data trends specific to that context, allowing for simultaneous progress across different fields.

Summary

Adaptive Learning Loop: The system leverages Google Sheets to store user history, allowing Gemini to tailor future questions based on identified strengths and weaknesses.
Dynamic UI Generation: A2UI eliminates the need for static HTML templates, allowing the AI to generate quizzes, charts, and booking forms on-the-fly based on context.
Detailed Performance Analytics: The agent provides qualitative feedback, not just scores, offering specific "Next Steps" to guide the user's learning path efficiently.
Cross-Domain Versatility: The demonstration proves the architecture is agnostic; it handles educational code quizzes and restaurant booking transactions with equal fluency.
Seamless Workspace Integration: By combining GAS and Gemini, we transform standard Google Sheets into intelligent, persistent databases that drive agentic behavior.

Beyond Chatbots: Building Task-Driven Agentic Interfaces in Google Workspace with A2UI and Gemini

Tanaike — Tue, 03 Feb 2026 05:07:07 +0000

Abstract

This article explores A2UI (Agent-to-User Interface) using Google Apps Script and Gemini. By generating dynamic HTML via structured JSON, Gemini transforms Workspace into an "Agent Hub." This recursive UI loop enables complex workflows where the AI builds the specific functional tools required to execute tasks directly.

Introduction: The Evolution of AI Interaction

The Official A2UI framework by Google marks a significant paradigm shift in how we interact with artificial intelligence. Short for Agent-to-User Interface, A2UI represents the evolution of Large Language Models (LLMs) from passive chatbots into active agents capable of designing their own functional interfaces. Building upon my previous research, A2UI for Google Apps Script and Bringing A2UI to Google Workspace with Gemini, I have refined this integration to support sophisticated, stateful workflows.

To appreciate the impact of A2UI, we must recognize the limitations of "Chat-centric" AI. In traditional chat interfaces, users must manually bridge the gap between an AI's advice and their actual files—a process often involving tedious context switching. By implementing A2UI within Google Apps Script (GAS), we leverage a unique "Home-Field Advantage." Because GAS is native to the Google ecosystem, it possesses high-affinity access to the Drive API and Spreadsheet services, allowing the AI to act directly on your data.

Core Architecture: The Generative UI Loop

In this system, Gemini functions as both the Agent and the UI Architect. When a user submits a natural language prompt, the Agent evaluates the intent and generates a specific HTML interface—such as a file selector, a metadata card, or a live text editor.

Crucially, this implementation utilizes Recursive UI Logic. When a user interacts with a generated component (e.g., clicking an "OK" button), that action is transmitted back to the Agent as a "System Event." This event contains the conversation history and the new data context. This allows the Agent to "see" the current state of the task and generate the next logical interface, creating a seamless, multi-step agentic workflow.

Workflow Visualization

This diagram illustrates how the system maintains state and generates interfaces recursively using "System Events."

Mermaid Chart Playground

Repository

The full source code and sample implementation can be found here:
https://github.com/tanaikech/A2UI-for-Google-Apps-Script

Application Setup Guide

To deploy this application in your own environment, please follow these steps:

1. Obtain an API Key
You will need a valid Gemini API Key to communicate with the LLM.
Get one here.

2. Copy the Sample Script
You can copy the Google Spreadsheet containing the pre-configured Google Apps Script using the link below:
https://docs.google.com/spreadsheets/d/1UB5j-ySSBBsGJjSaKWpBPRYkokl7UtgYhDxqmYW00Vc/copy

3. Configure the Script

Open the script editor (Extensions > Apps Script).
Locate the main.gs file.
Set your API key in the GEMINI_API_KEY variable.
Save the project.

Alternatively, visit the GitHub Repository to manually copy the source codes.

Demonstration: Productivity Meets Magic

The following video showcases how A2UI transforms a Google Sheet into an agentic command center. The system doesn't just talk; it guides the user through three distinct patterns of interaction.

Operational Patterns: Productivity in Action

The system transforms a standard Google Sheet into an agentic command center. It facilitates three distinct patterns of interaction:

Pattern 1: Intelligent Viewing

Sample prompt: Please list the files in the folder named 'sample'. I would like to select a file and view its content.

The user requests to see files in a specific folder. Gemini understands the intent, calls the Drive API to list the files, and generates a File Selector UI. Once the user selects files, the Agent fetches the content and renders it in a clean Content Viewer layout designed specifically for reading.

Pattern 2: Contextual Metadata Analysis

Sample prompt: Show me the files in the 'sample' folder. I need to select a file to check its metadata.

If a user asks for technical details, the UI adapts. The Agent generates a Metadata Viewer, displaying properties like File IDs, sizes, and creation dates. This showcases the agent hub's ability to pivot between task types by generating appropriate interfaces on the fly.

Pattern 3: Multi-Step "Verify and Edit"

Sample prompt: I want to edit a file in the 'sample' folder. Please let me select a file and check its content first. If it's the right one, I will edit and update it.

This demonstrates the power of stateful A2UI:

Selection Preview: The Agent provides a preview with radio buttons for content confirmation.
Dynamic Editor: Gemini generates an Editor UI containing the file’s text.
Real-Time Execution: The script executes modifications directly to Google Drive upon clicking "Update," completing the cycle from prompt to action.

Note: In this specific sample, only text files on Google Drive are eligible for editing.

Important Note

Summary

A2UI (Agent-to-User Interface) represents a paradigm shift where the Agent builds the functional UI components required for a task rather than just providing text.
The recursive task execution model uses "System Events" to track progress, allowing the interface to evolve dynamically based on real-time user actions.
Native Workspace integration via Google Apps Script provides secure, high-speed access to Drive and Sheets data without the need for external server management.
Zero-Tab efficiency is achieved by consolidating file discovery, analysis, and editing within a single, dynamic dialog box inside a spreadsheet.
This task-driven architecture proves the future of productivity lies in AI agents acting as architects, creating custom tools precisely when they are needed.

Smart Stowage: Building a 3D Cargo Digital Twin with Gemini 3

Tanaike — Wed, 21 Jan 2026 07:19:36 +0000

Abstract

This article details the development of Smart Stowage Optimizer, a web-based digital twin for logistics that bridges the gap between physical safety and artificial intelligence. By integrating Gemini 3 Pro, the system solves the 3D Bin Packing Problem (3DBPP) using advanced spatial reasoning. Built with React 19 and Three.js, the application visualizes physics-aware load stability in real-time, offering a comparative analysis between traditional heuristic algorithms and modern generative AI agents.

Introduction

The capabilities of Large Language Models (LLMs) are expanding at an unprecedented rate, moving from text generation to complex reasoning. When Gemini 2.5 was released, I conducted a feasibility study on automating cargo ship stowage planning, published in "Stowage Planning Automation Using Gemini: A Feasibility Study and A Prompt-Based Approach" Ref.

At that time, the implementation was a backend Python script producing static JSON results. While effective as a proof of concept, real-world logistics demands interactive visualization and immediate feedback on physical constraints like the Center of Gravity (COG).

With the arrival of Gemini 3, we can now handle significantly more complex spatial reasoning tasks. This article introduces the Smart Stowage Optimizer, a full-stack Web Application that evolves the previous concept into a live 3D Digital Twin. This application not only calculates optimal packing but also visualizes stability and safety constraints in a high-fidelity 3D environment.

Repository

You can access the full source code here:

https://github.com/tanaikech/Smart-Stowage-Optimizer

System Architecture

To tackle the 3D Bin Packing Problem (3DBPP)—a known NP-hard optimization challenge—I designed a dual-engine architecture. This allows users to compare the speed of deterministic algorithms against the semantic reasoning of modern AI.

Frontend: React 19, Tailwind CSS, Lucide React
Visualization: React Three Fiber (Three.js), InstancedMesh for performance
AI Logic: Google GenAI SDK (Gemini 3 Pro)
Algorithms: Custom greedy heuristic implementation

Below is the high-level data flow of the application. You can generate a similar diagram using the prompt below.

[Diagram Suggestion: System Architecture Flowchart]
Prompt for Diagram Generation: "Create a flowchart showing a React Frontend sending cargo data to two branches: one to a Local Heuristic Engine and one to the Gemini API. Both branches merge back into a Validation Layer which calculates Physics (COG), and finally outputs to a 3D Renderer."

Mermaid Chart Playground

Methodology: Dual-Engine Optimization

1. The Deterministic Approach: Algorithmic Engine

The first engine utilizes a Greedy Shelf-Packing Heuristic, specifically a variation of the First-Fit Decreasing Height (FFDH) algorithm.

Logic: It sorts cargo items by height to define "shelves" or layers.
Execution: Items are packed sequentially along the X and Z axes, filling one layer before moving to the next.
Pros/Cons: This method is computationally inexpensive and ensures a tidy lineup. However, it lacks "common sense"—it cannot understand complex constraints like "do not stack heavy machine parts on top of fragile electronics" unless explicitly hard-coded.

2. The Probabilistic Approach: Gemini 3 Pro Engine

The second engine leverages the Spatial Reasoning capabilities of Gemini 3 Pro. Instead of iterating through a fixed loop, the AI evaluates the entire manifest holistically.

Why Gemini 3?: Previous models struggled with 3D coordinate mapping. Gemini 3 Pro shows a marked improvement in maintaining spatial relationships, allowing it to "visualize" the container interior.
Workflow: The application prompts the model to act as a Senior Stowage Engineer.
Constraints: The prompt enforces non-linear rules:
- Stability: Keep the Center of Gravity (COG) low.
- Safety: Heavier items must be placed at y=0.
- Balance: Lateral and longitudinal distribution for truck axles.

Implementation: Structured JSON Output

To ensure the AI returns usable data, we utilize the responseMimeType: "application/json" configuration in the Google GenAI SDK. This forces the model to adhere to a strict schema, returning a typed array of coordinates rather than conversational text.

// services/geminiService.ts snippet
const response = await ai.models.generateContent({
  model: "gemini-3-pro-preview",
  contents: prompt,
  config: {
    responseMimeType: "application/json",
    responseSchema: {
      type: Type.OBJECT,
      properties: {
        packedItems: {
          type: Type.ARRAY,
          items: {
            type: Type.OBJECT,
            properties: {
              id: { type: Type.STRING },
              x: { type: Type.NUMBER },
              y: { type: Type.NUMBER },
              z: { type: Type.NUMBER },
            },
            required: ["id", "x", "y", "z"],
          },
        },
      },
    },
  },
});

Safety & Physics Validation

AI is probabilistic, but cargo safety must be deterministic. Therefore, the application includes a validation layer:

Boundary Clamping: If the AI suggests a coordinate where an item clips through the wall ($x + width > container_width$), the system automatically clamps the item to the boundary.
COG Calculation: The app calculates the weighted average position of all items ($COG = \frac{\sum (m_i \times p_i)}{\sum m_i}$) and renders a red visual marker in the 3D view. This allows engineers to verify stability instantly.

Application Overview: Smart Stowage Optimizer

Smart Stowage Optimizer acts as a sandbox to simulate loading risks before physical operations begin.

Key Features

Digital Twin Visualization: Using react-three-fiber, the scene renders a semi-transparent container with a grid floor. We use InstancedMesh for the cargo items, allowing the app to render hundreds of boxes with a single GPU draw call for high performance.
Physics-Aware Metrics: The UI displays real-time volumetric efficiency (%) and total payload weight, changing colors to warn of overloading.
Manifest Management: Users can upload CSV files, manually add items, or use industry-standard presets (20ft/40ft ISO containers, EURO Trucks).

Comparative Analysis

Feature	Algorithmic (Heuristic)	Gemini AI Engine
Speed	Instantaneous (<100ms)	3-8 seconds (Inference)
Logic	Deterministic (Fixed Rules)	Probabilistic (Reasoning)
Stability	Basic Height-based layers	Advanced COG awareness
Flexibility	Rigid packing patterns	Adapts to unique constraints
Best For	Uniform pallets, high speed	Complex manifests, fragile items

Installation and Usage

To run the application locally:

Clone the repository:

git clone https://github.com/tanaikech/Smart-Stowage-Optimizer

Install dependencies:

npm install

Configure API Key:

Set your Gemini API key as an environment variable GEMINI_API_KEY in a .env file.

Start the server:

npm run dev

Workflow

Define Space: Select a preset (e.g., "EURO_TRUCK") or define custom dimensions (W/H/L).
Build Manifest: Upload a CSV or use the "Sample" button to populate test cargo (generators, drums, electronics).
Select Engine: Choose Gemini AI for stability-focused packing or Algorithmic for speed.
Analyze: Rotate the 3D view. Check the red COG marker to ensure it is centered and low.
Export: Download the generated coordinates as a CSV report for the loading crew.

Testing and Demonstration

The following demonstration highlights the difference between the engines. Note how the Algorithmic engine packs tightly but may ignore weight distribution. In contrast, the Gemini engine intelligently places heavier items (blue/green generators) at the bottom and lighter items (orange electronics) on top to lower the Center of Gravity.

The exported CSV data generated by Gemini is structured as follows:

ID,Name,Width,Height,Length,Weight,X,Y,Z
BASE-1,Generator 1,1.2,1,2,2500,0,0,0
BASE-2,Generator 2,1.2,1,2,2500,0,0,2
PAL-1,Heavy Spares,1,0.8,1.2,1200,1.35,0,0
PAL-2,Heavy Spares,1,0.8,1.2,1200,1.35,0,1.2
BOX-A1,Electronics,0.6,0.6,0.8,150,0,1,0
BOX-A2,Electronics,0.6,0.6,0.8,150,0.6,1,0
...

Summary

By integrating Gemini 3 Pro, we have moved beyond simple script-based calculators to a fully interactive Digital Twin. While traditional algorithms are faster for uniform shapes, Gemini demonstrates a unique ability to understand "soft" constraints—such as stability and stackability—that are difficult to program explicitly. This hybrid approach represents the future of logistics software: combining the speed of heuristics with the reasoning of Artificial Intelligence.

Hybrid Architecture: Successfully combines deterministic Heuristics with probabilistic AI.
Gemini 3 Capability: Confirms that Gemini 3 Pro handles complex spatial reasoning and 3D coordinate mapping significantly better than previous iterations.
Visualization Impact: React 19 and Three.js transform abstract data into visual insights, allowing for immediate safety verification.
Physics Integration: Real-time Center of Gravity (COG) calculations ensure that AI-generated plans adhere to physical safety standards.

Bringing A2UI to Google Workspace with Gemini

Tanaike — Mon, 19 Jan 2026 05:54:51 +0000

Abstract

This article explores implementing the Agent-to-User Interface (A2UI) protocol within Google Apps Script. It demonstrates utilizing Gemini's structured output to render secure, dynamic, server-driven UIs—like booking forms and event lists—directly inside Google Sheets, streamlining workflows without complex external infrastructure.

Introduction

I recently published a sample implementation demonstrating how to bring the Agent-to-User Interface (A2UI) concepts to Google Apps Script (GAS). Ref

A2UI is an emerging open-standard protocol designed to enable AI agents to generate rich, interactive user interfaces that render natively across web, mobile, and desktop environments. Ref Unlike traditional approaches that often require executing arbitrary, high-risk code to generate UI on the fly, A2UI leverages a strict schema-based data format to describe UI components. This "secure-by-design" architecture effectively mitigates security risks like Cross-Site Scripting (XSS) while ensuring high performance and cross-platform consistency.

Integrating A2UI into the Google Workspace ecosystem represents a paradigm shift in user experience. It allows Large Language Model (LLM) driven agents to evolve beyond simple text-based chat. Instead, they provide dynamic, actionable components—such as forms, interactive charts, and data grids—directly within the user's workflow. In this article, I present a demonstration of A2UI functioning within Google Sheets, illustrating how AI agents can orchestrate complex, data-driven tasks through a native, structured interface.

Repository

The complete source code and documentation are available in the GitHub repository below:

https://github.com/tanaikech/A2UI-for-Google-Apps-Script

System Architecture and Workflow

Mermaid Chart Playground

The implementation of A2UI within Google Sheets follows a highly optimized lifecycle to ensure a smooth, agent-driven user experience.

User Input: The process begins in the Google Spreadsheet dialog where a user enters a natural language request, such as "Find 3 Chinese restaurants in New York."
Request Transmission: The HTML interface captures this input and sends it to the GAS backend. This is handled via the google.script.run API, which creates a direct and secure bridge between the user interface and the server logic.
Intent Routing: The GAS backend forwards the request to the Gemini API. Using a specialized System Prompt, Gemini acts as a "Router" to determine which sub-application (e.g., Restaurant Finder or Event Manager) is best suited to handle the request.
Tool Execution: Once the sub-application is selected, GAS executes local functions to interact with your data. This may involve searching the current spreadsheet, fetching files from Google Drive, or checking Google Calendar availability.
A2UI JSON Generation: The data retrieved from the tools is sent back to Gemini. Gemini then generates a structured response that includes both conversational text and a JSON object strictly following the A2UI (Agent-to-User Interface) schema.
Client-Side Rendering: The GAS backend returns this payload to the HTML dialog. A dedicated JavaScript rendering engine within the dialog parses the A2UI JSON and dynamically builds high-quality UI components like interactive cards, lists with images, and booking forms.
Native Integration: Unlike standard A2UI implementations that often rely on the A2A (Agent-to-Agent) protocol over HTTP, this GAS-optimized architecture eliminates external network overhead. By using the internal Google infrastructure, it provides a significantly faster response time for users.

Architectural Comparison: Distributed vs. Integrated

The official A2UI is designed as a "distributed" system for cross-platform interoperability. In contrast, the GAS-native version is an "integrated" system optimized specifically for the Google infrastructure.

Official A2UI Workflow (via A2A Protocol)

Process: The Frontend requests data from an A2A Server (e.g., Node.js/Python). The Server handles auth/protocol logic and requests JSON from the Gemini API. The generated JSON travels back through the server to the Frontend for rendering.
Challenge: Multiple network hops across the internet introduce latency and overhead.

GAS Native Workflow (via google.script.run)

Process: The Frontend (HTML) directly calls a GAS Backend function using google.script.run. The GAS Backend communicates with the Gemini API using UrlFetchApp to get the UI JSON. The script returns the object directly to the client for immediate rendering.
Innovation: By using google.script.run, the entire communication happens within Google's internal high-speed network. There is no need for an external A2A server, eliminating external network overhead.

Analysis: Pros and Cons of GAS-based A2UI

Why should users choose the GAS-native approach for their AI applications?

Pros

Zero Setup Cost & Rapid Development: No servers to manage. Backend, frontend, and AI integration all live in a single GAS project.
Seamless Google Integration: It is incredibly easy to let the AI perform "real-world actions," such as using Google Sheets as a database or managing Google Calendar events.
High Performance: Bypassing an external proxy server via google.script.run ensures a snappier, more responsive user experience.

Cons

Manual Rendering Logic: While the official version provides out-of-the-box UI components, the GAS version requires you to maintain the logic that converts JSON to HTML elements (the renderComponent code).
Execution Quotas: GAS has specific limits, such as a 6-minute execution timeout and daily triggers, which may not suit high-scale enterprise apps.

Application Setup

To deploy this application in your own environment, please follow the steps below.

1. Obtain an API Key

You will need a valid Gemini API Key to communicate with the LLM.
Get one here.

2. Copy the Sample Script

You can copy the Google Spreadsheet containing the necessary Google Apps Script using the link below.

https://docs.google.com/spreadsheets/d/1NdgN5e2l7-CTw-NTaP50Ta75l8Zbr93ATMyUOlZk1BY/copy

After copying the Google Spreadsheet:

Open the script editor (Extensions > Apps Script).
Locate the main.gs file.
Set your API key in the apiKey variable.
Save the script.

Alternatively, you can visit the GitHub Repository to manually copy the source codes.

Demonstration and Testing

Once the script is set up, re-open the Google Spreadsheet (or refresh the page). You will see a table on the "data" sheet, which acts as the source for the event demonstration.

A custom menu labeled "sample" will appear in the toolbar. Select sample > run to open the A2UI dialog.

In this demonstration, you can test the following two prompts:

1. "Find 3 Chinese restaurants in New York"

This prompt replicates the official A2UI demonstration. It tests the system's ability to retrieve mock data, render a list of restaurants with images, and present a booking form.

2. "Show me events for Jan 17-20"

This prompt demonstrates a custom integration with Google Workspace. The agent searches the spreadsheet for events within the specified date range and presents them as a selectable list. Upon confirmation, the agent triggers a function to register the selected events directly to your Google Calendar.

Summary

This project confirms that the A2UI protocol can be effectively implemented within the Google Apps Script environment.

Serverless Architecture: A2UI can be deployed using only GAS and Google Sheets, eliminating the need for external web servers or hosting.
Deep Workspace Integration: The system seamlessly connects Generative AI with Workspace tools, allowing actions like reading Sheets and writing to Calendar.
Enhanced Security: By adhering to A2UI's schema-driven rendering, the application avoids the high risks associated with generating and executing arbitrary HTML/JS code.
Dynamic User Experience: Users receive interactive, app-like interfaces (forms, buttons, lists) directly within a chat dialog, vastly improving usability over plain text.
Scalability to other Apps: This approach is not limited to Sheets; it can be readily adapted for Google Docs, Slides, and other Workspace applications to create a unified AI interface.

Seamless Integration of Google Workspace and Gemini API via External URLs

Tanaike — Thu, 15 Jan 2026 05:54:58 +0000

Abstract

The Gemini API now supports external file URLs, allowing developers to process data directly without uploading it first. This article demonstrates how to leverage this update to integrate Google Workspace resources—including Google Sheets, Docs, Slides, and Apps Script—into Gemini’s workflow, covering both public and secure private access methods.

Introduction

Recently, the limitations regarding inline file data in the Gemini API have been significantly updated Ref. The maximum file size has increased from 20 MB to 100 MB. Furthermore, external file URLs—both public and signed—can now be used directly as input.

The ability to use public external file URLs is particularly significant. Previously, data had to be uploaded to Gemini's servers first to generate an internal URI for processing. Eliminating this step substantially reduces processing overhead and latency.

It is considered that this update effectively bridges the gap between the Gemini API and the Google Workspace ecosystem. This article investigates the technical specifications of these external file URLs and explores how they enhance interoperability with Google Sheets, Docs, Slides, and Google Apps Script.

Prerequisites

To test the samples provided in this article, you will need a valid Gemini API Key.
Get an API Key here.

Integration with Google Workspace Files (Sheets, Docs, Slides)

Google Sheets is a representative resource within Google Workspace. In this section, we demonstrate how to use Google Sheets (and by extension, Docs and Slides) as an external URL source for the Gemini API.

1. Setting up the Google Sheet

Please create a new Google Spreadsheet and populate it with sample data. The image below shows the sample table used in this demonstration.

For the initial test, share this Google Spreadsheet publicly as "Anyone with the link can view". Ref Copy the Spreadsheet ID from the URL bar.

2. Client Script for Public URLs

Here, Node.js is used as the client environment. Ref

Please replace ### with your actual Spreadsheet ID in the spreadsheetId variable.

import { GoogleGenAI, createPartFromUri } from "@google/genai";

const spreadsheetId = "###";
const ai = new GoogleGenAI({});

async function main() {
  // Construct the URL to export the Sheet as a PDF
  const uri = `https://docs.google.com/spreadsheets/d/${spreadsheetId}/export?format=pdf`;

  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: [
      createPartFromUri(uri, "application/pdf"),
      "Describe the PDF data.",
    ],
  });
  console.log(response.text);
}

main();

When this script is executed, the Gemini API directly accesses the PDF export URL of the Spreadsheet. The result confirms that the model can interpret the current state of the Spreadsheet:

The PDF contains a table for tracking customer feedback, including manual input and AI-generated analysis. The table consists of five columns: **Date**, **Purchase ID**, **Feedback**, **AI sentiment**, and **AI category**.

There are three recorded entries of customer feedback:

1.  **October 12, 2024 (ID: 82736481):** A highly positive review for a custom-made pendant, noted for its beauty and craftsmanship. The AI classifies the sentiment as **Positive** and the category as **Compliment**.
2.  **December 19, 2024 (ID: 77654822):** A request to exchange a pair of pearl earrings for a smaller size. The AI classifies the sentiment as **Neutral** and the category as an **Exchange request**.
3.  **December 24, 2024 (ID: 84435116):** A complaint regarding a silver chain that tarnished quickly, leading to a request for a full refund. The AI classifies the sentiment as **Negative** and the category as a **Return request**.

The bottom of the table includes four placeholder rows with generic labels ("yyyy/mm/dd", "##", "Feedback") for future entries.

3. Applying to Other Workspace Services

This approach—using the export URL—is applicable to Google Sheets, Google Docs, and Google Slides. The URL patterns are as follows:

For Google Sheets:

const uri = `https://docs.google.com/spreadsheets/d/${spreadsheetId}/export?format=pdf`;

// Or, for a specific sheet (gid)
const uri = `https://docs.google.com/spreadsheets/d/${spreadsheetId}/export?format=pdf&gid=${sheetId}`;

For Google Docs:

const uri = `https://docs.google.com/document/d/${documentId}/export?format=pdf`;

// Or, for a specific tab
const uri = `https://docs.google.com/document/d/${documentId}/export?format=pdf&tab=${tabId}`;

For Google Slides:

const uri = `https://docs.google.com/presentation/d/${presentationId}/export?format=pdf`;

4. Handling Private Content

In a production environment, you likely do not want to make your files public. If you attempt to use the URL of a private file directly, the API will return the following error:

{"error":{"code":400,"message":"Cannot fetch content from the provided URL.","status":"INVALID_ARGUMENT"}}

To resolve this, you can append an OAuth 2.0 access token to the URL query parameters. (The access token from the service account can also be used.) This allows the Gemini API to fetch the content with the necessary permissions.

For Google Sheets:

The access token must have the scope https://www.googleapis.com/auth/spreadsheets or https://www.googleapis.com/auth/spreadsheets.readonly.

const uri = `https://docs.google.com/spreadsheets/d/${spreadsheetId}/export?format=pdf&access_token=${accessToken}`;

For Google Docs:

The access token must have the scope https://www.googleapis.com/auth/documents or https://www.googleapis.com/auth/documents.readonly.

const uri = `https://docs.google.com/document/d/${documentId}/export?format=pdf&access_token=${accessToken}`;

For Google Slides:

The access token must have the scope https://www.googleapis.com/auth/presentations or https://www.googleapis.com/auth/presentations.readonly.

const uri = `https://docs.google.com/presentation/d/${presentationId}/export?format=pdf&access_token=${accessToken}`;

Utility Script: Retrieving an Access Token

The following helper script uses the gcloud CLI to retrieve a valid access token for testing purposes. Ensure gcloud is installed and authenticated (gcloud auth application-default login) before running this.

import { execSync } from "child_process";

function getAccessToken() {
  // 1. Check if gcloud CLI is installed
  try {
    execSync("gcloud --version", { stdio: "ignore" });
  } catch (error) {
    console.error(
      "\n[Error] Google Cloud SDK (gcloud CLI) not found or failed to run."
    );
    console.error("Please install it by following the official instructions:");
    console.error("https://cloud.google.com/sdk/gcloud");
    process.exit(1);
  }

  // 2. Obtain access token
  try {
    return execSync("gcloud auth print-access-token", {
      encoding: "utf8",
    }).trim();
  } catch (error) {
    console.error("\nError obtaining access token:");
    console.error(error.message);
    console.error(
      "Please ensure you are authenticated with gcloud CLI. Run 'gcloud auth application-default login'."
    );
    process.exit(1);
  }
}

Dynamic Content with Google Apps Script

Google Apps Script (GAS) is a powerful tool for automation and dynamic content generation. By deploying a script as a Web App, we can create a dynamic external URL for the Gemini API.

1. Setting up the Web App

In this example, we create a simple Web App that returns a specific text string. This simulates a dynamic data source.

Create a standalone Google Apps Script file in Google Drive and paste the following code:

function doGet(e) {
  const text = "The current keyword is 'apple'.";
  return ContentService.createTextOutput(text);
}

Next, deploy the script as a Web App:

Open the script editor.
Click Deploy > New deployment.
Select Web App as the type.
Set "Execute as" to Me.
Set "Who has access" to Anyone.
Click Deploy and copy the Web App URL (https://script.google.com/macros/s/###/exec).

Note on Security:
If you wish to restrict access (e.g., set "Who has access" to Only myself), you must append the access token to the Web App URL, similar to the private file examples above:
https://script.google.com/macros/s/###/exec?access_token=${accessToken}.

Note on Updates:
When modifying the GAS code, you must create a new deployment version to reflect the changes in the Web App URL. Reference. Additional details on GAS Web Apps can be found here.

2. Client Script for GAS Web Apps

Set your Web App URL to the uri variable.

import { GoogleGenAI, createPartFromUri } from "@google/genai";

const uri =  "https://script.google.com/macros/s/###/exec";
const ai = new GoogleGenAI({});

async function main() {
  const response = await ai.models.generateContent({
    model: "gemini-3-flash-preview",
    contents: [
      createPartFromUri(uri, "text/plain"),
      "What is the current key word?",
    ],
  });
  console.log(response.text);
}

main();

3. Testing Dynamic Updates

When the script is run initially, the output is:

The current keyword is **apple**.

To test the dynamic nature of this integration, modify the GAS code:
Change const text = "The current keyword is 'apple'."; to const text = "The current keyword is 'orange'.";.
Deploy a new version of the Web App.

Running the client script again yields:

The current keyword is **orange**.

This test confirms that the Gemini API always fetches data from the external URL in real-time. This capability is incredibly powerful. It allows Gemini to generate content based on live data feeds, latest news, or real-time calculations performed by Google Apps Script.

Additionally, it is worth noting that GAS Web Apps typically require clients to follow HTTP redirects. Ref. The success of this test indicates that the Gemini API's external URL fetcher correctly handles HTTP redirects, ensuring seamless integration with services like GAS.

Summary

The Gemini API now supports external file URLs (up to 100 MB), eliminating the need to upload files beforehand.
Google Workspace files (Sheets, Docs, Slides) can be directly ingested by Gemini using their PDF export URLs.
Private Workspace files can be accessed securely by appending a valid OAuth 2.0 access token to the URL parameters.
Google Apps Script Web Apps allow for the integration of dynamic, real-time data sources into Gemini's generation process.
The Gemini API correctly handles HTTP redirects, which is essential for working with Google Apps Script Web Apps and similar services.

Building Next-Gen AI Agents for Google Workspace: MCP, A2A, and A2UI with Google Apps Script

Tanaike — Sat, 10 Jan 2026 02:38:25 +0000

Abstract

This article demonstrates how to implement Model Context Protocol (MCP), Agent-to-Agent (A2A), and Agent-to-UI (A2UI) utilizing Google Apps Script (GAS). By leveraging GAS, developers can overcome authentication bottlenecks, enabling seamless integration of AI agents with Google Workspace data for powerful, autonomous workflows and dynamic user interfaces.

Introduction

The ecosystem of AI agents is evolving rapidly. To enable these agents to process complex tasks effectively, the Model Context Protocol (MCP) has emerged as a critical standard. MCP allows AI models, such as Large Language Models (LLMs), to connect and interact with external data sources, tools, and software applications in a standardized manner. Ref

Looking ahead, Agent2Agent (A2A) and Agent-to-User Interface (A2UI) protocols are expected to play pivotal roles. A2A refers to the autonomous communication and interaction between multiple AI agents without direct human intervention. Ref Meanwhile, A2UI allows AI agents to construct interactive user interfaces using structured data (such as JSON) rather than static code. This enables an agent to generate a specific UI—like a restaurant booking form—on the fly, which the host application renders using native components. Ref

Integrating these technologies with Google Workspace unlocks limitless potential. Recently, a Gemini CLI extension including an MCP server for Workspace management was released. Ref However, existing samples for MCP, A2A, and A2UI often face compatibility issues with Google Workspace, primarily due to complex scope authorization bottlenecks. Connecting from a local environment typically requires handling OAuth 2.0 or service accounts, which can hinder rapid development.

Google Apps Script (GAS) offers a robust solution to this challenge. As the only low-code platform designed to integrate, automate, and extend Google Workspace, GAS handles scope authorization seamlessly upon execution. Ref Consequently, leveraging GAS significantly simplifies the implementation of MCP, A2A, and A2UI. This article introduces practical implementations of these protocols using Google Apps Script.

Project Resources

MCP & A2A Repository: https://github.com/tanaikech/a2a-for-google-apps-script
A2UI Repository: https://github.com/tanaikech/A2UI-for-Google-Apps-Script

Part 1: MCP (Model Context Protocol)

In this section, we will build an MCP server using Google Apps Script and test it using the Gemini CLI.

Prerequisites

Node.js is installed on your local machine.
A valid Gemini API Key. Get one here.
The Gemini CLI is installed. Ref

1. Server-Side Setup

1.1 Copy the Demo Script

You can copy the A2A server template to your Google Drive by running the following GAS code:

function myFunction() {
  const fileId = "1mylSOTzCuui95Amk-kRufA9ffMqcnjqk8HSaoatoxaSPwkv-hg1q7uRC";
  const file = DriveApp.getFileById(fileId);
  file.makeCopy(file.getName());
}

Run myFunction to copy the sample A2A server to your root folder.

Alternatively, you can manually copy the scripts from the GitHub Repository. This example uses a2a-server/sample2/a2a-server.js, which integrates 160 tools from ToolsForMCPServer.

For developers wishing to use custom tools, a separate sample is available at a2a-server/sample1/a2a-server.js.

1.2 Deploy as Web App

Open the script editor in your copied project.
Click Deploy > New deployment.
Select Web App as the type.
Set "Execute as" to Me.
Set "Who has access" to Anyone.
Click Deploy and copy the Web App URL (https://script.google.com/macros/s/###/exec).

Note: Whenever you modify the code, you must deploy a new version to reflect the changes. Reference.

1.3 Configure the Script

Locate the configuration object in your GAS project and update the variables:

const object = {
  apiKey: "{apiKey}", // Your API key for using Gemini API.
  model: "models/gemini-3-flash-preview",
  accessKey: "sample", // Optional: Access key for requesting Web Apps.
  webAppsUrl: "https://script.google.com/macros/s/###/exec", // Your deployed Web App URL.
  // logSpreadsheetId: "{spreadsheetId}", // Optional: Store logs in Google Spreadsheet.
};

Set your Gemini API key in apiKey.
Set your access key (default is sample).
Set your Web App URL in webAppsUrl.

After updating the script, remember to redeploy the Web App.

2. Client-Side Setup

Navigate to the .gemini directory on your local machine and update settings.json. Replace {Your value} with your specific details.

{
  "security": {
    "auth": {
      "selectedType": "{Your value}"
    }
  },
  "ui": {
    "theme": "{Your value}"
  },
  "mcpServers": {
    "gas_web_apps": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://script.google.com/macros/s/{Your value}/exec?accessKey=sample"
      ],
      "timeout": 300000
    }
  }
}

Launch the Gemini CLI and run the command /mcp. You should see the connected status. You can now use the tools immediately because the authorization process was handled during the GAS Web App deployment.

Part 2: A2A (Agent-to-Agent)

1. Server-Side Setup

If you have successfully completed the MCP test above, your server is ready. The GAS Web App configured in the previous section functions as both an MCP server and an A2A server. No further server-side configuration is required.

2. Client-Side Setup

2.1 Clone Repository and Install Dependencies

Execute the following commands in your terminal:

git clone https://github.com/tanaikech/a2a-for-google-apps-script
cd a2a-for-google-apps-script/a2a-client
npm install

The directory contains:

a2a-client: Node.js sample client scripts.
a2a-server: Google Apps Script Web App server samples.

2.2 The Proxy Script

The current @a2a-js/sdk version automatically strips query parameters and redirects to a /.well-known/ path. To resolve this, the provided clientGas.js acts as a proxy. It intercepts the fetch API, allowing the SDK to communicate correctly with GAS's dynamic URLs.

Authentication Note: This script uses the Google Cloud SDK (gcloud CLI) to retrieve access tokens. Ensure you have authorized the https://www.googleapis.com/auth/drive.readonly or https://www.googleapis.com/auth/drive scope. This is required to access the GAS Web App path /.well-known/agent-card.json.

2.3 Set Environment Variables

Create a .env file in the a2a-client directory:

GEMINI_API_KEY="YOUR_KEY"
GEMINI_MODEL="gemini-3-flash-preview"
A2A_WEB_APPS_URL="https://script.google.com/macros/s/{Your value}/exec?accessKey=sample"

Ensure A2A_WEB_APPS_URL includes your access key as a query parameter. This sample uses a single A2A server. To use multiple servers, define additional variables and register them using new FunctionTool in the client script.

2.4 Testing

Terminal Test

Run the basic connectivity test:

npm run test1

Expected output:

Prompt: How much is 10 yen in USD?
Response: 10 yen is approximately **0.0641 USD**...
Prompt: What is the weather forecast for Tokyo?
Response: The weather forecast for Tokyo... is clear sky.

Browser/ADK Test

This test utilizes the Agent Development Kit (ADK) to provide a chat interface:

npm run test2

Open http://localhost:8000 in your browser.

Example 1: Simple Workflow

Prompt:

I want to cook miso soup.
To achieve this goal, create a new Google Spreadsheet,
generate a roadmap for cooking miso soup in the spreadsheet,
and return the Spreadsheet URL.

The browser demonstrates the agent processing the prompt via the A2A server.

The resulting roadmap in the Spreadsheet:

Example 2: Complex Workflow

Prompt:

Write a comprehensive article about developing Google Apps Script (GAS) using generative AI.
The article should include an introductory overview, formatted lists for best practices,
and a table comparing different AI-assisted coding techniques.
Once generated, please create a new Google Document, insert the content, convert the Google Document to a PDF file,
and send an email to `tanaike@hotmail.com` including the shareable URL of the PDF file by giving a suitable title and email body.

The browser visualizes the processing steps:

This task requires coordination between the Docs API, Drive API, and Gmail API. While this might trigger a Tool Selection Issue (TSI) in standard environments, the GAS A2A server handles the deterministic selection seamlessly.

The generated PDF:

The email received:

Dear Tanaike,

Please find attached the PDF document containing the comprehensive article on "Leveraging Generative AI for Google Apps Script Development". The shareable URL for the PDF is https://drive.google.com/file/d/###/view?usp=sharing.

Best regards,
Your AI Assistant

Part 3: A2UI (Agent-to-User Interface)

In the official A2UI sample (Restaurant finder), the client communicates via A2A protocols. In this GAS-optimized implementation, we reduce HTTP overhead by allowing the client (HTML) to communicate directly with the AI agent using google.script.run.

1. Sample Script

Copy the Google Spreadsheet containing the necessary scripts:

https://docs.google.com/spreadsheets/d/1csYUJO8LzcEFPkt_ickIkdsGZsvim6lb1OEQZHUkB3c/copy

After copying, open the script editor and set your apiKey in main.gs.

Alternatively, access the code via the GitHub Repository.

2. Deploy as Web App

Open the script editor in your project.
Click Deploy > New deployment.
Select Web App.
Set "Execute as" to Me.
Set "Who has access" to Only myself. (Restrict access to yourself for testing as the owner).
Click Deploy and copy the Web App URL.

Note: You can use the dev mode URL (.../dev) for testing. Updates require a new deployment. Reference.

3. Testing

Sample 1: Restaurant Finder

This test reproduces the official "A2UI Restaurant finder" sample.

Open your Web App URL. You will see the interface:

Enter: "Find 3 Chinese restaurants in New York" and click Send.

Click Book Now for "Han Dynasty". The agent generates a reservation UI.

Fill in the details and click Submit Reservation. The server processes the request.

Using Spreadsheet Data:
While the sample uses hard-coded data in executeGetRestaurants, GAS allows you to fetch this from a Spreadsheet easily. If you have a sheet formatted like this:

You can replace the data source with:

const allRestaurants = ((_) => {
  const sheet = SpreadsheetApp.getActiveSpreadsheet().getSheetByName("Sheet1");
  const [header, ...values] = sheet.getDataRange().getDisplayValues();
  const obj = values.map((e) =>
    header.reduce((o, h, j) => ((o[h] = e[j]), o), {})
  );
  return obj;
})();

Sample 2: Budget Simulator

Copy the Budget Simulator Spreadsheet:

https://docs.google.com/spreadsheets/d/1HEfmSD9WMqQfy39aEZEjz7ggFeiZIx0_b2oKkrReEpk/copy

Set your apiKey in main.gs after copying.

This sample implements an "Interactive smart household account book and budget simulator". Ensure "Sheet1" contains the initial budget data:

Deploy as a Web App and open the URL.

Enter: Check this month's budget. A2UI displays a pie chart and category list based on the spreadsheet data.

Enter: "What would happen if I reduced my dining out expenses by 10,000 yen and put the money towards savings?"

The graph updates to simulate the proposal.

Click Update sheet with this budget proposal. GAS updates the cells, and a notification confirms the action.

The new data is appended to "Sheet1":

Summary

MCP, A2A, and A2UI represent the future of AI interoperability, enabling agents to connect with tools, collaborate with each other, and generate dynamic user interfaces.
Google Apps Script provides a unique advantage by resolving complex OAuth 2.0 authorization bottlenecks native to local environments.
Implementing MCP servers on GAS allows for seamless integration between the Gemini CLI and Google Workspace data.
A2A on GAS facilitates autonomous multi-agent workflows, capable of executing complex tasks like generating documents and sending emails without human intervention.
A2UI combined with GAS allows agents to build interactive, data-driven interfaces on the fly, directly connected to live Spreadsheet data.

Appendix

I am exploring taking advantage of Google Apps Script. The summary of this can be seen https://github.com/tanaikech/taking-advantage-of-google-apps-script.