GASADK (Agent Development Kit for Google Apps Script)

Welcome to GASADK, the ultimate Agent Development Kit (ADK) designed specifically for 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. GASADK is a highly engineered survival architecture. Inspired by the @google/adk, this initial release of GASADK introduces the heavily optimized LlmAgent. It replaces unbounded, recursive ReAct loops with a deterministic, phase-separated orchestration model, fundamentally solving context bloat, execution latency, and API quota exhaustion.

[!TIP] 🚀 Looking to turn your Google Workspace APIs into a Model Context Protocol (MCP) server?
Check out our new sample project: Google API MCP Server Guide to instantly expose all Google Workspace APIs (Sheets, Drive, Docs, Calendar, Gmail, etc.) as dynamic MCP tools.

---

🌟 Architecture & Key Innovations

At the core of GASADK is the LlmAgent, powered by the Planner-Executor-Synthesizer (PES) architecture. It utilizes Directed Acyclic Graphs (DAGs) to orchestrate complex task delegations across external tools, Model Context Protocol (MCP) servers, Agent-to-Agent (A2A) networks, and file-based Agent Skills.

Core Safeguards & Optimizations

1. One-Pass Fast-Track (Zero-Latency Bypass) If the LLM Planner determines that external capabilities are unnecessary for a given prompt (e.g., standard conversational queries), the execution and synthesis phases are completely bypassed. The agent returns a direct response, aggressively slashing API latency and token consumption by avoiding redundant tool queueing.
2. Schema Interception Even when the Fast-Track attempts to bypass execution, if developers enforce an outputSchema (strict JSON formatting), GASADK intelligently intercepts the bypass. It routes the output through a dummy task directly into the Synthesizer to mathematically guarantee adherence to the requested JSON schema under all circumstances.
3. Temporal Context Anchoring LLMs suffer from temporal blindness—they cannot natively resolve relative time like "tomorrow" or "last week". GASADK intercepts the system prompt and injects a hardcoded new Date() absolute anchor. The Planner autonomously converts relative requests into absolute ISO 8601 timestamps before pinging external tools (MCP/A2A), completely eliminating date-resolution errors on remote servers.
4. Payload Bulletproofing (Pessimistic Memory Management) When external servers or massive Google Drive files return tens of thousands of characters, feeding them directly into the context window triggers a fatal 400 Payload Too Large error. GASADK enforces a strict maxResultLength threshold (default 20,000 chars), automatically truncating overflow data. It favors partial data over catastrophic runtime crashes.
5. Dynamic Re-Planning (Targeted ReAct) Unlike standard ADKs that rely on a continuous ReAct loop for every step, GASADK plans an entire DAG upfront. Only if a node in the DAG execution fails does the system trigger a Re-Plan. It discards the unexecuted queue, analyzes the failure report, and generates an alternative DAG utilizing different tools.
6. Clean History Optimization (A2AApp v2.6.0) Maintains and propagates conversation history dynamically to sub-agents, MCP servers, and remote A2A servers without polluting the core logic history. Massive internal intermediate LLM reasoning steps (function calls, planning thoughts) are filtered out, constructing a clean user/model role-based chat history to prevent token bloat and quota exhaustion.
7. Fast-Track Halt Optimization Allows server functions to forcefully bypass the server-side LLM synthesis loop (by returning _gemini_halt: true). This prevents endless generative loops, eliminates unnecessary token usage, and guarantees instant response times for purely algorithmic/computational tool executions.
8. Direct JSON-RPC Bypass & Direct Routing (v1.3.1) Bypasses the entire multi-phase LLM mock orchestration when directRouting is flagged and a single target card is assigned, dispatching the JSON-RPC request natively to slash network latency. It also supports local pre-fetched Agent Cards through a2aServerAgentCardJSONs to completely bypass remote HTTP fetches.
9. Multi-Channel Log Propagation (v1.3.3) Supports explicit log propagation from the orchestrator down to sub-clients (MCPApp and A2AApp), storing logs inside dedicated, isolated Sheets (raw, MCP, A2A, MCPA2Aserver_log) dynamically. It guarantees thread-safe writes using script lock protection under high-concurrency environments.
10. Global Scope Initialization Fix (v1.3.4) Resolves compilation ReferenceError during global script initialization in Google Apps Script by removing unbound variables (accessKey, webAppsUrl) from the global context of agentCard_ToolsForMCPServer.js and instead using runtime shadow cloning for context safety.

GASADK vs. TS ADK (@google/adk) Paradigm Shift

| Feature | TypeScript ADK (@google/adk) | GASADK | | :------------------- | :------------------------------------------- | :------------------------------------------------------ | | Execution Model | Recursive ReAct Loop (Step-by-Step). | Phase-separated DAG execution. | | I/O Networking | Asynchronous I/O, local stdio, WebSockets. | Synchronous, thread-blocking HTTP (UrlFetchApp). | | Concurrency | Highly parallelized (Promise.all). | Strictly sequential execution to prevent quota burnout. | | Failure Handling | Optimistic: Infinite loops possible. | Pessimistic: Hard aborts at 280s to prevent 6-min kill. | | State Protection | In-memory session tracking. | Infrastructure-level locking via LockService. |

---

⚙️ GASADK Workflow Architecture

The execution lifecycle of LlmAgent is rigorously compartmentalized. The diagram below details the exact chronological flow from the moment agent.run() is invoked to the final synthesized response.

graph TD
    %% Styling Definitions
    classDef userReq fill:#f9f,stroke:#333,stroke-width:2px,color:#000;
    classDef core fill:#bbf,stroke:#333,stroke-width:2px,color:#000;
    classDef llm fill:#fbb,stroke:#333,stroke-width:2px,color:#000;
    classDef external fill:#bfb,stroke:#333,stroke-width:2px,color:#000;
    classDef decision fill:#ff9,stroke:#333,stroke-width:2px,color:#000;
    classDef safeguard fill:#f66,stroke:#333,stroke-width:2px,color:#000;

    %% Nodes
    Start(["User: agent.run(prompt)"])
    InitCaps["Initialize Capabilities<br>(Tools, MCP, A2A, Skills)"]
    InjectTime["Inject Temporal Context<br>System Time Anchor"]
    Planner["LLM: Planner Phase<br>Generate DAG & JSON Schema"]

    FastTrackDec{"requires_<br>capabilities<br>== false?"}
    SchemaDec{"outputSchema<br>defined?"}
    ReturnDirect(["Return direct_answer<br>Execution Bypassed"])

    PopTask["Pop Task from planQueue"]
    CheckTime{"Elapsed Time ><br>timeoutMs<br>(280s)?"}
    TimeoutAbort["Trigger Safe Abort<br>Stop Queue"]

    InjectContext["Inject 'depends_on'<br>Context to Prompt"]
    ExecRouter{"Capability<br>Type?"}

    ExecMCP["MCP Server Client"]
    ExecA2A["A2A Server Client"]
    ExecSkill["Agent Skill LLM Call"]
    ExecNative["Native Function Calling"]

    CheckErr{"Execution<br>Error?"}
    Truncate["Payload Truncation<br>> maxResultLength"]
    SaveResult["Save to taskResults"]

    CheckEmpty{"planQueue<br>Empty?"}
    CheckReplan{"replanCount <<br>maxReplans?"}
    DropQueue["Discard Remaining DAG"]
    Replanner["LLM: Dynamic Re-Planner<br>Avoid Failed Method"]

    SynthPhase["LLM: Final Synthesis<br>Analyze Gathered Data"]
    End(["Return Final Answer"])

    A2A_Registry[("A2A App")]
    MCP_Servers[("MCP Servers")]
    GDrive[("Google Drive")]

    %% Edges
    Start --> InitCaps
    InitCaps -. "Fetch Agent Cards" .-> A2A_Registry
    InitCaps -. "tools/list Request" .-> MCP_Servers
    InitCaps -. "Read .md Skills" .-> GDrive

    InitCaps --> InjectTime --> Planner
    Planner --> FastTrackDec

    FastTrackDec -- "Yes (Fast-Track)" --> SchemaDec
    SchemaDec -- "No (Raw output fine)" --> ReturnDirect
    SchemaDec -- "Yes (Intercept)" --> SynthPhase

    FastTrackDec -- "No (Capabilities required)" --> PopTask

    PopTask --> CheckTime
    CheckTime -- "Timeout Exceeded" --> TimeoutAbort
    TimeoutAbort --> SynthPhase

    CheckTime -- "Safe" --> InjectContext
    InjectContext --> ExecRouter

    ExecRouter -- "MCP Server" --> ExecMCP
    ExecRouter -- "A2A Server" --> ExecA2A
    ExecRouter -- "Agent Skill" --> ExecSkill
    ExecRouter -- "Native/Built-in" --> ExecNative

    ExecMCP --> CheckErr
    ExecA2A --> CheckErr
    ExecSkill --> CheckErr
    ExecNative --> CheckErr

    CheckErr -- "Success" --> Truncate --> SaveResult
    SaveResult --> CheckEmpty
    CheckEmpty -- "No" --> PopTask
    CheckEmpty -- "Yes" --> SynthPhase

    CheckErr -- "Failed" --> CheckReplan
    CheckReplan -- "Yes (Can Replan)" --> DropQueue --> Replanner
    Replanner --> PopTask
    CheckReplan -- "No (Max Replans)" --> SaveResult

    SynthPhase --> End

    %% Assign Classes
    class Start,ReturnDirect,End userReq;
    class InitCaps,InjectTime,PopTask,InjectContext,ExecNative,SaveResult core;
    class Planner,ExecSkill,Replanner,SynthPhase llm;
    class ExecMCP,ExecA2A,A2A_Registry,MCP_Servers,GDrive external;
    class FastTrackDec,SchemaDec,CheckTime,ExecRouter,CheckErr,CheckEmpty,CheckReplan decision;
    class TimeoutAbort,Truncate,DropQueue safeguard;

---

🧩 Supported Capabilities

GASADK acts as a universal adapter, normalizing disparate protocols into a unified schema for the Planner.

• Native Tools: Wrap standard Google Apps Script functions directly into the capability schema.
• MCP Servers: Native integration to dynamically discover (tools/list) and invoke tools on external servers using the Model Context Protocol.
• A2A Servers: Cross-agent communication. Fetch remote Agent Cards and utilize other autonomous agents as local tools via the Agent-to-Agent protocol.
• Sub-Agents: Nest instances of LlmAgent locally. Delegate complex cognitive sub-tasks without corrupting the main orchestrator's context.
• Agent Skills: Dynamically load behavioral skills stored as Markdown (.md) files inside Google Drive. A native GAS hack for distributed, RAG-like prompt injection.
• Built-in Tools: Comes equipped with a Python CodeExecutor and native GoogleSearch capabilities.

---

📥 Installation & Core Dependencies

GASADK integrates multiple high-performance GAS libraries under the hood. You can use it as a standalone library or copy the source code directly.

GASADK is constructed by the following scripts.

• GADADK
• GeminiWithFiles
• A2AApp
• MCPApp
• MCPA2Aserver
• FileSearchApp

Option 1: Use as a GAS Library (Recommended)

1. Open your GAS project.
2. Navigate to Libraries on the left panel and click "+".
3. Enter the Project Key: 1w2mwhWQd4_6rom-UBRPD8gayBoqGH_87awSBVqGI8DdaQI_pOeSuGYDu
4. Select the latest version and set the identifier to GASADK.
5. Click Add.

After GASADK was installed, you can use i