Autonomous Google API Agent

Vibe Code All Google APIs: The Zero-Trust Autonomous Agent for Google Apps Script (AGAA)

Welcome to the Autonomous Google API Agent (AGAA), the ultimate autonomous workspace orchestrator designed specifically for the strict execution limits of the Google Apps Script (GAS) environment.

Operating within the strict constraints of Google Apps Script—specifically the absolute 6-minute execution limit and synchronous blocking networking—demands an architecture that discards the optimistic assumptions of traditional Node.js environments. AGAA is a highly engineered survival architecture. Inspired by Google's Agent Development Kit, AGAA eliminates the hallucination risks and catastrophic data-destruction vulnerabilities inherent in standard LLM function-calling. It introduces a Zero-Trust Role-Based Access Control (RBAC) architecture, granular method-level sandboxing, deterministic security auditing, and autonomous schema discovery via the Model Context Protocol (MCP).

By fusing GASADK with GoogleApiApp, we cross the threshold into true Vibe Coding. AGAA allows developers to transition from writing rigid, boilerplate API scripts to dictating cross-service automation entirely via natural language across all Google APIs—including Workspace, Analytics, and YouTube—without bloated client libraries.

---

🌟 Core Architecture & Innovations

At the core of AGAA is a sophisticated, phase-separated orchestration model that acts as an absolute firewall between the LLM Planner and your live Google data.

• Autonomous Schema Discovery (MCP Integration): AGAA is mathematically forbidden from guessing or hallucinating API payloads. It natively queries the Google Developer Knowledge API via MCP (mcp_0) to extract official documentation, exact endpoints, and required JSON body structures before executing any network request.
• Universal API Agnosticism: AGAA does not care if you are formatting a Docs paragraph, fetching Classroom rosters, parsing Analytics dimensions, or querying YouTube metadata. It utilizes a single dynamic tool wrapper (call_google_api) for all Google APIs, eliminating tool bloat entirely.
• Fast-Fail Method Validation: Rejects improperly formatted or incomplete method names (e.g., hallucinating create instead of documents.create) locally before initiating costly network requests, saving tokens and execution time.
• Formula Latency Suspension: Autonomously detects uncomputed #N/A or Loading... states in Spreadsheet cells and suspends the GAS thread to wait for server-side computations to resolve before retrying.
• Autonomous Pagination Integration: Detects nextPageToken in responses and recursively aggregates list data across multiple pages without requiring the LLM to manage while-loops or page states.
• Execution Loop Limiters: Tracks deterministic tool invocation signatures, mathematically halting runaway token burn if the LLM repeatedly attempts to hit a blocked URL or executes the same failed API method more than 3 times.

---

⚙️ AGAA Workflow Architecture

The step-by-step workflow of AGAA operates as a dynamic Directed Acyclic Graph (DAG), seamlessly weaving between planning, schema discovery, execution, and security evaluation.

flowchart TD
    Start([User Prompt Input])
    Planner[Task Planning & DAG Generation]
    FastTrack{Requires Tools?}
    DirectOut[Direct Response Bypass]
    TaskLoop[Sequential Task Execution]
    MCP[Pathway A: MCP Schema Lookup]
    HTTP[Pathway B: HTTP Web Retrieval]
    Workspace[Pathway C: Google API Call]
    SecurityCheck{Pass Local RBAC Check?}
    APIExec[Execute API via GoogleApiApp]
    Block[Raise Security Block]
    Synthesis[Final Synthesis & Summary]
    EndNode([Output to User])

    Start --> Planner
    Planner --> FastTrack
    FastTrack -- No --> DirectOut
    DirectOut --> EndNode
    FastTrack -- Yes --> TaskLoop
    TaskLoop --> MCP
    TaskLoop --> HTTP
    TaskLoop --> Workspace
    Workspace --> SecurityCheck
    SecurityCheck -- Denied --> Block
    SecurityCheck -- Allowed --> APIExec
    MCP --> TaskLoop
    HTTP --> TaskLoop
    APIExec --> TaskLoop
    Block --> Synthesis
    TaskLoop -- All Tasks Done --> Synthesis
    Synthesis --> EndNode

    classDef core fill:#0f172a,color:#f8fafc,stroke:#3b82f6,stroke-width:2px;
    classDef tool fill:#1e293b,color:#22d3ee,stroke:#06b6d4,stroke-width:2px;
    classDef check fill:#334155,color:#facc15,stroke:#eab308,stroke-width:2px;
    classDef output fill:#0f172a,color:#10b981,stroke:#059669,stroke-width:2px;
    classDef block fill:#450a0a,color:#f87171,stroke:#ef4444,stroke-width:2px;

    class Start,Planner,TaskLoop core;
    class MCP,HTTP,Workspace,APIExec tool;
    class FastTrack,SecurityCheck check;
    class DirectOut,Synthesis,EndNode output;
    class Block block;

Step-by-Step Workflow Explanation

1. Task Planning: The orchestrator digests the natural language prompt and decomposes it into a logical DAG, taking a Fast-Track route to eliminate execution latency if tools are unnecessary.
2. Pathway Evaluation: The agent selects the correct capability for the current node, routing schema knowledge to MCP, external data to HTTP, and data mutation to the Google API tool.
3. Security Interception: Before any Google API request touches the network, it is intercepted by the local RBAC engine for deterministic method and class validation.
4. Execution & Aggregation: Validated requests are processed by GoogleApiApp, which handles REST endpoint construction, parameter encoding, and automatic pagination aggregation.
5. Synthesis: The LLM receives the aggregated data arrays, parses them natively, and formulates a final, formatted response to the user.

---

🚀 Step-by-Step Quick Start Guide for Beginners

This section guide shows absolute beginners how to get AGAA up and running in a Google Apps Script project from scratch.

Step 1: Install Required Libraries in GAS

AGAA depends on GASADK (which manages the cognitive orchestration engine) and GoogleApiApp (which dynamically resolves Google API endpoints).

1. Open your Google Apps Script Editor.
2. On the left sidebar, click the "+" button next to Libraries.
3. Install GASADK:

• Paste the Project Key: 1kYkLP1KNs2AGBBzw903WE-rt_cF5gS2RlKxu2kg4xn8q0sy6hoAQlBrd
• Click Look up, select the latest version, and choose the identifier GASADK.
• Click Add.

1. Install GoogleApiApp:

• Paste the Project Key: 1YVWd5qzz0quKljrJkliE143UwwJq1BopoZQSwNEqwNgHOPQ9VeaQeNS7
• Click Look up, select the latest version, and choose the identifier GoogleApiApp.
• Click Add.

Step 2: Copy AutonomousGoogleApiAgent.js into your Project

1. In your GAS project, click "+" next to Files and select Script.
2. Name the file AutonomousGoogleApiAgent.
3. Copy the entire source code of [AutonomousGoogleApiAgent.js](src/AutonomousGoogleApiAgent.js) from this repository and paste it into the editor.

Step 3: Setup Script Properties (Your Secrets API Keys)

AGAA requires two API Keys: one for Gemini, and one for the Developer Knowledge API (MCP).

1. In your GAS project, navigate to Project Settings (the gear icon on the left sidebar).
2. Scroll down to the Script Properties section.
3. Click Add script property and add the following two key-value pairs:

• Property Name: GEMINI_API_KEY | Value: Your Gemini API Key (Get one here)
• Property Name: DEVELOPER_MCP_KEY | Value: Your Google Developer Knowledge API Key (Get one here)

1. Click Save script properties.

Step 4: Enable Advanced Google Services (APIs)

You must enable any Google service you plan to have the agent orchestrate.

1. On the left sidebar of the script editor, click "+" next to Services.
2. Select the API you wish to enable (e.g., Google Sheets API, Google Drive API, Google Docs API).
3. Click Add.

Step 5: Execute Your First Wrapper Script

Create a new script file (e.g. main.js) and paste the following simple test code to run your first prompt:

function runMyFirstAgent() {
  const prompt =
    'Create a new Google Spreadsheet and write "Hello World from AGAA!" in cell A1 of the first sheet.';

  // Beginners: Highly restrictive zero-trust settings. Read and write are allowed for sheets, everything else is blocked.
  const securityConfig = {
    sheets: { read: true, write: true, delete: false },
  };

  const properties = PropertiesService.getScriptProperties();
  const geminiApiKey = properties.getProperty("GEMINI_API_KEY");
  const developerMcpKey = properties.getProperty("DEVELOPER_MCP_KEY");

  const agent = new AutonomousGoogleApiAgent({
    geminiApiKey,
    developerMcpKey,
    securityConfig,
  });

  console.log("Starting agent...");
  const response = agent.run(prompt, (logEntry) =>
    console.log(logEntry.message),
  );

  console.log("=== Response ===");
  console.log(response);
}

---

🛡️ Zero-Trust Security Configuration (Deep Dive)

Security cannot be an LLM prompt instruction; it must be a deterministic reality. Granting an LLM unfettered access to your workspace via OAuth scopes is dangerous. AGAA shifts the security burden away from the AI and into hardcoded JavaScript middleware.

1. Coarse RBAC (Role-Based Access Control)

The securityConfig object enforces strict boundaries regardless of the underlying OAuth token's capabilities. Any Google API service not explicitly defined in your configuration object is mathematically blocked by default (Implicit Deny).

const securityConfig = {
  sheets: { read: true, write: true, delete: false },
  drive: { read: true, write: false, delete: false },
};

• read: (Boolean) Allows/disallows read methods (GET operations).
• write: (Boolean) Allows/disallows creation and mutation methods (POST, PUT, PATCH, copy, batch).
• delete: (Boolean) Allows/disallows destructive methods (DELETE, trash, empty, clear, purge).

2. Action Class Inference

AGAA automatically parses the requested REST method string (e.g., files.delete) and uses regex to classify it dynamically as READ, WRITE, or DELETE:

• DELETE: Triggered by method names containing delete, trash, empty, remove, purge, or clear.
• WRITE: Triggered by method names containing create, update, patch, insert, send, write, post, put, copy, or batch.
• READ: All other method names are classified as read-only.

3. Hierarchical Method Masking (allowMethods / denyMethods)

For highly precise control, you can white- or blacklist specific namespaces using dot-notation hierarchical matching. Deny rules always override allow rules.

const securityConfig = {
  sheets: {
    read: true,
    write: true,
    delete: false,
    allowMethods: ["spreadsheets.values"], // Restricts only to value manipulation
    denyMethods: ["spreadsheets.values.clear"], // Blocks specific cell clearing
  },
};

• Allowing spreadsheets.values automatically permits spreadsheets.values.get and spreadsheets.values.update, but definitively blocks spreadsheets.create.

4. Network Egress Sandboxing (httpGet)

External web scraping via the fetch_http_get tool is sandboxed through allowDomains and denyDomains, evaluated using strict hierarchical string matching to prevent data exfiltration.

const securityConfig = {
  httpGet: {
    allowDomains: ["api.github.com"], // External fetch is limited only to GitHub
    denyDomains: ["evil.com"], // Block explicitly restricted domains
  },
};

5. Intervention Protocol

If an action violates the RBAC policy, the tool locally returns a [SECURITY BLOCKED] payload to the agent. AGAA’s system instructions mathematically forbid the LLM from attempting to bypass the firewall (no ReAct hallucinations), forcing a graceful explanation of the permissions failure.

---

📖 API Reference

Constructor Config Parameters (new AutonomousGoogleApiAgent(config))

| Parameter | Type | Required | Default | Description | | :---------------- | :----- | :------: | :-------------------------------: | :------------------------------------------------------------------------------ | | geminiApiKey | String | Yes | undefined | Your Gemini API authorization key. | | developerMcpKey | String | Yes | undefined | Your Google Developer Knowledge MCP API key. | | accessToken | String | No | "" | Optional. OAuth2 access token to manually override GoogleApiApp authentication. | | model | String | No | "models/gemini-3-flash-preview" | The target Gemini model to power the orchestrator. | | timeoutMs | Number | No | 280000 | Milliseconds before safe abort to avoid GAS 6-minute execution limits. | | securityConfig | Object | No | {} | The zero-trust security rule map (Coarse & Granular controls). |

Public Methods

setAccessToken(accessToken)

Overrides the default script authentication with a custom Google OAuth2 access token.

• Arguments: accessToken (String) - The raw access token.
• Returns: this (Allows method chaining).

run(prompt, logCallback)

Executes the autonomous agent to solve the user's intent.

• Arguments:
• prompt (String) - The natural language command.
• logCallback (Function) - Optional callback for telemetry logs. Receives a log object: { timestamp, message, data }.
• Returns: String - The final synthesized natural language response (or strictly structured JSON matching request).

getHistory()

Retrieves the complete conversation history.

• Returns: Array - Array of multi-turn conversation messages.

getLogs()

Retrieves execution telemetry logs collected during the execution run.

• Returns: Array - Array of logging entries.

getSecurityLogs()

Retrieves a detailed history of all blocked requests intercepted by the zero-trust middleware.

• Returns: Array - Audit trail logs of blocked API calls or domain fetches.

---

💻 Guided Real-World Usage Scenarios (Tests)

Test 1: Spreadsheet Formula Orchestration and Latency Handling

This scenario tests the agent's ability to create a spreadsheet, insert a formula, and read the computed value, managing Sheets computation latency.

• Required Scopes: script.external_request, drive, spreadsheets
• Required Advanced Services: Google Drive API, Google Sheets API

function testSpreadsheetLatency() {
  const prompt =
    'Create a new Google Spreadsheet by putting a formula `=GOOGLEFINANCE("CURRENCY:USDJPY")` in cell "A1" of the first sheet. Then, get and show the value of cell "A1".';

  const securityConfig = {
    sheets: { read: true, write: true, delete: false },
  };

  main_AutonomousGoogleApiAgent_(prompt, securityConfig);
}

• Under the Hood: Sheets takes time to fetch finance data. The initial cell read returns #N/A. The AGAA middleware detects this, suspends execution for 3000ms, and retries the read operation dynamically, ensuring the agent gets the actual exchange rate.

---

Test 2: Cross-Domain Web Scraping and Document Batch Processing

This script fetches a live website profile, summarizes it within the context, and uses the Google Docs batchUpdate A

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tanaikech
• Source: tanaikech/Autonomous-Google-API-Agent
• License: MIT
• Homepage: https://medium.com/google-cloud/vibe-code-all-google-apis-the-zero-trust-autonomous-agent-for-google-apps-script-77d743bdd545

Install and usage instructions live in the source repository linked above.