DEV Community: Tanaike

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.

Seamless Integration of Google Workspace and Gemini API via External URLs

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

Abstract

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

Introduction

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

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

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

Prerequisites

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

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

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

1. Setting up the Google Sheet

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

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

2. Client Script for Public URLs

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

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

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

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

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

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

main();

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

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

There are three recorded entries of customer feedback:

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

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

3. Applying to Other Workspace Services

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

For Google Sheets:

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

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

For Google Docs:

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

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

For Google Slides:

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

4. Handling Private Content

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

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

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

For Google Sheets:

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

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

For Google Docs:

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

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

For Google Slides:

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

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

Utility Script: Retrieving an Access Token

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

import { execSync } from "child_process";

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

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

Dynamic Content with Google Apps Script

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

1. Setting up the Web App

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

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

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

Next, deploy the script as a Web App:

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

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

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

2. Client Script for GAS Web Apps

Set your Web App URL to the uri variable.

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

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

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

main();

3. Testing Dynamic Updates

When the script is run initially, the output is:

The current keyword is **apple**.

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

Running the client script again yields:

The current keyword is **orange**.

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

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

Summary

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

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

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

Abstract

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

Introduction

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

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

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

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

Project Resources

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

Part 1: MCP (Model Context Protocol)

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

Prerequisites

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

1. Server-Side Setup

1.1 Copy the Demo Script

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

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

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

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

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

1.2 Deploy as Web App

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

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

1.3 Configure the Script

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

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

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

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

2. Client-Side Setup

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

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

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

Part 2: A2A (Agent-to-Agent)

1. Server-Side Setup

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

2. Client-Side Setup

2.1 Clone Repository and Install Dependencies

Execute the following commands in your terminal:

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

The directory contains:

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

2.2 The Proxy Script

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

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

2.3 Set Environment Variables

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

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

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

2.4 Testing

Terminal Test

Run the basic connectivity test:

npm run test1

Expected output:

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

Browser/ADK Test

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

npm run test2

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

Example 1: Simple Workflow

Prompt:

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

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

The resulting roadmap in the Spreadsheet:

Example 2: Complex Workflow

Prompt:

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

The browser visualizes the processing steps:

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

The generated PDF:

The email received:

Dear Tanaike,

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

Best regards,
Your AI Assistant

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

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

1. Sample Script

Copy the Google Spreadsheet containing the necessary scripts:

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

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

Alternatively, access the code via the GitHub Repository.

2. Deploy as Web App

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

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

3. Testing

Sample 1: Restaurant Finder

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

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

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

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

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

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

You can replace the data source with:

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

Sample 2: Budget Simulator

Copy the Budget Simulator Spreadsheet:

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

Set your apiKey in main.gs after copying.

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

Deploy as a Web App and open the URL.

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

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

The graph updates to simulate the proposal.

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

The new data is appended to "Sheet1":

Summary

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

Appendix

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