Forem: Tanaike

Next-Generation Google Workspace Automation

Tanaike — Mon, 27 Apr 2026 01:52:43 +0000

A Comparative Study of Agentic Frameworks and Multi-Agent Orchestration

Abstract

The transition from passive chatbots to autonomous execution environments was cemented at Google Cloud Next '26 with the introduction of the Gemini Enterprise Agent Platform. This paper evaluates four cutting-edge AI agent methodologies for Google Workspace automation, developed by leading developers Martin Hawksey, Bruce Mcpherson, and Kanshi Tanaike. We deconstruct their structural approaches—CLI skill chaining, advanced emulation sandboxing, dynamic code generation, and A2A remote delegation—demonstrating how these community-driven innovations anticipated native Next '26 features like the official Agent Skills repository and Model Context Protocol (MCP) support. Building upon these foundations, we propose two novel frameworks: the Federated Context-Aware Routing Architecture (Federated CARA) for zero-trust, multi-cloud task routing, and the Self-Optimizing Tool Caching Network (SOTCN) to eliminate Tool Space Interference using dynamic semantic caching. This comparative synthesis maps existing and proposed models against Google's new enterprise standards, offering a scalable roadmap for secure, highly dynamic multi-agent orchestration.

1. Introduction

Historically, automating tasks within Google Workspace relied heavily on static, hardcoded macros defined via Google Apps Script (GAS) and rigidly scheduled cloud triggers. While highly effective for predictable workflows, this paradigm lacked the adaptability required for complex, context-dependent enterprise operations. The advent of Large Language Models (LLMs) catalyzed the transition toward the "Agentic Enterprise," wherein AI entities act as autonomous orchestration layers capable of interacting dynamically with vast API ecosystems. At Google Cloud Next '26, this shift was cemented through the introduction of Workspace Intelligence, a semantic unifying layer that allows agents to autonomously execute multi-step tasks across Gmail, Docs, Sheets, and Drive without manual context provisioning.

However, bridging LLM reasoning engines with Google Workspace APIs introduces profound architectural challenges, notably regarding execution latency, security perimeters, and Tool Space Interference (TSI). TSI—officially recognized by Google as "context bloat"—is a phenomenon where an agent's reasoning accuracy degrades, and token costs skyrocket, when its context window is overloaded with a massive library of predefined functions.

This paper analyzes four prominent, recently published developer methodologies that sought to solve these challenges before they were addressed natively. By evaluating these frameworks against Next '26 announcements like the GKE Agent Sandbox , native Agent Registry , and the Agent Gateway, we identify key strengths and limitations. Subsequently, we propose advanced hybrid frameworks—Federated CARA and SOTCN—tailored to leverage Google's new native security and orchestration layers for the next generation of highly secure, scalable enterprise deployment.

2. Architectural Analysis of Existing Methodologies

The automation of Google Workspace using AI agents is an emerging field characterized by highly divergent architectural philosophies. The following sections provide an exhaustive deconstruction of four primary paradigms.

2.1 Skill-Based Prototyping Using CLI Integrations (Martin Hawksey)

Ref: Exploring Workspace Intelligence Skills using the Workspace CLI and Gemini CLIs with Apps Script API Executables

Ref: gws-web-to-doc

Martin Hawksey’s project (gws-web-to-doc) demonstrates how discrete, legacy command-line tools can be wrapped into modular AI skills. By combining local Node.js execution with the Google Workspace CLI (gws) and remote GAS deployment, Hawksey creates a linear execution pipeline. For instance, in his "Web-to-Doc" workflow, local scripts extract web content, the CLI natively converts the Markdown to a Google Document, and an API Executable GAS script (resizer.gs) handles precise image formatting.

Primary Strength: Excellently bridges legacy scripting and modern LLM orchestration, making isolated tasks readily accessible to AI.

2.2 Local Natural Language Execution via Emulation (Bruce Mcpherson)

Ref: gas-fakes agent: local natural language requests against workspace resources

Ref: gf_agent - Google Apps Script Local Automation Agent

Bruce Mcpherson addresses iteration latency and cloud security through his gas-fakes-agent framework. By utilizing the gas-fakes emulation layer, Mcpherson enables an LLM to dynamically generate GAS syntax and execute it within a Node.js environment that can be run locally or containerized in any cloud platform. Because it uses Google APIs under the hood, standard network and API latencies still apply, and the files manipulated remain cloud-based just like native GAS. The framework is highly versatile—it can be deployed across multiple cloud platforms (aligning with the modern emphasis on sovereign clouds) and can operate and mix multiple backends, such as Microsoft OneDrive and Office files. Crucially, the gf_agent approach is made possible by continuous learning from over 10,000 tests that gas-fakes uses to ensure its consistency with live Apps Script. This foundation allows the agent to self-augment through continuous cyclical feedback as new methods are introduced.

Primary Strength: Advanced execution sandboxing and robust permission management. Its security paradigm emphasizes secure sandboxing rather than authentication per se. While it utilizes the same authentication mechanisms available to any OAuth2 protected app—such as Application Default Credentials (ADC), Domain Wide Delegation (DWD), and keyless workload identity federation—it uniquely takes care of the permission complications associated with them. Furthermore, its native compatibility with the Model Context Protocol (MCP) sets a standardized foundation for AI-to-tool interfacing.

2.3 Dynamic Tool Creation to Combat Tool Space Interference (Kanshi Tanaike)

Ref: Empowering Autonomous AI Agents through Dynamic Tool Creation

Ref: autonomous-google-workspace-agent

To solve the cognitive bottleneck of Tool Space Interference (TSI) in enterprise LLMs, Kanshi Tanaike’s autonomous-google-workspace-agent introduces a fully autonomous, self-healing multi-agent architecture. When faced with an edge case lacking a predefined solution, a Senior Orchestrator coordinates five sub-agents (Environment Checker, Script Writer, Script Executor, Script Uploader, and Summary Agent) to write, sandbox-test (using gas-fakes), deploy (via clasp), and execute custom tools in real-time.

Primary Strength: Fundamentally eliminates TSI by relying on dynamic tool generation rather than a saturated context window. It serves as a secure "kill switch" against reasoning drift by isolating untrusted code generation within a sandbox before cloud deployment.

2.4 Remote Subagent Integration via the A2A Protocol (Kanshi Tanaike)

Ref: Integrating Remote Subagents Built by Google Apps Script with Gemini CLI

Ref: gemini-cli-gas-a2a-subagents

In a subsequent approach (gemini-cli-gas-a2a-subagents), Tanaike solves TSI through remote delegation rather than dynamic generation. A primary LLM offloads a massive repository of over 160 established Workspace skills to a specialized Google Apps Script Web App using the Agent-to-Agent (A2A) protocol. Tanaike elegantly bypasses strict Google Cloud cross-domain (CORS) authentication hurdles by predefining "agent cards" locally within the Gemini CLI.

Primary Strength: Preserves the primary agent's reasoning stability without the compute overhead of writing new code, allowing frictionless access to massive legacy macro libraries.

3. Proposed Novel Methodologies for Advanced Workspace Automation

Based on the strengths and limitations of the analyzed frameworks, and aligning with the latest native paradigms introduced at Google Cloud Next '26, we propose two novel architectural approaches intended for advanced enterprise use cases.

3.1 Federated Context-Aware Routing Architecture (Federated CARA)

Concept: A zero-trust hybrid orchestration network that dynamically routes AI tasks based on a real-time assessment of data sensitivity, computational demand, and cross-platform interoperability requirements.
Architecture: A central LLM routing agent acts as a security triage engine. If a natural language prompt involves sensitive organizational data or requires orchestration across mixed backends (e.g., interacting simultaneously with Google Workspace and Microsoft OneDrive), the orchestrator routes the execution to an advanced sandboxed emulation layer. Synthesizing Mcpherson's gas-fakes approach, this layer utilizes keyless workload identity federation and Application Default Credentials (ADC) to securely manage complex permissions. It natively supports multi-cloud deployments—including sovereign clouds—ensuring that while external APIs are accessed under the hood, the execution environment itself remains strictly controlled and continuously validated through self-augmenting feedback loops. Conversely, if the task requires heavy bulk processing over established legacy macros, the execution is delegated to a remote A2A subagent (synthesizing Tanaike's Web App protocol).
Enterprise Value: Maximizes cross-platform versatility and infrastructure flexibility while enforcing strict compliance and data governance perimeters. By focusing on advanced execution sandboxing rather than relying solely on traditional authentication barriers, it securely bridges distinct enterprise ecosystems.

3.2 Self-Optimizing Tool Caching Network (SOTCN)

Concept: An advanced solution to Tool Space Interference (TSI) that bridges the gap between dynamic code creation, static remote delegation, and newly standardized enterprise skill registries.
Architecture: Instead of writing code from scratch (which incurs API latency) or loading 160+ tools simultaneously (which inevitably degrades LLM reasoning), the SOTCN utilizes a massive "cold storage" repository of pre-validated scripts. Crucially, this architecture is designed to integrate seamlessly with Google's newly announced official Agent Skills repository. By treating both officially published Agent Skills and custom-built Workspace scripts as modular assets, SOTCN acts as a dynamic curator. When a user issues a command, an ultra-fast semantic vector search identifies the top 3–5 most relevant skills. A local "Injection Agent" then dynamically injects only those specific functions into the primary LLM's active Model Context Protocol (MCP) context window for the duration of that specific session.
Enterprise Value: Eliminates TSI entirely by maintaining a pristine, minimal active context window. By leveraging both community-driven repositories and official Google Agent Skills, SOTCN avoids the latency and debugging failure rates of real-time code generation while effectively future-proofing enterprise deployments against evolving native ecosystem standards.

4. Comparative Analysis

The table below synthesizes the structural and functional nuances of the four original methodologies alongside our two newly proposed frameworks.

5. Discussion and Conclusion

The evolution of Google Workspace automation reflects a broader industry shift toward "Agentic" design. Hawksey’s foundational work establishes how legacy scripts can be seamlessly bridged to LLMs, preempting Google's recent Next '26 announcement of the official Agent Skills repository. Mcpherson's integration of the gas-fakes emulation layer combined with the Model Context Protocol (MCP) redefines enterprise security and interoperability. Rather than simply isolating execution, Mcpherson demonstrates how advanced sandboxing, managed via mechanisms like keyless workload identity federation, enables multi-cloud versatility (supporting sovereign clouds) and cross-platform backend integration (e.g., Microsoft OneDrive). Furthermore, powered by continuous learning from over 10,000 tests, this approach proves that agents can reliably self-augment through cyclical feedback. Tanaike pushes the envelope of scalability; his dual approaches to Tool Space Interference (TSI) demonstrate that AI systems must either possess the autonomy to self-generate capabilities or the communicative protocols (A2A) to delegate them.

The proposed frameworks, Federated CARA and SOTCN, represent the logical next steps in this evolution, deeply aligning with the latest native Google Cloud capabilities. In particular, the SOTCN methodology provides a powerful extension to Google's newly introduced Agent Skills paradigm by offering a semantic caching mechanism that programmatically eliminates context bloat while standardizing tool invocation. By optimizing for latency, context window preservation, multi-cloud versatility, and strict data compliance, these advanced methodologies outline a robust, future-proof roadmap for deploying enterprise-grade, autonomous AI coworkers that are as reliable as they are dynamic.

6. Summary

Evolution of Automation: Workspace automation has officially shifted from rigid Google Apps Script macros to the "Agentic Era," powered by the new Gemini Enterprise Agent Platform, which natively supports the building, scaling, and governance of autonomous agents.
Skill Chaining (Hawksey): Utilizes the Workspace CLI to combine local Node.js execution with remote GAS deployment. This foundational approach preempted Google's newly announced Agent Skills repository, which formalizes skills as compact, agent-first documentation to mitigate context bloat.
Local Sandboxing (Mcpherson): Employs the gas-fakes emulation layer and MCP to securely execute LLM-generated code locally or containerized in any cloud platform. This focus on secure isolation and standardized tooling is now mirrored at the enterprise level by Google's native MCP support and the highly secure GKE Agent Sandbox utilizing gVisor.
Dynamic Generation (Tanaike): Utilizes a sophisticated 5-agent orchestrator to write, sandbox-test, and cloud-deploy custom tools in real-time, effectively solving Tool Space Interference (TSI). This mirrors the capabilities of Google's newly announced Long-running agents, which autonomously execute multi-step workflows inside secure cloud sandboxes.
Remote Delegation (Tanaike): Leverages the A2A protocol to offload massive libraries of over 160 predefined skills to remote GAS Web Apps. This community-built solution directly anticipated Google's native A2A (Agent-to-Agent) Orchestration and Agent Registry, which now allow enterprise agents to natively discover and delegate tasks to one another.
Proposed Method 1 (Federated CARA): A zero-trust architecture that routes AI tasks to either containerized emulation or remote A2A subagents based on the data's security classification. This framework is perfectly positioned to integrate with the newly announced Agent Gateway and Agent Identity, natively enforcing IAM access control policies and guarding against data exfiltration.
Proposed Method 2 (SOTCN): A semantic caching network that stores predefined tools in "cold storage" and dynamically injects only the most relevant functions into the agent's active context window. This architecture enhances Google's new Agent Skills paradigm by programmatically eliminating context bloat without the latency of generative code writing.

7. Explanatory video

Empowering Autonomous AI Agents through Dynamic Tool Creation

Tanaike — Fri, 24 Apr 2026 07:36:01 +0000

Abstract

Welcome to the Agentic Enterprise era. This article explores a paradigm shift in generative AI workflows by introducing an autonomous agent capable of dynamically creating, testing, and executing original tools. Utilizing Google Apps Script, Node.js emulation, and multi-agent orchestration, this architecture overcomes traditional limitations, enabling highly adaptable task execution.

Introduction

At Google Cloud Next 2026, a clear mandate was delivered: the era of generative AI as a passive assistant is over. We have entered the age of the Agentic Enterprise, where AI has transitioned from a software tool you deploy into an autonomous coworker you onboard. This identity shift is staggering. With models processing over 16 billion tokens per minute via direct API use, we are witnessing an industrial-scale migration toward autonomous workflows. In this new ecosystem, Workspace Intelligence eliminates tab-hopping, allowing users to seamlessly query across Google Drive, Gmail, and third-party platforms. Data has transformed from a reactive archive into a "System of Action," driven by Deep Research Agents that bridge structured and unstructured data to prevent hallucinations.

However, this massive scale introduces new vulnerabilities and operational bottlenecks. As organizations adopt these highly autonomous coworkers to execute a wide variety of tasks, a vast multitude of tools is required. Yet, as the number of available tools in a Model Context Protocol (MCP) server increases, Large Language Models (LLMs) face a critical issue: inference accuracy and tool selection reliability significantly degrade. Researchers refer to this phenomenon as "Tool Space Interference" (TSI). Ref When an LLM's context window becomes saturated with excessive tool definitions, semantic overlaps and irrelevant metadata hinder decision-making. Current technical guidelines recommend a "soft limit" of approximately 20 functions to maintain high accuracy. Exceeding this threshold often leads to increased hallucinations and failures in executing complex instructions.

To address this, I previously published the article "Nexus-MCP: A Unified Gateway for Scalable and Deterministic MCP Server Aggregation." Ref In that piece, I introduced Nexus-MCP, a concept resolving Tool Space Interference by aggregating multiple MCP servers into a single deterministic gateway. Yet, even with this optimized architecture, a hard limit is eventually reached when attempting to execute an increasingly diverse array of edge-case tasks.

Furthermore, relying strictly on static tools presents a severe security risk. The 2026 summit highlighted the emergence of machine-speed, "Living off the Land" AI attacks, where internal AI CLI tools are hijacked by rogue processes. Treating AI simply as software leaves systems vulnerable; they must be managed as identities with strict minimum privileges, cryptographic IDs, and robust "Kill Switches" to prevent reasoning drift from turning agents into digital predators.

This article tackles both the TSI limitation and the security imperative directly by building an agent that dynamically creates, safely tests, and executes original scripts to process varied tasks on the fly. When an AI encounters an edge-case task lacking a pre-existing tool, a true paradigm shift occurs if the AI can automatically generate the exact tools it needs in real-time. By dynamically generating code and executing it in a secure, least-privilege sandbox, we protect the enterprise from unverified execution paths while expanding the spectrum of successfully executable tasks exponentially. I have previously explored this groundbreaking concept in the following articles:

In those articles, I demonstrated how tools could be dynamically created, safely executed in a sandbox, and thoroughly evaluated. Ref The execution results were retrieved using gas-fakes, a powerful emulation layer that allows Google Apps Script (GAS) projects to run natively on Node.js, effectively acting as an MCP server. We have advanced gas-fakes into the robust gas-fakes CLI. Simultaneously, deploying specialized AI agents has become an industry standard. For instance, the Gemini CLI can now seamlessly orchestrate these AI agents as subagents to handle complex, multi-step workflows.

Recently, I also published a comprehensive guide, "Orchestrating Agents via ADK for TypeScript and Gemini CLI."Ref I detailed practical scaffolding patterns, sophisticated multi-agent coordination strategies, and seamless integration techniques for deploying remote subagents within the Gemini CLI ecosystem. The architectural concepts established in that article serve as the foundational blueprint for developing the advanced agent system discussed here.

Specifically, I have engineered a robust AI agent equipped with a multi-agent framework designed to handle the entire lifecycle of a tool: writing the code, executing the script, validating the output, and summarizing the final results. I rigorously tested this framework as a subagent orchestrated by the Gemini CLI. For the tool's programming language, I selected Google Apps Script. While generative AI is often equipped with code interpreters capable of executing Python, I chose Google Apps Script because it is a low-code language featuring native integration with Google Workspace APIs, enabling seamless cloud automation. Ref For the execution platform, I utilized gas-fakes to ensure rapid, secure, and local runtime capabilities. Ref Looking ahead, I speculate that AI will eventually generate and execute tasks using entirely novel programming languages—languages highly optimized for AI comprehension, even if difficult for humans to read.

Technological Foundations

Google Apps Script (GAS): GAS is a highly versatile, low-code platform that makes it quick and easy to build business solutions that integrate, automate, and extend Google Workspace. By bridging services like Gmail, Drive, Docs, and Sheets, business users and developers alike can build highly customized workflows—no professional development experience required. GAS is available to everyone with a standard Gmail account or Enterprise Workspace tenant, making it a ubiquitous tool for cloud automation. Ref
gas-fakes: A powerful emulation layer that lets you run Apps Script projects on Node.js as if they were native. By translating proprietary GAS service calls into granular, authenticated Google API requests, it provides a secure, high-speed sandbox for local debugging, automated testing, and CI/CD pipeline integration. This eliminates the traditional latency of cloud-based GAS deployments and opens the door for AI agents to write, test, and execute Apps Script entirely within a localized Node environment.

Project Setup and Prerequisites

You can view the complete repository of sample scripts at https://github.com/tanaikech/autonomous-google-workspace-agent.

To follow along with this guide, ensure your environment meets the following requirements:

Node.js is installed and configured on your system.
Gemini CLI is installed and accessible via your terminal.

Install `autonomous-google-workspace-agent`

To retrieve and initialize the scripts, execute the following commands in your terminal:

git clone https://github.com/tanaikech/autonomous-google-workspace-agent
cd autonomous-google-workspace-agent
npm install

To use this agent, you must configure your Gemini API key as an environment variable:

export GEMINI_API_KEY=<YOUR_API_KEY_HERE>

Install gas-fakes

Detailed installation instructions can also be found athttps://github.com/brucemcpherson/gas-fakes/blob/main/gas-fakes-cli.md.

npm install -g @mcpher/gas-fakes

If you are using a consumer account (standard Gmail), use the Application Default Credentials (ADC) authorization. Run the following command in the autonomous-google-workspace-agent directory:

gas-fakes init --auth-type adc
gas-fakes auth

Check the .env file created by gas-fakes init --auth-type adc. Required scopes might need to be manually added to EXTRA_SCOPES if you encounter permission errors.

If you are using a Google Workspace enterprise account, you can use either ADC or Domain Wide Delegation (DWD). The DWD type is the default.

gas-fakes init --auth-type adc
gas-fakes auth

or simply:

gas-fakes init
gas-fakes auth

Install clasp

If you do not need to upload the generated Google Apps Script to Google Drive, you can skip this step. Official documentation is available at https://github.com/google/CLASP.

npm install -g @google/clasp

clasp login

Multi-Agent Architecture

You can review the complete architecture in my repository. This section details the agent structure.

`src/agent.ts`

This script establishes a multi-agent system consisting of 5 specialized subagents and 1 master orchestrator.

The comprehensive agent instructions are defined as follows:

const AGENT_INSTRUCTIONS = {
  ENVIRONMENT_CHECKER: `You are 'environment_checker'. Your objective is to verify if '@google/clasp' and '@mcpher/gas-fakes' are installed globally.
Use the 'check_cli_installation' tool to perform this check.
Report clearly to the orchestrator whether both, one, or none of them are installed.`,

  SCRIPT_WRITER: `You are 'script_writer', an expert Google Apps Script (GAS) developer.
Your primary objective is to write, debug, and refine Google Apps Script code to ensure it executes successfully within a local testing environment using the 'gas-fakes' library.

### Tool Usage Guidelines
1. Workspace Developer MCP:
   - Use this tool to reference the latest API specifications and documentation directly from Google Workspace. Ensure you are using the correct services, methods, and object structures.

2. Google Search (GOOGLE_SEARCH):
   - Search Priority: When looking for sample scripts or implementations, prioritize searching on Stack Overflow first (e.g., by appending "site:stackoverflow.com" to your query).
   - Broad Search: If sufficient information isn't found, perform broader searches (official tutorials, blogs, forums).
   - Troubleshooting: If the script fails, use Google Search to investigate specific error messages or understand specific behaviors of the 'gas-fakes' environment.

### Code Generation & Output Rules
1. Executable Code Block: Your output MUST strictly include the complete, runnable TypeScript or JavaScript code enclosed in a standard markdown code block.
2. 'gas-fakes' Context: Write your code assuming it is executed in the 'gas-fakes' environment. Keep in mind that certain advanced features might have mocked limitations.
3. Entry Point Invocation: Since the code will be executed as a direct string, you MUST ensure that the main entry function is explicitly called at the very bottom of your script (e.g., \`function main() { /* logic */ } main();\`).

### Error Handling & Iteration
- When reported a failure from the previous step, carefully analyze the provided stderr/stdout execution logs.
- Identify the exact root cause (syntax error, API payload issue, missing permissions, etc.).
- Always provide the fully corrected and executable code block in your response.`,

  SCRIPT_EXECUTOR: (
    schemaStr: string,
  ) => `You are 'script_executor', an expert testing agent responsible for verifying Google Apps Script (GAS) code.
Your objective is to execute the provided script locally using the 'run_gas_in_sandbox' tool and report the exact results to the 'script_writer'.

### Tool Usage Guidelines ('run_gas_in_sandbox')
1. Script Execution Target:
   - Provide the direct GAS code string in the 'script' argument.
   - IMPORTANT: Ensure the entry function is called at the end of the string.

2. Sandbox Configurations ('useSandbox' and 'json'):
   - Read the user's prompt carefully. If the prompt explicitly states NOT to use the sandbox, set 'useSandbox' to false. Otherwise, you MUST set 'useSandbox' to true (default behavior).
   - If 'useSandbox' is true, you MUST pass a JSON configuration string via the 'json' argument to define the sandbox permissions.
   - Construct the 'json' argument strictly according to this JSON schema:
${schemaStr}
   - Include all necessary method names in 'whitelistServices' to avoid permission errors.
   - If 'useSandbox' is false, the 'json' argument is not required and can be left empty.

### Evaluation & Output Rules
1. Execution Succeeded: If the tool returns successfully, return 'SUCCESS' along with the complete stdout execution logs.
2. Execution Failed: If the tool indicates an error, return 'FAILED' along with the exact stderr/stdout output.
3. Security Notice: You MUST explicitly state in your output whether the Google Apps Script was executed "WITH the sandbox" or "WITHOUT the sandbox".`,

  SCRIPT_UPLOADER: `You are 'script_uploader', an expert at managing Google Apps Script projects on Google Drive using the 'clasp' CLI via MCP.
Your primary objective is to upload (push), download (pull), or create (create) GAS projects directly on Google Drive.

### Usage Guidelines & Strict File Operation Rules:
- The orchestrator will invoke you only if '@google/clasp' is confirmed to be installed.
- **Uploading a Script (MANDATORY WORKFLOW)**:
  When uploading a file using clasp, you MUST follow these precise steps:
  1. Create the project via clasp (if a new directory is needed).
  2. **Save the Script**: Use the 'save_script_file' tool to save the generated script as a file (e.g., .js or .gs) inside the directory created by clasp.
  3. **Execute Push**: Only AFTER the file has been successfully saved, execute the clasp push command to upload it.
- Ensure to handle authentication or missing project contexts appropriately.
- Report the detailed outcome of your file creation and clasp operations.`,

  SUMMARY: `Summarize the final deliverables in the following format:
1. Execution Summary (Whether it succeeded, was skipped, and what processes were executed).
2. Final Script Code (Clean code block, ready to be copied and used).
3. Execution Results / Data. You MUST explicitly mention whether the script was executed WITH a sandbox or WITHOUT a sandbox.
4. System Guidance (Include any specific guidance required from the orchestrator regarding missing CLIs or Drive sync capabilities).`,

  ORCHESTRATOR: `You are a Senior Multi-Agent Orchestrator and the leader coordinating multiple sub-agents. Your primary role is to deeply understand the given prompt, select the optimal sub-agents, and execute them in the optimal order to autonomously develop, test, and manage Google Apps Script (GAS) solutions, ensuring the prompt's tasks are accomplished reliably.

### Handling Missing Information (Crucial Requirement)
If any information required to achieve the task in the prompt is missing (e.g., specific requirements, Google Drive Folder IDs, target service names), you MUST provide feedback to the user requesting the necessary details. Once the user provides the missing information, you must resume the workflow and aim to achieve the prompt's task based on the added context.

### Available Sub-Agents & Expertise:
- "environment_checker" (agent0): Checks if '@google/clasp' and '@mcpher/gas-fakes' are installed.
- "script_writer" (agent1): References Google Workspace API docs and writes gas-fakes compatible code.
- "script_executor" (agent2): Simulates script execution in the gas-fakes environment (with or without a sandbox).
- "script_uploader" (agent3): Manages GAS projects via clasp and handles file saves prior to upload.
- "summary_agent" (agent4): Formats the final deliverables into a structured report.

### Operational Protocols:
1. **Selection & Purpose**: Clearly identify which agent(s) you are using and why. You must determine the optimal sequence of execution based on the task's complexity.
2. **Execution Strategy**:
   - **Environment Check (Mandatory First Step)**:
     - BEFORE invoking 'script_executor' or 'script_uploader', you MUST use 'environment_checker' to verify installations.
     - **If '@mcpher/gas-fakes' is NOT installed**: Skip execution, return ONLY the generated script, and instruct the user to install it via \`npm -g install @mcpher/gas-fakes\`.
     - **If '@google/clasp' IS installed**: Explicitly state that the user can upload, download, or create scripts directly on Google Drive.
     - **Clasp Independence**: Inform the user that creating and executing GAS locally is still possible as long as 'gas-fakes' is installed.

   - **Direct Execution (If provided by the user)**:
     - If the user provides Google Apps Script code directly in their prompt and asks to execute it, you can bypass the 'script_writer' and pass the provided script directly to the 'script_executor'.

   - **Iterative Workflow (If gas-fakes is installed)**:
     1. Ask 'script_writer' to generate code.
     2. Pass the code to 'script_executor' for simulation.
     3. If 'FAILED', pass the details back to 'script_writer' for regeneration.
     4. **Constraint**: The cycle has a MAXIMUM limit of 5 retries.

   - **Script Management (Optional, if clasp is installed)**:
     - Use 'script_uploader' if project creation/upload is requested. Ensure you communicate that files will be generated before pushing.

   - **Serial (Finalization)**:
     Once execution succeeds or limits are reached, invoke 'summary_agent' to generate the final guaranteed output.

3. **Reporting (Strict Requirement)**: You MUST start your response with an "Execution Log".

### Mandatory Output Format (in English):
---
## Execution Log
- **Agents Involved**:[List names of agents used]
- **Execution Strategy**:[Iterative / Serial / Direct Execution / Awaiting User Input]
- **Purpose & Logic**:[Briefly explain the coordination, environment check results, retry cycles, or reason for requesting missing information]

## Result[Provide the comprehensive final answer in the requested language, incorporating the output from summary_agent, and the necessary feedback about missing CLIs, Drive capabilities, or missing information required from the user]`,
};

`environment_checker`

const environmentCheckerAgent = new LlmAgent({
  name: "environment_checker",
  model: DEFAULT_MODEL,
  description: ""
    "Checks if the required CLI tools (@google/clasp and @mcpher/gas-fakes) are installed globally.",
  instruction: AGENT_INSTRUCTIONS.ENVIRONMENT_CHECKER,
  tools: [checkCliInstallationTool],
});

This agent verifies whether the necessary dependencies are properly installed in the host environment.

`script_writer`

const scriptWriterAgent = new LlmAgent({
  name: "script_writer",
  model: DEFAULT_MODEL,
  description: ""
    "References Google Workspace API specifications via MCP and generates code for the gas-fakes environment. Analyzes and fixes errors.",
  instruction: AGENT_INSTRUCTIONS.SCRIPT_WRITER,
  tools:[
    new MCPToolset({
      type: "StreamableHTTPConnectionParams",
      url: "https://workspace-developer.goog/mcp",
    }),
    GOOGLE_SEARCH,
  ],
  generateContentConfig: {
    toolConfig: {
      includeServerSideToolInvocations: true,
    },
  },
});

Tools are dynamically generated using Google Apps Script, ensuring high affinity with Google Workspace. To enable GOOGLE_SEARCH alongside custom capabilities, includeServerSideToolInvocations: true must be specified.

`script_executor`

const scriptExecutorAgent = new LlmAgent({
  name: "script_executor",
  model: DEFAULT_MODEL,
  description: ""
    "Simulates script execution securely in the gas-fakes sandbox environment and handles error reporting.",
  instruction: AGENT_INSTRUCTIONS.SCRIPT_EXECUTOR(
    JSON.stringify(SANDBOX_PERMISSION_SCHEMA),
  ),
  tools: [runGasInSandboxTool],
});

The created Google Apps Script is run using gas-fakes within a strict sandbox. This protects the wider enterprise environment from unauthorized access. gas-fakes is run by the gas-fakes CLI. You can also select with and without the sandbox for executing Google Apps Script. In some cases, the sandbox might not be required to be used.

`script_uploader`

const scriptUploaderAgent = new LlmAgent({
  name: "script_uploader",
  model: DEFAULT_MODEL,
  description: ""
    "Uploads, downloads, or creates Google Apps Script projects on Google Drive using clasp. Used only when @google/clasp is installed.",
  instruction: AGENT_INSTRUCTIONS.SCRIPT_UPLOADER,
  tools:[
    new MCPToolset({
      type: "StdioConnectionParams",
      serverParams: {
        command: "clasp",
        args: ["mcp"],
      },
    }),
    saveScriptFileTool,
  ],
});

If clasp is installed, this agent pushes the validated scripts directly to Google Drive. However, even without clasp, the generated tools can still be executed locally.

`summary_agent`

const summaryAgent = new LlmAgent({
  name: "summary_agent",
  model: DEFAULT_MODEL,
  description: "\"Formats the final deliverables into a structured report.\","
  instruction: AGENT_INSTRUCTIONS.SUMMARY,
});

This final agent synthesizes the execution logs, source code, and outcome data into a clean, readable report for the user.

`autonomous_gas_orchestrator`

export const autonomousGoogleWorkspaceAgent = new LlmAgent({
  name: "autonomous-google-workspace-agent",
  model: DEFAULT_MODEL,
  description: ""
    "Senior Orchestrator managing GAS creation, environment check, execution, clasp integration, and up to 5 retries.",
  instruction: AGENT_INSTRUCTIONS.ORCHESTRATOR,
  subAgents:[
    environmentCheckerAgent,
    scriptWriterAgent,
    scriptExecutorAgent,
    scriptUploaderAgent,
    summaryAgent,
  ],
});

This is the central agent that intelligently delegates tasks and manages the lifecycle of the entire dynamic generation process.

`src/a2aserver.ts`

This script is used for launching autonomous-google-workspace-agent as an A2A server.


/**
 * A2A server
 */
import { LlmAgent, toA2a } from "@google/adk";
import express from "express";

import { autonomousGasOrchestratorAgent as targetAgent } from "./agent.ts";

const port = 8000;
const host = "localhost";

async function startServer() {
  const app = express();

  app.use((req, res, next) => {
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
    next();
  });

  // For A2A
  await toA2a(targetAgent, {
    protocol: "http",
    basePath: "",
    host,
    port,
    app,
  });

  app.listen(port, () => {
    console.log(`Server started on http://${host}:${port}`);
    console.log(`Try: http://${host}:${port}/.well-known/agent-card.json`);
  });
}

startServer().catch(console.error);

Launching the Agent System

This framework can function both as a standalone web server and as a subagent linked to the Gemini CLI.

Launch the Web server:

npm run web

$ npm run web

> adk-full-samples@1.0.0 web
> npx adk web src/agent.ts


+-----------------------------------------------------------------------------+
| ADK API Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+

You can now interact with the web interface by navigating to http://localhost:8000 in your browser.

Launch the A2A server:

npm run a2a

Upon execution, you will see a confirmation output in your terminal indicating the server has started successfully:

$ npm run a2a

> adk-full-samples@1.0.0 a2a
> npx tsx src/a2aserver.ts

Server started on http://localhost:8000
Try: http://localhost:8000/.well-known/agent-card.json

To configure this A2A server as a subagent for the Gemini CLI, create or update .gemini/agents/autonomous-google-workspace-agent.md with the following:

---
kind: remote
name: autonomous-google-workspace-agent
agent_card_url: http://localhost:8000/.well-known/agent-card.json
---

You can inspect the agent card specifications by opening the provided URL (http://localhost:8000/.well-known/agent-card.json) in your browser.

Testing and Use Cases

Once correctly configured, launch the Gemini CLI. You can now delegate complex natural language instructions to your autonomous-google-workspace-agent. The system will automatically construct necessary scripts, execute them, iterate on errors, and return validated results.

1. Dynamic Exchange Rate Retrieval via GOOGLEFINANCE

Prompt:

Create a new Google Spreadsheet by putting a formula `=GOOGLEFINANCE("CURRENCY:USDJPY")` in cell "A1" of the first sheet. Then, get and show the value of cell "A1". (Note: `gas-fakes` has no `getActiveSheet()` method. In this case, use `getSheets()[0]`.)

The system successfully generated the script, ran it safely within the sandbox, and fetched the financial data directly from Google Sheets.

2. Automated Spreadsheet Initialization with Dummy Data

Prompt:

In this case, the script is not required to be executed in a sandbox. Create a new Google Spreadsheet and add the headers 'Date', 'Task Name', and 'Status' to cells A1:C1. Then, populate the next 3 rows with dummy task data. Finally, execute the script, retrieve the URL of the created spreadsheet, and provide it to me.

Following the execution, the agent instantiated the Google Sheet and correctly populated it with the requested structured dummy data.

3. Dynamic Calendar Event Scheduling with Autonomous Error Correction

Prompt:

**Write** and **execute** a script to create a Google Calendar event titled 'Monthly Team Meeting' for exactly one hour starting at 10:00 AM on the second Monday of next month. If you encounter any API specification errors or logic issues with the date calculation, investigate the cause, fix the code, and retry until the execution is successful. The calendar ID is '{your calendar ID}'.

The orchestrator dynamically calculated the date logic, interfaced with the Calendar API, handled temporary validation failures gracefully via the script_writer, and successfully scheduled the event.

4. GAS Development Workflow: Document Highlighter and Google Drive Deployment

Prompt:

Create a GAS custom function that highlights a specific keyword (e.g., 'TODO') in yellow within a Google Document, and verify its execution in the local sandbox. Once successful, create a new GAS project named 'Doc Highlighter Project' on Google Drive, save the file locally, and upload (push) it using clasp.

The script successfully manipulated the Google Document and utilized the script_uploader agent to push the project securely to Google Drive.

5. Automated Weekly Drive Report: Filtered File Aggregation and Gmail Synchronization

Prompt:

In this case, the script is not required to be executed in a sandbox. Retrieve a list of files in a folder of folder ID '{folder ID}' of my Google Drive that were created or modified in the last week. Then, create a draft email in Gmail containing a list of these file names and their URLs as a weekly report. Set the recipient to 'tanaike@hotmail.com' and the subject to 'Weekly Drive Files Report'.

The result was an accurately compiled draft email directly saved to Gmail, complete with proper formatting and links.

Weekly Drive Files Report

The following files were created or modified in the last 7 days:

- Name: sample slide 1
  URL: https://docs.google.com/presentation/d/{file ID 1}/edit?usp=drivesdk

- Name: sample spreadsheet 1
  URL: https://docs.google.com/spreadsheets/d/{file ID 2}/edit?usp=drivesdk

- Name: sample document 1
  URL: https://docs.google.com/document/d/{file ID 3}/edit?usp=drivesdk

Deployment Considerations

While this article demonstrates running the A2A server locally for testing, deploying this multi-agent architecture to fully managed serverless environments—such as Google Cloud Run—will vastly increase its operational capacity. Adopting a cloud-native hosting strategy ensures the A2A server can automatically scale to accommodate high-concurrency enterprise workflows without hardware bottlenecks.

Summary

The transition to the Agentic Enterprise means AI models now act as autonomous coworkers, requiring a shift from static software deployments to dynamic identity management and task execution.
Tool Space Interference (TSI) degrades inference accuracy when LLMs are overloaded with predefined tools, a limitation effectively bypassed by enabling agents to dynamically write and execute their own scripts in real-time.
Utilizing Google Apps Script alongside the gas-fakes emulation layer provides AI agents with a secure, high-speed, and sandboxed local runtime to safely develop and test enterprise workflows.
A robust multi-agent architecture seamlessly orchestrated via the Gemini CLI can independently handle the entire tool lifecycle: code generation, secure sandbox testing, execution validation, and Google Drive deployment.
Expanding this framework into serverless cloud environments not only addresses the massive computational scale of modern AI but also fortifies security by isolating dynamic tool execution from core organizational infrastructure.

Orchestrating Agents via ADK for TypeScript and Gemini CLI

Tanaike — Tue, 21 Apr 2026 05:22:52 +0000

Abstract

Explore how to build and orchestrate production-ready, type-safe AI agents using Google's TypeScript Agent Development Kit (ADK). This guide provides practical scaffolding patterns, multi-agent coordination strategies, and seamless integration techniques for deploying remote subagents within the Gemini CLI ecosystem.

Introduction

As the artificial intelligence landscape rapidly evolves, modern generative AI increasingly relies on autonomous agents equipped with sophisticated components, including system instructions, specialized skills, and Model Context Protocol (MCP) servers. To facilitate the development of such AI-driven applications, Google has released the Agent Development Kit (ADK) across multiple programming languages Ref. Among these, the ADK for TypeScript Ref offers distinct advantages for modern engineering paradigms:

Full-Stack Synergy: Essential for modern web applications (e.g., Next.js or React), allowing developers to share types and logic between the frontend and backend to streamline the development lifecycle.
Scalability & Reliability: Crucial for large-scale enterprise systems, where static typing and robust refactoring tools ensure long-term maintainability and minimize runtime errors.
High Concurrency: Highly effective for agents that must efficiently handle numerous asynchronous events, streaming responses, and real-time user interactions.

Despite these architectural merits, a critical gap exists in ecosystem maturity. While Python remains the "Gold Standard" with first-class support in AI research, TypeScript is often viewed as an emerging platform. Although there is a rising demand for integrating AI agents into enterprise web applications, quantitative data indicates that TypeScript-specific ADK resources account for less than 5% of the total search volume compared to the Python-centric ecosystem. This overwhelming scarcity of documentation and community-driven knowledge presents a significant barrier to entry for full-stack developers.

To fill this critical information void and catalyze the development of type-safe, production-ready AI agents, this article provides a comprehensive framework and practical scaffolding patterns using the TypeScript ADK. Furthermore, it introduces advanced methodologies for establishing a multi-agent architecture. Specifically, this article demonstrates how to seamlessly integrate these custom-built TypeScript agents as remote subagents within the Gemini CLI, leveraging agent-to-agent protocols to enable scalable, interconnected AI workflows.

Project Setup and Prerequisites

You can view the complete repository of sample scripts athttps://github.com/tanaikech/ts-multi-agent-scaffolding.

To follow along with this guide, ensure your environment meets the following requirements:

Node.js is installed and configured on your system.
Gemini CLI is installed and accessible via your terminal.

To retrieve and initialize the sample scripts, execute the following commands in your terminal:

git clone https://github.com/tanaikech/ts-multi-agent-scaffolding
cd ts-multi-agent-scaffolding
npm install

Building Specialized AI Agents

The following samples demonstrate how to construct specialized, single-purpose agents using the TypeScript ADK. Each agent is designed to handle a distinct operational domain.

1. General Logic Analyst (Sample 1)

Focus: Logical analysis, summarization, drafting, and evaluation.

This foundational agent focuses on parsing text and validating logical structures without relying on external API tools.

sample1/agent.ts

import { LlmAgent } from "@google/adk";

export const rootAgent = new LlmAgent({
  name: "general_logic_analyst",
  description:
    "Handles general reasoning, text summarization, and logical validation of information.",
  model: "gemini-3-flash-preview",
  instruction: `You are a Senior Logic Analyst and General Assistant. 
Your role is to process general queries and synthesize information from various sources.

### Key Responsibilities:
1. **Summarization**: Condense long texts or technical logs into concise, actionable insights.
2. **Logical Validation**: Check if a given statement or piece of code follows logical consistency.
3. **Drafting**: Create professional emails, reports, or documentation based on raw data.
4. **Knowledge Retrieval**: Answer general knowledge questions using your internal training data.

### Constraints:
- Keep responses professional and structured.
- If you receive data from other agents (like weather or file logs), focus on explaining the *implications* of that data.
- Do not invent facts; if information is missing, clearly state so.

### Output Style:
Use bullet points for clarity and always provide a brief "Conclusion" or "Next Steps" section at the end of long responses.`,
});

Launch the agent as a local web server:

npm run sample1

Access http://localhost:8000 in your browser to interact with the web interface.

2. API Manager for Real-Time Data (Sample 2)

Focus: Real-time data retrieval via external APIs (Weather, Exchange Rates).

This agent leverages custom tools built with Zod schema validation to dynamically fetch external data, demonstrating how AI can interact with the real world.

sample2/agent.ts

/**
 * agent.ts
 * AI Agent definition with dynamic date context and Tool definitions.
 *
 * npx adk web
 */
import { LlmAgent, FunctionTool } from "@google/adk";
import { z } from "zod";

// ==========================================
// 1. Dynamic Date Helper
// ==========================================
const now = new Date();
const currentDateTime = now.toLocaleString("ja-JP", {
  year: "numeric",
  month: "2-digit",
  day: "2-digit",
  hour: "2-digit",
  minute: "2-digit",
  timeZone: "Asia/Tokyo",
});

// ==========================================
// 2. Tools Definition
// ==========================================

const getExchangeRateTool = new FunctionTool({
  name: "get_exchange_rate",
  description: "Use this to get current exchange rate between currencies.",
  parameters: z.object({
    currency_from: z
      .string()
      .default("USD")
      .describe("Source currency (major currency)."),
    currency_to: z
      .string()
      .default("EUR")
      .describe("Destination currency (major currency)."),
    currency_date: z
      .string()
      .default("latest")
      .describe("Date of the currency in ISO format (YYYY-MM-DD) or 'latest'."),
  }),
  execute: async ({ currency_from, currency_to, currency_date }) => {
    try {
      const response = await fetch(
        `https://api.frankfurter.app/${currency_date}?from=${currency_from}&to=${currency_to}`,
      );
      if (!response.ok) throw new Error(`API status: ${response.status}`);
      const data: any = await response.json();
      const rate = data.rates[currency_to];
      return[
        `The raw data from the API is ${JSON.stringify(data)}.`,
        `The currency rate at ${currency_date} from "${currency_from}" to "${currency_to}" is ${rate}.`,
      ].join("\n");
    } catch (error: any) {
      return `Error retrieving exchange rate: ${error.message}`;
    }
  },
});

const getCurrentWeatherTool = new FunctionTool({
  name: "get_current_weather",
  description:
    "Use this to get the weather using the latitude and the longitude.",
  parameters: z.object({
    latitude: z.number().describe("The latitude of the inputed location."),
    longitude: z.number().describe("The longitude of the inputed location."),
    date: z
      .string()
      .describe("Date for searching the weather. Format: 'yyyy-MM-dd HH:mm'"),
    timezone: z.string().describe("The timezone (e.g., 'Asia/Tokyo')."),
  }),
  execute: async ({ latitude, longitude, date, timezone }) => {
    const codeMap: Record<number, string> = {
      0: "Clear sky",
      1: "Mainly clear, partly cloudy, and overcast",
      2: "Mainly clear, partly cloudy, and overcast",
      3: "Mainly clear, partly cloudy, and overcast",
      45: "Fog and depositing rime fog",
      48: "Fog and depositing rime fog",
      51: "Drizzle: Light, moderate, and dense intensity",
      53: "Drizzle: Light, moderate, and dense intensity",
      55: "Drizzle: Light, moderate, and dense intensity",
      56: "Freezing Drizzle: Light and dense intensity",
      57: "Freezing Drizzle: Light and dense intensity",
      61: "Rain: Slight, moderate and heavy intensity",
      63: "Rain: Slight, moderate and heavy intensity",
      65: "Rain: Slight, moderate and heavy intensity",
      66: "Freezing Rain: Light and heavy intensity",
      67: "Freezing Rain: Light and heavy intensity",
      71: "Snow fall: Slight, moderate, and heavy intensity",
      73: "Snow fall: Slight, moderate, and heavy intensity",
      75: "Snow fall: Slight, moderate, and heavy intensity",
      77: "Snow grains",
      80: "Rain showers: Slight, moderate, and violent",
      81: "Rain showers: Slight, moderate, and violent",
      82: "Rain showers: Slight, moderate, and violent",
      85: "Snow showers slight and heavy",
      86: "Snow showers slight and heavy",
      95: "Thunderstorm: Slight or moderate",
      96: "Thunderstorm with slight and heavy hail",
      99: "Thunderstorm with slight and heavy hail",
    };
    try {
      const endpoint = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&hourly=weather_code&timezone=${encodeURIComponent(timezone)}`;
      const response = await fetch(endpoint);
      const data: any = await response.json();
      const targetTime = date.replace(" ", "T").trim();
      const widx = data.hourly.time.indexOf(targetTime);
      if (widx !== -1) {
        return codeMap[data.hourly.weather_code[widx]] || "Unknown condition.";
      }
      return "No weather data found for the specified time.";
    } catch (error: any) {
      return `Error retrieving weather: ${error.message}`;
    }
  },
});

// ==========================================
// 3. Agent Definition
// ==========================================

export const rootAgent = new LlmAgent({
  name: "api_manager_agent",
  description: "An agent that manages currency and weather API tools.",
  model: "gemini-3-flash-preview",
  instruction: `You are a professional API Manager.
Current date and time is ${currentDateTime}. Use this information to calculate relative dates.
1. Use 'get_exchange_rate' for currency queries.
2. Use 'get_current_weather' for weather queries. "date" is required to be "yyyy-MM-dd HH:00".
3. Provide precise, helpful responses based on tool outputs.`,
  tools: [getExchangeRateTool, getCurrentWeatherTool],
});

Launch the agent:

npm run sample2

Access http://localhost:8000 to interact with this API-connected agent.

3. Local Filesystem Expert via MCP (Sample 3)

Focus: Local filesystem operations via MCP.

By integrating the Model Context Protocol (MCP), this agent gains secure, managed access to the local filesystem. For this sample, target files should be placed in the sample3/sample directory.

sample3/agent.ts

import { LlmAgent, MCPToolset } from "@google/adk";

export const rootAgent = new LlmAgent({
  name: "local_file_expert",
  model: "gemini-3-flash-preview",
  instruction:
    "You are a local file manager. Help users organize and understand their files. Here, you can access only a directory of 'sample' given by the MCP server.",
  tools:[
    new MCPToolset({
      type: "StdioConnectionParams",
      serverParams: {
        command: "npx",
        args:[
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "sample3/sample",
        ],
      },
    }),
  ],
});

Launch the agent:

npm run sample3

Access http://localhost:8000 to instruct the agent to read and organize your local files.

4. Google Workspace Technical Guide via MCP (Sample 4)

Focus: Technical support for Google Workspace APIs and Apps Script (GAS).

This agent utilizes a remote MCP server to stream up-to-date Workspace documentation, creating a highly specialized technical support assistant.

sample4/agent.ts

import { LlmAgent, MCPToolset } from "@google/adk";

export const rootAgent = new LlmAgent({
  name: "workspace_doc_guide",
  model: "gemini-3-flash-preview",
  instruction:
    "You are a Google Workspace expert. Use the provided tools to answer questions about Apps Script and Workspace APIs.",
  tools:[
    new MCPToolset({
      type: "StreamableHTTPConnectionParams",
      url: "https://workspace-developer.goog/mcp",
    }),
  ],
});

Launch the agent:

npm run sample4

Access http://localhost:8000 to query the agent regarding complex Workspace developer documentation.

Orchestrating Multi-Agent Workflows

5. Multi-Agent Orchestrator (Sample 5)

Focus: Coordination of multiple agents using serial, parallel, and iterative execution strategies.

Once individual subagents are established, they can be orchestrated by a primary agent. This orchestrator acts as a dynamic manager, delegating tasks to the specialized subagents (Agents 1 through 4) based on the user's prompt.

sample5/agent.ts

import { LlmAgent } from "@google/adk";

import { rootAgent as agent1 } from "../sample1/agent.ts";
import { rootAgent as agent2 } from "../sample2/agent.ts";
import { rootAgent as agent3 } from "../sample3/agent.ts";
import { rootAgent as agent4 } from "../sample4/agent.ts";

export const rootAgent = new LlmAgent({
  name: "multi_agent_orchestrator",
  description:
    "Advanced orchestrator capable of serial, parallel, and iterative task execution.",
  model: "gemini-3-flash-preview",
  instruction: `You are a Senior Multi-Agent Orchestrator. Your role is to analyze user prompts and delegate tasks to the most suitable sub-agents.

### Available Sub-Agents & Expertise:
- "general_logic_analyst" (agent1): Logic validation, summarization, and final report drafting.
- "api_manager_agent" (agent2): Real-time currency exchange and weather data retrieval.
- "local_file_expert" (agent3): Local file system operations within the workspace.
- "workspace_doc_guide" (agent4): Google Workspace APIs and Apps Script documentation.

### Operational Protocols:
1. **Selection & Purpose**: Clearly identify which agent(s) you are using and why.
2. **Execution Strategy**:
   - **Serial**: When one agent's output is needed as input for another.
   - **Parallel**: When multiple independent data points are needed.
   - **Iterative**: When you need to re-run an agent or call a new one based on fresh findings.
3. **Reporting (Strict Requirement)**: You MUST start your response with an "Execution Log".

### Mandatory Output Format (in English):
---
## Execution Log
- **Agents Involved**: [List names of agents used]
- **Execution Strategy**: [Single / Serial / Parallel / Iterative]
- **Purpose & Logic**:[Briefly explain why these agents were chosen and how they were coordinated]

## Result[Provide the comprehensive final answer in the language requested by the user]
---`,
  subAgents:[agent1, agent2, agent3, agent4],
});

Launch the orchestrator:

npm run sample5

Access http://localhost:8000 to witness complex routing and multi-agent problem-solving in action.

Agent-to-Agent (A2A) Integration with Gemini CLI

6. A2A Server Implementation (Sample 6)

Focus: Exposing the multi-agent system to external clients via an A2A server.

To fully integrate these TypeScript agents into enterprise workflows, we can expose them as an Agent-to-Agent (A2A) service. This allows tools like the Gemini CLI to communicate directly with our orchestrator.

sample6/a2aserver.ts

/**
 * sample6/a2aserver.ts
 *
 * A2A server that dynamically loads agents.
 * Usage: SAMPLE_TYPE=5 npx tsx sample6/a2aserver.ts
 */
import { LlmAgent, toA2a } from "@google/adk";
import express from "express";
import "dotenv/config";

import { rootAgent as agent1 } from "../sample1/agent.ts";
import { rootAgent as agent2 } from "../sample2/agent.ts";
import { rootAgent as agent3 } from "../sample3/agent.ts";
import { rootAgent as agent4 } from "../sample4/agent.ts";
import { rootAgent as agent5 } from "../sample5/agent.ts";

const port = 8000;
const host = "localhost";

const agents: Record<string, LlmAgent> = {
  "1": agent1,
  "2": agent2,
  "3": agent3,
  "4": agent4,
  "5": agent5,
};

async function startServer() {
  const type = process.env.SAMPLE_TYPE || "5";
  const targetAgent = agents[type];

  if (!targetAgent) {
    console.error(`Invalid SAMPLE_TYPE: ${type}.`);
    process.exit(1);
  }

  const app = express();

  app.use((req, res, next) => {
    console.log(`[${new Date().toISOString()}] ${req.method} ${req.url}`);
    next();
  });

  // For A2A
  await toA2a(targetAgent, {
    protocol: "http",
    basePath: "",
    host,
    port,
    app,
  });

  app.listen(port, () => {
    console.log(`Server started on http://${host}:${port}`);
    console.log(`Try: http://${host}:${port}/.well-known/agent-card.json`);
  });
}

startServer().catch(console.error);

Launch the A2A server:

npm run sample6

Upon execution, you will see a confirmation output in your terminal indicating the server and MCP roots have started successfully:

$ npm run sample6

> adk-full-samples@1.0.0 sample6
> npx tsx sample6/a2aserver.ts

Secure MCP Filesystem Server running on stdio
Client does not support MCP Roots, using allowed directories set from server args:[ '/{your directory}/sample3/sample' ]
Server started on http://localhost:8000
Try: http://localhost:8000/.well-known/agent-card.json

To configure this A2A server as a subagent for the Gemini CLI, create or update .gemini/agents/sample-adk-agent.md with the following configuration:

---
kind: remote
name: sample-adk-agent
agent_card_url: http://localhost:8000/.well-known/agent-card.json
---

Once configured, launch the Gemini CLI. You will now be able to delegate complex tasks directly to your sample-adk-agent subagent:

Additionally, you can inspect the agent card specifications directly by navigating to the provided URL (http://localhost:8000/.well-known/agent-card.json) in your browser.

While this article demonstrates running the A2A server in a local environment for testing purposes, deploying this architecture to fully managed serverless platforms—such as Google Cloud Run or similar services—will significantly increase its scalability. Cloud-native hosting ensures the A2A server can automatically scale to meet the demands of high-concurrency enterprise workloads.

Future Outlook

It is important to note that the TypeScript version of the ADK is still actively under development. As the framework evolves, developers can anticipate frequent updates that will introduce further usability improvements, streamlined APIs, and robust new features, continuing to close the maturity gap with its Python counterpart.

Summary

Google's TypeScript ADK provides an optimal foundation for building highly concurrent, type-safe AI agents tailored for modern full-stack web architectures.
Specialized, single-purpose subagents drastically improve output reliability, efficiently handling discrete tasks ranging from logical validation to real-time API integrations.
The Model Context Protocol (MCP) securely extends agent capabilities, enabling direct interactions with local filesystems and remote knowledge bases without compromising security.
Advanced orchestration models allow complex workflows to be dynamically distributed across multiple agents using serial, parallel, or iterative execution strategies.
Implementing an Agent-to-Agent (A2A) server allows seamless external integration, transforming custom TypeScript agents into scalable remote subagents executable natively within the Gemini CLI.

Integrating Remote Subagents Built by Google Apps Script with Gemini CLI

Tanaike — Mon, 13 Apr 2026 05:21:33 +0000

Abstract

This article explores integrating remote subagents built with Google Apps Script into the Gemini CLI using the Agent-to-Agent (A2A) protocol. It demonstrates how bypassing standard authentication via local agent cards enables seamless execution of complex workflows while effectively overcoming Tool Space Interference (TSI) for massive toolsets.

Introduction

Recently, remote subagent support was introduced to the Gemini CLI. Ref With this feature, the Gemini CLI connects to remote subagents using the Agent-to-Agent (A2A) protocol, expanding its capabilities by delegating tasks to external services. I have previously published several articles discussing the A2A server architecture:

These articles introduce A2A servers built with Google Apps Script (GAS) Web Apps. GAS serves as an ideal foundation for A2A servers because its low-code environment is easily navigable by both human developers and generative AI. Furthermore, GAS is accessible to anyone with a Google account and offers native affinity with Google Workspace. It simplifies complex operations by facilitating seamless OAuth scope authentication and providing direct access to Google APIs via Advanced Google Services.

By utilizing GAS, developers can rapidly deploy lightweight, category-specific agents that communicate via the A2A protocol. This forms a robust mesh of capabilities without the infrastructure overhead of traditional server environments.

An excellent foundational article on the basic methods for using subagents with the Gemini CLI was recently published by Romin Irani. Ref Building on that foundation, this article introduces a specific approach for securely and natively integrating remote subagents built by Google Apps Script Web Apps with the Gemini CLI.

Demonstration

Prerequisites and Repository

This article assumes the following prerequisites:

You have installed and configured the latest Gemini CLI.
You have an active API key for the Gemini API.

You can view all the sample scripts used in this article at the following repository:https://github.com/tanaikech/gemini-cli-gas-a2a-subagents

1. Basic Integration: Connecting Gemini CLI to a GAS-based A2A Server

This section demonstrates a simple test to confirm the connection between the Gemini CLI and a remote subagent (A2A server) built with Google Apps Script.

1.1 Building the A2A Server

1.1.1 Google Apps Script Preparation

Copy Google Apps Script

Log in to your Google account and access the following URL to view the Google Apps Script project dashboard. Click the copy icon in the top right corner to copy the standalone script to your root folder:https://script.google.com/home/projects/1vcbr7E7XeJafVGdV6QKEgsr9H0-Vl_zLOQSjgysDCs2olWlrE43HGOne

Manual Preparation of Google Apps Script

If you prefer to create the sample A2A server manually, follow these steps:

Create a new standalone Google Apps Script project. Ref

appsscript.json

Overwrite appsscript.json with the following JSON. Adjust timeZone to your local timezone.

{
  "timeZone": "Asia/Tokyo",
  "dependencies": {
    "enabledAdvancedServices": [],
    "libraries": [
      {
        "userSymbol": "MCPA2Aserver",
        "libraryId": "1xRlK6KPhqp374qAyumrtVXXNEtb7iZ_rD7yRuYxccQuYieKCCao9VuB6",
        "version": "0",
        "developmentMode": true
      }
    ]
  },
  "webapp": {
    "executeAs": "USER_DEPLOYING",
    "access": "ANYONE_ANONYMOUS"
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request"
  ]
}

MCPA2Aserver is a Google Apps Script library designed to consolidate Generative AI protocols into a single server solution. It enables developers to easily build and deploy servers supporting both the Model Context Protocol (MCP) and the Agent-to-Agent (A2A) protocol. The repository is available athttps://github.com/tanaikech/MCPA2Aserver-GAS-Library.

In this manifest file, only a scope https://www.googleapis.com/auth/script.external_request is set for using sample 2 skills. However, if you wish to use other scopes, please modify this accordingly.

code.gs

Copy and paste the following script into code.gs. Set your API key for using the Gemini API.

// --- Your variables ---
const object = {
  apiKey: "{apiKey}", // Your API key for using Gemini API.
  model: "models/gemini-3-flash-preview",
  accessKey: "sample", // If you want to use an access key for requesting Web Apps, please use this.
  // logSpreadsheetId: "{spreadsheetId}", // If you use this, the logs are stored to Google Spreadsheet.
};

// --- Entry Points ---
const doGet = (e) => main(e);
const doPost = (e) => main(e);

/**
 * Main Dispatcher Function
 * Routes the request to either A2A handler or MCP handler based on the payload or path.
 *
 * @param {EventObject} e - The event object from doGet/doPost
 * @return {ContentService.TextOutput} The JSON response
 */
function main(e) {
  const context = createServerContext_(); // Load sample tools.
  const m = MCPA2Aserver;
  m.a2a = true;
  m.apiKey = object.apiKey;
  m.model = object.model;
  if (object.accessKey) m.accessKey = object.accessKey;
  if (object.logSpreadsheetId) m.logSpreadsheetId = object.logSpreadsheetId;
  const res = m.main(e, context);
  return res;
}

/**
 * Please get the agent card from the following function.
 */
function getAgentCard() {
  const obj = createServerContext_();
  const agentCard = obj.A2AObj.agentCard();
  const disp = JSON.stringify(agentCard, null, 2)
    .split("\n")
    .map((e) => `  ${e}`)
    .join("\n");
  console.log(disp);
}

agent.gs

Create another script file named agent.gs and paste the following code. Make sure to update the url within agentCard with your Web App URL later.

function createServerContext_() {
  const functions = {
    params_: {
      get_exchange_rate: {
        description: "Use this to get current exchange rate.",
        parameters: {
          type: "object",
          properties: {
            currency_from: {
              type: "string",
              description: "Source currency (major currency). Default is USD.",
            },
            currency_to: {
              type: "string",
              description:
                "Destination currency (major currency). Default is EUR.",
            },
            currency_date: {
              type: "string",
              description:
                "Date of the currency. Default is latest. It should be ISO format (YYYY-MM-DD).",
            },
          },
          required: ["currency_from", "currency_to", "currency_date"],
        },
      },

      get_current_weather: {
        description: [
          "Use this to get the weather using the latitude and the longitude.",
          "At that time, convert the location to the latitude and the longitude and provide them to the function.",
          `The date is required to be included. The date format is "yyyy-MM-dd HH:mm"`,
          `If you cannot know the location, decide the location using the timezone.`,
        ].join("\n"),
        parameters: {
          type: "object",
          properties: {
            latitude: {
              type: "number",
              description: "The latitude of the inputed location.",
            },
            longitude: {
              type: "number",
              description: "The longitude of the inputed location.",
            },
            date: {
              type: "string",
              description: `Date for searching the weather. The date format is "yyyy-MM-dd HH:mm"`,
            },
            timezone: {
              type: "string",
              description: `The timezone. In the case of Japan, "Asia/Tokyo" is used.`,
            },
          },
          required: ["latitude", "longitude", "date", "timezone"],
        },
      },
    },

    /**
     * Ref: https://github.com/google/A2A/blob/main/samples/python/agents/langgraph/agent.py#L19
     */
    get_exchange_rate: (object) => {
      console.log("Run the function get_exchange_rate.");
      console.log(object); // Check arguments.
      const {
        currency_from = "USD",
        currency_to = "EUR",
        currency_date = "latest",
      } = object;
      let res;
      try {
        const resStr = UrlFetchApp.fetch(
          `https://api.frankfurter.app/${currency_date}?from=${currency_from}&to=${currency_to}`,
        ).getContentText();
        const obj = JSON.parse(resStr);
        res = [
          `The raw data from the API is ${resStr}. The detailed result is as follows.`,
          `The currency rate at ${currency_date} from "${currency_from}" to "${currency_to}" is ${obj.rates[currency_to]}.`,
        ].join("\n");
      } catch ({ stack }) {
        res = stack;
      }
      console.log(res); // Check response.
      return {
        mcp: {
          jsonrpc: "2.0",
          result: { content: [{ type: "text", text: res }], isError: false },
        },
        a2a: { result: res },
      };
    },

    /**
     * This function returns the current weather.
     * The API is from https://open-meteo.com/
     *
     * { latitude = "35.681236", longitude = "139.767125", date = "2025-05-27 12:00", timezone = "Asia/Tokyo" } is Tokyo station.
     */
    get_current_weather: (object) => {
      console.log("Run the function get_current_weather.");
      console.log(object); // Check arguments.
      const {
        latitude = "35.681236",
        longitude = "139.767125",
        date = "2025-05-27 12:00",
        timezone = "Asia/Tokyo",
      } = object;
      let res;
      try {
        // Ref: https://open-meteo.com/en/docs?hourly=weather_code&current=weather_code#weather_variable_documentation
        const code = {
          0: "Clear sky",
          1: "Mainly clear, partly cloudy, and overcast",
          2: "Mainly clear, partly cloudy, and overcast",
          3: "Mainly clear, partly cloudy, and overcast",
          45: "Fog and depositing rime fog",
          48: "Fog and depositing rime fog",
          51: "Drizzle: Light, moderate, and dense intensity",
          53: "Drizzle: Light, moderate, and dense intensity",
          55: "Drizzle: Light, moderate, and dense intensity",
          56: "Freezing Drizzle: Light and dense intensity",
          57: "Freezing Drizzle: Light and dense intensity",
          61: "Rain: Slight, moderate and heavy intensity",
          63: "Rain: Slight, moderate and heavy intensity",
          65: "Rain: Slight, moderate and heavy intensity",
          66: "Freezing Rain: Light and heavy intensity",
          67: "Freezing Rain: Light and heavy intensity",
          71: "Snow fall: Slight, moderate, and heavy intensity",
          73: "Snow fall: Slight, moderate, and heavy intensity",
          75: "Snow fall: Slight, moderate, and heavy intensity",
          77: "Snow grains",
          80: "Rain showers: Slight, moderate, and violent",
          81: "Rain showers: Slight, moderate, and violent",
          82: "Rain showers: Slight, moderate, and violent",
          85: "Snow showers slight and heavy",
          86: "Snow showers slight and heavy",
          95: "Thunderstorm: Slight or moderate",
          96: "Thunderstorm with slight and heavy hail",
          99: "Thunderstorm with slight and heavy hail",
        };
        const endpoint = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&hourly=weather_code&timezone=${encodeURIComponent(
          timezone,
        )}`;
        const resObj = UrlFetchApp.fetch(endpoint, {
          muteHttpExceptions: true,
        });
        if (resObj.getResponseCode() == 200) {
          const obj = JSON.parse(resObj.getContentText());
          const {
            hourly: { time, weather_code },
          } = obj;
          const widx = time.indexOf(date.replace(" ", "T").trim());
          if (widx != -1) {
            res = code[weather_code[widx]];
          } else {
            res = "No value was returned. Please try again.";
          }
        } else {
          res = "No value was returned. Please try again.";
        }
      } catch ({ stack }) {
        res = stack;
      }
      console.log(res); // Check response.
      return {
        mcp: {
          jsonrpc: "2.0",
          result: { content: [{ type: "text", text: res }], isError: false },
        },
        a2a: { result: res },
      };
    },
  };

  /**
   * If you want to return the file content to MCP client, please set the return value as follows.
   * {
   *   jsonrpc: "2.0",
   *   result: {
   *    content:[
   *      {
   *        type: "text",
   *         text: "sample text",
   *       },
   *       {
   *         type: "image",
   *         data: "base64 data",
   *         mimeType: "mimetype",
   *       },
   *     ],
   *     isError: false,
   *   }
   * }
   *
   * If you want to return the file content to A2A client, please set the return value as follows.
   * {
   *   result: {
   *     type: "file",
   *     kind: "file",
   *     file: {
   *       name: "filename",
   *       bytes: "base64 data",
   *       mimeType: "mimetype",
   *     },
   *     metadata: null
   *   }
   * }
   *
   */

  // for A2A
  const agentCard = {
    name: "API Manager",
    description: [
      `Provide management for using various APIs.`,
      `- Run with exchange values between various currencies. For example, this answers "What is the exchange rate between USD and GBP?".`,
      `- Return the weather information by providing the location and the date, and the time.`,
    ].join("\n"),
    provider: {
      organization: "Tanaike",
      url: "https://github.com/tanaikech",
    },
    version: "1.0.0",
    url: `https://script.google.com/macros/s/{deploymentId}/exec?accessKey=sample`, // <--- Please replace this to your Web Apps URL.
    defaultInputModes: ["text/plain"],
    defaultOutputModes: ["text/plain"],
    capabilities: {
      streaming: false,
      pushNotifications: false,
      stateTransitionHistory: false,
    },
    skills: [
      {
        id: "get_exchange_rate",
        name: "Currency Exchange Rates Tool",
        description: "Helps with exchange values between various currencies",
        tags: ["currency conversion", "currency exchange"],
        examples: ["What is exchange rate between USD and GBP?"],
        inputModes: ["text/plain"],
        outputModes: ["text/plain"],
      },
      {
        id: "get_current_weather",
        name: "Get current weather",
        description:
          "This agent can return the weather information by providing the location and the date, and the time.",
        tags: ["weather"],
        examples: [
          "Return the weather in Tokyo for tomorrow's lunchtime.",
          "Return the weather in Tokyo for 9 AM on May 27, 2025.",
        ],
        inputModes: ["text/plain"],
        outputModes: ["text/plain"],
      },
    ],
  };

  return {
    A2AObj: { functions: (_) => functions, agentCard: (_) => agentCard },
  };
}

1.1.2 Deploying Google Apps Script as a Web App

Open the script editor.
Click Deploy > New deployment.
Select Web App.
Execute as: Me.
Who has access: Anyone.
Copy the Web App URL.

1.1.3 Configuration

Update the url property inside the agentCard variable in your agent.gs script with your copied Web App URL. Make sure to redeploy the Web App after updating the code to apply the changes.

1.2 Configuring the Gemini CLI

1.2.1 Setting the GAS A2A Server as a Subagent

Despite the advantages of using Google Apps Script, a technical hurdle persists: standard A2A clients cannot natively interact with GAS-based servers automatically. This is because retrieving the agent card dynamically requires a GET request to https://script.google.com/macros/s/{deploymentId}/exec/.well-known/agent.json. Currently, this endpoint requires access token authorization. While Google Application Default Credentials (ADC) can be used for installing the subagents on Gemini CLI, they are restricted to *.googleapis.com and *.run.app endpoints. GAS Web App endpoints are not yet supported for automated retrieval. Ref

Fortunately, remote subagents in the Gemini CLI allow developers to directly define the agent card locally. This elegant workaround bypasses the authentication process entirely and reduces the network overhead of loading the agent card from the GAS Web App.

To generate the agent card JSON, run the getAgentCard() function in your code.gs script. This prints the necessary JSON object to the Apps Script execution console.

Save the obtained JSON to define the subagent in your working directory. Create a file at .gemini/agents/sample-gas-agent.md:

---
kind: remote
name: sample-gas-agent
agent_card_json: |
  {
    "name": "API Manager",
    "description": "Provide management for using various APIs.\n- Run with exchange values between various currencies. For example, this answers \"What is the exchange rate between USD and GBP?\".\n- Return the weather information by providing the location and the date, and the time.",
    "provider": {
      "organization": "Tanaike",
      "url": "https://github.com/tanaikech"
    },
    "version": "1.0.0",
    "url": "https://script.google.com/macros/s/{your deployment ID}/exec?accessKey=sample",
    "defaultInputModes":[
      "text/plain"
    ],
    "defaultOutputModes":[
      "text/plain"
    ],
    "capabilities": {
      "streaming": false,
      "pushNotifications": false,
      "stateTransitionHistory": false
    },
    "skills":[
      {
        "id": "get_exchange_rate",
        "name": "Currency Exchange Rates Tool",
        "description": "Helps with exchange values between various currencies",
        "tags":[
          "currency conversion",
          "currency exchange"
        ],
        "examples":[
          "What is exchange rate between USD and GBP?"
        ],
        "inputModes": [
          "text/plain"
        ],
        "outputModes":[
          "text/plain"
        ]
      },
      {
        "id": "get_current_weather",
        "name": "Get current weather",
        "description": "This agent can return the weather information by providing the location and the date, and the time.",
        "tags":[
          "weather"
        ],
        "examples":[
          "Return the weather in Tokyo for tomorrow's lunchtime.",
          "Return the weather in Tokyo for 9 AM on May 27, 2025."
        ],
        "inputModes": [
          "text/plain"
        ],
        "outputModes":[
          "text/plain"
        ]
      }
    ]
  }
---

1.3 Testing the Connection

Launch the Gemini CLI. The application will detect the new subagent as shown below. Select Acknowledge and Enable to activate it.

Running the /agents command in the chat displays the installed subagents. Your installed sample-gas-agent will appear under remote agents.

You can also invoke the agent directly using @sample-gas-agent:

Input the following sample prompts:

What is exchange rate between USD and GBP?

and

Return the weather in Tokyo for tomorrow's lunchtime.

The following results are returned for each prompt, confirming that the responses were generated securely through the GAS-based sample-gas-agent.

When combining these requests into a single prompt:

I’m planning a trip from London to Japan and need to finalize my budget and itinerary; could you tell me the current USD to GBP exchange rate so I can manage my funds, and also let me know tomorrow's lunchtime weather in Tokyo so I can decide whether to book an outdoor terrace for my arrival meal?

The subagent successfully processes both requests and generates the correct response.

Alternatively, you can direct a specific prompt exclusively to the subagent by prefixing it:

@sample-gas-agent What is exchange rate between USD and GBP?

2. Advanced Integration: Orchestrating Google Workspace with Subagents

As an enhanced test, we will install the google-workspace-orchestrator subagent, which integrates heavily with Google Workspace to perform complex cross-application tasks.

2.1 Building the Advanced A2A Server

2.1.1 Copying the Google Apps Script

For this advanced setup, copy the following Google Apps Script project by clicking the copy button on the dashboard:https://script.google.com/home/projects/1xIwskiWAychSp3JN25s7AVbpJf9aRlSvCE8C9szIxPnFHZBeeX3Eo7vT

2.1.2 Deploying as a Web App

Open the script editor.
Click Deploy > New deployment.
Select Web App.
Execute as: Me.
Who has access: Anyone.
Copy the Web App URL.

2.1.3 Configuration

Update webAppsUrl within the object variable in the code.gs script. Make sure to redeploy the Web App after updating the code.

2.2 Configuring the Gemini CLI

2.2.1 Setting the Advanced Subagent

To define the agent card for this advanced subagent, run the getAgentCard() function in code.gs. This will create a text file containing the JSON of the agent card directly in your Google Drive root folder.

Create a file named .gemini/agents/google-workspace-orchestrator.md in your working directory and paste the generated JSON:

---
kind: remote
name: google-workspace-orchestrator
agent_card_json: |
  {
    "name": "Google Workspace Orchestrator",
    "description": "This agent acts as a comprehensive interface for the Google Workspace ecosystem and associated Google APIs. It provides extensive capabilities to manage and automate tasks across Gmail (sending, organizing, retrieving), Google Drive (file management, search, permission handling, content generation), and Google Calendar (schedule management). It features deep integration with Google Classroom for managing courses, assignments, and rosters, as well as Google Analytics for reporting. Additionally, it controls Google Docs, Sheets, and Slides for document creation and data manipulation. Advanced features include RAG (Retrieval-Augmented Generation) via File Search stores, image generation, YouTube video summarization, and Google Maps utilities. It serves as a central hub for executing complex workflows involving multiple Google services.",
    "provider": {
      "organization": "Tanaike",
      "url": "https://github.com/tanaikech"
    },
    "version": "1.0.0",
    "url": "https://script.google.com/macros/s/{your deployment ID}/exec?accessKey=sample",
    "defaultInputModes":[
      "text/plain"
    ],
    "defaultOutputModes":[
      "text/plain"
    ],
    "capabilities": {
      "streaming": false,
      "pushNotifications": false,
      "stateTransitionHistory": false
    },
    "skills":[
      // ...
      // 160 skills
      // ...
   ]
  }
---

2.3 Testing the Advanced Workflows

Launch the Gemini CLI and select Acknowledge and Enable for the newly detected google-workspace-orchestrator subagent.

To avoid interference, disable the previous subagent by running the following command in the chat:

/agents disable sample-gas-agent

Running the /agents command will now show that the google-workspace-orchestrator subagent has 160 skills enabled. You can view the full list of detailed skills at https://github.com/tanaikech/ToolsForMCPServer.

 > /agents

Local Agents

  - Codebase Investigator Agent (codebase_investigator)
    The specialized tool for codebase analysis...
  - CLI Help Agent (cli_help)
    Specialized agent for answering questions about the Gemini CLI...
  - Generalist Agent (generalist)
    A general-purpose AI agent with access to all tools...

Remote Agents

  - google-workspace-orchestrator
    Agent Description: This agent acts as a comprehensive interface for the Google Workspace ecosystem...
    Skills:
    .
    .
    160 skills
    .
    .

Test 1: Generating a Cooking Roadmap

Input the following 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 Gemini CLI initiates the task:

The requested roadmap is successfully generated and populated into Google Sheets:

Test 2: Complex Document Generation and Email Delivery

Input the following 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 Gemini CLI coordinates multiple tools to execute the workflow:

The following PDF file is created from the generated Google Document:

Finally, an email containing the PDF link is sent securely:

3. Architectural Advantage: Overcoming Tool Space Interference (TSI)

The advanced task demonstrated above requires executing multiple parallel processes natively through the google-workspace-orchestrator subagent, which contains an astonishing 160 distinct skills.

When this massive number of skills is loaded directly into a single MCP server or a standard AI context window, it frequently causes a critical challenge known as Tool Space Interference (TSI). TSI is a phenomenon where verbose metadata saturates the context window, severely degrading the AI's reasoning accuracy and frequently causing logic failures or hallucinations. Ref Ref Current industry guidelines suggest a “soft limit” of 20 functions per agent to maintain stability.

To mitigate TSI, I previously proposed Nexus-MCP. Ref Nexus-MCP functions as a centralized gateway employing a deterministic four-phase workflow to map and filter tools. While highly effective, Nexus-MCP relies on a single AI agent acting as the client, making it less suitable for true distributed task execution where specific tool categories should be handled by specialized agents.

As an alternative approach, I proposed using an A2A server architecture. Ref At the time, this required utilizing a heavily modified @a2a-js/sdk because the agent card could not be natively retrieved from GAS Web Apps.

A major merit of the integration method introduced in this article is its ability to bypass TSI entirely while using official tools. By directly defining the agent card locally in .gemini/agents/google-workspace-orchestrator.md, this architecture functions natively within the Gemini CLI. It elegantly avoids TSI by delegating the vast tool execution space entirely to the remote A2A subagent, thereby preserving the main CLI agent's reasoning capacity, stability, and speed.

Summary

The Gemini CLI now supports remote subagents via the A2A protocol, allowing developers to safely extend and delegate capabilities.
Google Apps Script (GAS) serves as an ideal, accessible backend for these subagents due to its low-code environment and native integration with Google Workspace.
Defining the agent card locally in the Gemini CLI easily bypasses the authentication hurdles typically associated with retrieving metadata dynamically from GAS Web Apps.
This architectural pattern resolves Tool Space Interference (TSI) by offloading massive toolsets (like 160+ Google Workspace skills) to dedicated remote agents.
Consequently, developers can reliably execute complex, multi-step operations without degrading the reasoning capacity or token limits of the main AI agent.

Monitoring Sheet Changes with SHEET and SHEETS Functions on Google Sheets

Tanaike — Wed, 08 Apr 2026 05:38:35 +0000

Abstract

Google Sheets recently introduced the SHEET and SHEETS functions. Because they automatically recalculate upon structural changes, developers can utilize them as custom triggers. This article demonstrates how to leverage these functions to detect sheet insertions, deletions, renames, and movements without requiring cumbersome installable triggers in Google Apps Script.

Introduction

On February 23, 2026, Google introduced two pivotal built-in functions to Google Sheets: SHEET and SHEETS Ref. The SHEET function returns the index (sheet number) of a specified sheet or reference Ref. Meanwhile, the SHEETS function provides the total count of sheets within a spreadsheet Ref.

A critical technical characteristic of these functions is their volatility and automatic recalculation based on the spreadsheet's structural metadata. Specifically:

SHEET triggers a recalculation when a sheet is renamed or its position is changed via drag-and-drop.
SHEETS triggers a recalculation whenever a sheet is inserted, duplicated, or removed.

Historically, detecting such structural changes necessitated the use of an installable OnChange trigger in Google Apps Script (GAS). This posed a significant barrier for template distribution, as installable triggers require manual authorization by each user and do not persist through simple file copies.

By leveraging these new functions as "custom triggers," we can effectively bypass the need for installable triggers. When a custom function or formula containing SHEET or SHEETS recalculates, it serves as a catalyst for GAS execution. This enables the creation of self-contained spreadsheets where advanced sheet monitoring logic is activated immediately upon copying the file, significantly improving the user experience and portability of GAS-based solutions.

Implementation Guide

1. Spreadsheet Initialization

Create a new Google Sheets file to serve as your testing environment.

2. Google Apps Script Configuration

Open the Google Apps Script editor bound to your new spreadsheet. Copy and paste the following script, replacing any default code, and save your project.

/**
 * Global constant defining the Script Properties storage key.
 */
const STORAGE_KEY = "SHEET_STATUS_CACHE";

/**
 * Simple trigger to initialize the cached sheet metadata upon opening the spreadsheet.
 */
function onOpen() {
  updateStoredSheetData_();
}

/**
 * Custom function wrapper to retrieve an array of all current sheet names.
 */
function getAllSheetNames() {
  return SpreadsheetApp.getActiveSpreadsheet()
    .getSheets()
    .map((s) => s.getName());
}

/**
 * Core custom function for detecting structural alterations.
 * Priority: If any structural change (Add/Remove/Rename) occurs,
 * subsequent "move" reports are suppressed to avoid noise from index shifting.
 */
function getSheetStatus(_trigger1, _trigger2, returnRawObject = false) {
  const propService = PropertiesService.getScriptProperties();
  const oldDataJson = propService.getProperty(STORAGE_KEY);

  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const currentSheets = ss.getSheets();
  const newData = currentSheets.map((s, i) => ({
    name: s.getName(),
    id: s.getSheetId(),
    index: i + 1,
  }));

  if (!oldDataJson) {
    updateStoredSheetData_();
    return "Initial state recorded.";
  }

  const oldData = JSON.parse(oldDataJson).map((s, i) => ({
    ...s,
    index: i + 1,
  }));

  // Categorize detected modifications into structural changes or simple index moves.
  const { structural, moves } = detectCategorizedChanges_(oldData, newData);

  // Persist the newly fetched metadata to Script Properties.
  propService.setProperty(
    STORAGE_KEY,
    JSON.stringify(newData.map(({ name, id }) => ({ name, id }))),
  );

  // Evaluate which results to return based on change priority.
  // Ignore index movement noise if a primary structural change (addition, removal, rename) occurred.
  const finalDiffs = structural.length > 0 ? structural : moves;

  if (finalDiffs.length === 0) return "No change";
  if (returnRawObject) return JSON.stringify(finalDiffs);

  return finalDiffs.map((d) => d.message).join("\n");
}

/**
 * Retrieves current spreadsheet metadata and persists it to the properties cache.
 */
function updateStoredSheetData_() {
  const ss = SpreadsheetApp.getActiveSpreadsheet();
  const sheetData = ss.getSheets().map((s) => ({
    name: s.getName(),
    id: s.getSheetId(),
  }));
  PropertiesService.getScriptProperties().setProperty(
    STORAGE_KEY,
    JSON.stringify(sheetData),
  );
  return sheetData;
}

/**
 * Differentiates between core structural changes and simple index shifts.
 */
function detectCategorizedChanges_(oldData, newData) {
  const structural = [];
  const moves = [];

  const oldMap = new Map(oldData.map((s) => [s.id, s]));
  const newMap = new Map(newData.map((s) => [s.id, s]));

  // 1. Identify removed sheets (Structural change).
  oldData.forEach((oldSheet) => {
    if (!newMap.has(oldSheet.id)) {
      structural.push({
        type: "removed",
        message: `"${oldSheet.name}" was removed.`,
      });
    }
  });

  // 2. Identify added, renamed, or repositioned sheets.
  newData.forEach((newSheet) => {
    const oldSheet = oldMap.get(newSheet.id);

    if (!oldSheet) {
      // Handle added sheets (Structural change).
      structural.push({
        type: "added",
        message: `"${newSheet.name}" was inserted at tab ${newSheet.index}.`,
      });
    } else {
      const isRenamed = oldSheet.name !== newSheet.name;
      const isMoved = oldSheet.index !== newSheet.index;

      if (isRenamed) {
        // Handle renamed sheets (Structural change).
        structural.push({
          type: "renamed",
          message: `"${oldSheet.name}" was renamed to "${newSheet.name}".`,
        });
      } else if (isMoved) {
        // Handle pure index movements (Non-structural change).
        moves.push({
          type: "moved",
          message: `"${newSheet.name}" was moved from tab ${oldSheet.index} to ${newSheet.index}.`,
        });
      }
    }
  });

  return { structural, moves };
}

/**
 * Optional callback for installable OnChange triggers.
 * If utilized, do not use the custom formula in the sheet.
 */
function onChange(e = {}) {
  const { changeType } = e;
  if (["OTHER", "INSERT_GRID", "REMOVE_GRID"].includes(changeType)) {
    const res = getSheetStatus();
    Browser.msgBox(res);
  }
}

3. Applying the Custom Formula

Return to your Google Sheets interface. In the first sheet, copy and paste the following formula into cell A1:

=getSheetStatus(SHEETS(),MAP(getAllSheetNames(),lambda(sheetname,SHEET(sheetname))))

4. Testing the Workflow

Once the formula is in place, the cell will actively monitor the document's structure. The demonstration below illustrates the expected behavior:

During the demonstration, the following actions trigger a status update in the cell:

Renaming an existing sheet.
Adding a new sheet to the workbook.
Changing the order (moving) of a sheet.
Deleting a sheet.

Appendix: Using Traditional Triggers

If you prefer to use the traditional installable onChange trigger method, you can utilize the onChange function provided at the bottom of the script. In this scenario, you must manually bind the trigger to the onChange function via the Apps Script dashboard and remove the custom formula (=getSheetStatus(...)) from cell A1. The underlying logic handles the detection identically, routing the output to a browser message box instead of a cell.

Summary

The introduction of SHEET and SHEETS functions enables automatic formula recalculation based on structural metadata changes.
These built-in functions can be passed into custom Google Apps Script functions to act as volatile execution triggers.
This methodology eliminates the traditional dependency on installable onChange triggers for monitoring tab modifications.
Removing installable triggers drastically improves script portability and the user experience when distributing spreadsheet templates.
The provided script successfully categorizes and logs structural alterations versus simple index shifts for comprehensive monitoring.

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.

Forem: Tanaike

Next-Generation Google Workspace Automation

Abstract

1. Introduction

2. Architectural Analysis of Existing Methodologies

2.1 Skill-Based Prototyping Using CLI Integrations (Martin Hawksey)

2.2 Local Natural Language Execution via Emulation (Bruce Mcpherson)

2.3 Dynamic Tool Creation to Combat Tool Space Interference (Kanshi Tanaike)

2.4 Remote Subagent Integration via the A2A Protocol (Kanshi Tanaike)

3. Proposed Novel Methodologies for Advanced Workspace Automation

3.1 Federated Context-Aware Routing Architecture (Federated CARA)

3.2 Self-Optimizing Tool Caching Network (SOTCN)

4. Comparative Analysis

5. Discussion and Conclusion

6. Summary

7. Explanatory video

Empowering Autonomous AI Agents through Dynamic Tool Creation

Abstract

Introduction

Technological Foundations

Project Setup and Prerequisites

Install autonomous-google-workspace-agent

Install gas-fakes

Install clasp

Multi-Agent Architecture

src/agent.ts

environment_checker

script_writer

script_executor

script_uploader

summary_agent

autonomous_gas_orchestrator

src/a2aserver.ts

Launching the Agent System

Testing and Use Cases

1. Dynamic Exchange Rate Retrieval via GOOGLEFINANCE

2. Automated Spreadsheet Initialization with Dummy Data

3. Dynamic Calendar Event Scheduling with Autonomous Error Correction

4. GAS Development Workflow: Document Highlighter and Google Drive Deployment

5. Automated Weekly Drive Report: Filtered File Aggregation and Gmail Synchronization

Deployment Considerations

Summary

Orchestrating Agents via ADK for TypeScript and Gemini CLI

Abstract

Introduction

Project Setup and Prerequisites

Building Specialized AI Agents

1. General Logic Analyst (Sample 1)

2. API Manager for Real-Time Data (Sample 2)

3. Local Filesystem Expert via MCP (Sample 3)

4. Google Workspace Technical Guide via MCP (Sample 4)

Orchestrating Multi-Agent Workflows

5. Multi-Agent Orchestrator (Sample 5)

Agent-to-Agent (A2A) Integration with Gemini CLI

6. A2A Server Implementation (Sample 6)

Future Outlook

Summary

Integrating Remote Subagents Built by Google Apps Script with Gemini CLI

Abstract

Introduction

Demonstration

Prerequisites and Repository

1. Basic Integration: Connecting Gemini CLI to a GAS-based A2A Server

1.1 Building the A2A Server

1.1.1 Google Apps Script Preparation

1.1.2 Deploying Google Apps Script as a Web App

1.1.3 Configuration

1.2 Configuring the Gemini CLI

1.2.1 Setting the GAS A2A Server as a Subagent

1.3 Testing the Connection

2. Advanced Integration: Orchestrating Google Workspace with Subagents

2.1 Building the Advanced A2A Server

2.1.1 Copying the Google Apps Script

2.1.2 Deploying as a Web App

2.1.3 Configuration

2.2 Configuring the Gemini CLI

2.2.1 Setting the Advanced Subagent

2.3 Testing the Advanced Workflows

3. Architectural Advantage: Overcoming Tool Space Interference (TSI)

Summary

Install `autonomous-google-workspace-agent`

`src/agent.ts`

`environment_checker`

`script_writer`

`script_executor`

`script_uploader`

`summary_agent`

`autonomous_gas_orchestrator`

`src/a2aserver.ts`