AppsScriptPulse

Solutions, AI, Advanced

Mastering Workspace API Authentication in ADK Agents with a Reusable Pattern

Tags:
| | 0 Comments |

For developers seasoned in the Google Workspace ecosystem, the promise of agentic AI is not just about automating tasks, but about creating intelligent, nuanced interactions with the services we know so well. Google’s Agent Development Kit (ADK) provides the foundation, but integrating the familiar, user-centric OAuth 2.0 flow into this new world requires a deliberate architectural approach.

This article explores the patterns for building a sophisticated, multi-capability agent. It explores why you might choose a custom tool implementation (ADK’s “Journey 2”) over auto-generation, and presents a reusable authentication pattern that you can apply to any Workspace API.

The full source code for this project is available in the companion GitHub repository. It’s designed as a high-fidelity local workbench, perfect for development, debugging, and rapid iteration.

The Architectural Crossroads: Journey 1 vs. Journey 2

When integrating a REST API with the ADK, you face a choice, as detailed in the official ADK authentication documentation:

  • Journey 1: The “Auto-Toolify” Approach. This involves using components like OpenAPIToolset or the pre-built GoogleApiToolSet sets. You provide an API specification, and the ADK instantly generates tools for the entire API surface. This is incredibly fast for prototyping but can lead to an agent that is “noisy” (has too many tools and scopes) and lacks the robustness to handle API-specific complexities like pagination.
  • Journey 2: The “Crafted Tool” Approach. This involves using FunctionTool to wrap your own Python functions. This is the path taken in this project. It requires more initial effort but yields a far superior agent for several reasons:
    • Control: This approach exposes only the high-level capabilities needed (e.g., search_all_chat_spaces), not every raw API endpoint.
    • Robustness: Logic can be built directly into the tools to handle real-world challenges like pagination, abstracting this complexity away from the LLM.
    • Efficiency: The tool can pre-process data from the API, returning a concise summary to the LLM and preserving its valuable context window.

Journey 2 was chosen because the goal is not just to call an API, but to provide the agent with a reliable, intelligent capability.

The Core Implementation: A Reusable Pattern

The cornerstone of this integration is a single, centralised function: get_credentials. This function lives in agent.py and is called by every tool that needs to access a protected resource.

It elegantly manages the entire lifecycle of an OAuth token within the ADK session by following a clear, four-step process:

  1. Check Cache: It first looks in the session state (tool_context.state) for a valid, cached token.
  2. Refresh: If a token exists but is expired, it uses the refresh token to get a new one and updates the cache.
  3. Check for Auth Response: If no token is found, it checks if the user has just completed the OAuth consent flow using tool_context.get_auth_response().
  4. Request Credentials: If all else fails, it formally requests credentials via tool_context.request_credential(), which signals the ADK runtime to pause and trigger the interactive user flow.

This pattern is completely generic. You can see in the agent.py file how, by simply changing the SCOPES constant, you could reuse this exact function for Google Drive, Calendar, Sheets, or any other Workspace API.

Defining the Agent and Tools

With the authentication pattern defined, building the agent becomes a matter of composition. The agent.py file also defines the “Orchestrator/Worker” structure—a best practice that uses a fast, cheap model (gemini-2.5-flash) for routing and a more powerful, specialised model (gemini-2.5-pro) for analysis.

The Other Half: The Client-Side Auth Flow

The get_credentials function is only half the story. When it calls tool_context.request_credential(), it signals to the runtime that it needs user authentication. The cli.py script acts as that runtime, or “Agent Client.”

The cli.py script is responsible for the user-facing interaction. As you can see in the handle_agent_run function within cli.py, the script’s main loop does two key things:

  1. It iterates through agent events and uses a helper to check for the specific adk_request_credential function call.
  2. When it detects this request, it pauses, prints the authorisation URL for the user, and waits to receive the callback URL.
  3. It then bundles this callback URL into a FunctionResponse and sends it back to the agent, which can then resume the tool call, this time successfully.

This client-side loop is the essential counterpart to the get_credentials pattern.

Production Considerations: Moving Beyond the Workbench

This entire setup is designed as a high-fidelity local workbench. Before moving to a production environment, several changes are necessary:

  • Persistent Sessions: The InMemorySessionService is ephemeral. For production, you must switch to a persistent service like DatabaseSessionService (backed by a database like PostgreSQL) or VertexAiSessionService. This is critical for remembering conversation history and, most importantly, for securely storing the user’s OAuth tokens.
  • Secure Credential Storage: While caching tokens in the session state is acceptable for local testing, production systems should encrypt the token data in the database or use a dedicated secret manager.
  • Runtime Environment: The cli.py would be replaced by a web server framework (like FastAPI or Flask) if you are deploying this as a web application, or adapted to the specific requirements of a platform like Vertex AI Agent Engine.

By building with this modular, Journey 2 approach, you create agents that are not only more capable and robust but are also well-architected for the transition from local development to a production-grade deployment.

Explore the Code

Explore the full source code in the GitHub repository to see these concepts in action. The README.md file provides all the necessary steps to get the agent up and running on your local machine. By combining the conceptual overview in this article with the hands-on code, you’ll be well-equipped to build your own robust, production-ready agents with the Google ADK.

Source: GitHub – mhawksey/ADK-Workspace-User-oAuth-Example

Solutions, Advanced

Customising the Gemini CLI with Extensions: A gas-fakes Case Study

Tags:
| | 0 Comments |

The Gemini CLI is a powerful tool for developers, but its true potential lies in its extensibility. I’m excited to share a project that showcases this flexibility: the gas-fakes Gemini CLI Extension. This extension is a case study in tailoring the Gemini CLI to your specific needs, particularly when it comes to secure software development in Google Apps Script.

At its core, this project addresses a critical security concern in the age of AI-driven development: how can you safely test and execute AI-generated code that requires broad access to your Google Workspace data? The answer lies in the pioneering work of Bruce Mcpherson on his gas-fakes library, which this extension integrates into a seamless and secure workflow, thanks to the invaluable contributions of Kanshi Tanaike. I’m looking forward to discussing this project in more detail with Bruce at the upcoming Google Workspace Developer Summit in Paris.

The Power of Gemini CLI Extensions

The ability to create extensions for the Gemini CLI opens up a world of possibilities for developers. By packaging together a collection of tools and resources, you can create a customised experience that is perfectly suited to your workflow. An extension can include three key components:

  • System Prompts (GEMINI.md): A GEMINI.md file allows you to provide the model with custom instructions and context, guiding its behaviour to ensure it generates code that aligns with your specific requirements.
  • Custom Commands: You can create custom commands to automate common tasks and streamline your development process.
  • MCP Tools: The Model Context Protocol (MCP) allows you to integrate external tools and services with the Gemini CLI, enabling powerful, interactive experiences.

The gas-fakes Extension: A Case Study in Secure Development

The gas-fakes Gemini CLI Extension is a practical example of how these components can be combined to create a powerful and secure development environment for Google Apps Script.

The extension tackles the challenge of safely executing AI-generated code by creating a sandboxed environment where scripts can be tested without granting them access to your Google account. Here’s how it works:

  • GEMINI.md: The GEMINI.md file provides the model with detailed instructions on how to use the gas-fakes library, ensuring that the generated code is compatible with the sandboxed environment.
  • Custom Commands: The extension includes custom commands like /gas:init and /gas:new that automate the process of setting up a new project and generating code.
  • MCP Tool: The packaged MCP tool allows the Gemini CLI to interact with the gas-fakes sandbox, enabling it to execute code and receive feedback in a secure environment. This extension also includes the new official Model Context Protocol (MCP) for Google Workspace Development to interact directly with Google Workspace APIs.

Getting Started

To get started with the gas-fakes extension, you’ll first need to have the Google Gemini CLI installed. Once that’s set up, you can install the extension with the following command:

gemini extensions install https://github.com/mhawksey/gas-fakes-ext

For more information on managing extensions, including uninstallation and updates, please see the official documentation.

Usage

Once the extension is installed, you can start a new sandboxed Apps Script project directly from your terminal.

First, create a new directory for your project, navigate into it, and start the Gemini CLI. From there, you can use the /gas:init command to scaffold a complete project structure, which includes all the necessary files for local development and testing.

With the project initialised, you can then use the /gas:new command to generate code from a natural language prompt. For example:

/gas:new "create a new Google Doc and write 'Hello, World!' to it"

This command generates the Apps Script code in src/Code.js and a corresponding runner script in run.js. From here, you can continue the conversation with the Gemini CLI to refine and build upon your code, testing each iteration locally in the secure, sandboxed environment.

This project structure is deliberate: the run.js file is your sandbox for testing, while the src folder contains the clean, production-ready Apps Script code. This separation makes it easy to use other command-line tools like clasp to push only the code in the /src directory to your online Apps Script project when you are ready to deploy.

Fine-Grained Security with Conversational Controls

Beyond creating new files, a common requirement is to have a script interact with existing documents in a user’s Google Drive. The gas-fakes extension provides a robust solution for this, and because it’s integrated into the Gemini CLI, you can configure these advanced security settings using natural language.

This conversational control is powered by the extension’s MCP tool, run-gas-fakes-test. When you ask Gemini to “whitelist this Google Doc for read access”, the model doesn’t write the configuration code itself. Instead, it calls this tool, translating your request into a set of structured parameters that the tool understands. The MCP tool then dynamically assembles and executes the run.js script with the precise security settings you requested. This abstraction is what makes the natural language interface so powerful.

For example, instead of requesting broad access to all of a user’s files, you can create a specific whitelist of file IDs that your script is allowed to interact with, specifying read-only or write access on a per-file basis. This granular approach ensures your script only ever touches the files it is supposed to.

For even tighter security, you can ask Gemini to:

  • Disable entire services: If your script only needs to work with Sheets, you can completely disable DriveApp and DocumentApp.
  • Whitelist specific methods: Lock down a service to only allow certain actions, for example, permitting DriveApp.getFiles() but blocking DriveApp.createFile().
  • Manage test artefacts: For debugging, you can disable the automatic cleanup feature to inspect any files created during a test run.

These advanced features provide developers with the confidence to build and test powerful automations, knowing that the execution is contained within a secure, predictable environment.

Conclusion

The Gemini CLI is more than just a command-line interface; it’s a powerful platform for creating customised and intelligent experiences. The gas-fakes Gemini CLI Extension is just one example of what is possible. I encourage you to explore the world of Gemini CLI Extensions and see what you can create.

Acknowledgements

This extension stands on the shoulders of giants. It directly builds upon the pioneering work of Bruce Mcpherson and his gas-fakes library. I’d also like to express my sincere gratitude to Kanshi Tanaike, whose work on the gas-fakes sandbox and MCP server has been instrumental in the development of this extension.

Source: GitHub – mhawksey/gas-fakes-ext

Library, Solutions, Advanced

Unlocking Google’s Full API Universe and Authentication Flows in Google Apps Script

Tags:
| | 0 Comments |

A Google Apps Script project that dynamically generates modern, feature-rich client libraries for any public Google API directly from the Google API Discovery Service.

For many developers, Google Apps Script is the go-to platform for rapidly automating and extending Google Workspace. Its simplicity and deep integration are powerful. But as projects grow in ambition, developers often encounter two significant walls: needing to connect to a Google API that isn’t built-in, or requiring an authentication flow, like a service account, that the standard services don’t support.

What if you could break through those walls? What if you could use a robust client library for almost any Google API—from Firebase to Cloud Billing—in seconds, right from Apps Script itself?

Today, I’m excited to introduce the Google API Client Library Generator for Apps Script, a project and code repository designed to solve these very challenges. It comes with a full suite of pre-built libraries, enabling you to significantly expand what’s possible on the platform.

Why This Matters: Beyond the Built-in Services

While Apps Script’s built-in and advanced services are excellent, they represent just a fraction of Google’s vast API ecosystem. This collection of generated libraries unlocks the rest, offering two critical advantages:

  1. Complete API Coverage: The generator uses the Google APIs Discovery Service to create clients for over 400 APIs. If it’s in the Google Discovery Service then there is a library for it in the repository.
  2. Flexible Authentication Flows: Generated libraries are not tied to the standard user-permission model. This means you can use service accounts for server-to-server authentication, or implement other OAuth2 flows as needed.

Getting Started

Getting started is as simple as finding the library you need in the build/ directory of the GitHub repository and copying the code into your Apps Script project. For detailed setup instructions and other authentication options, please refer to the main README.md in the repository.

Unlocking Professional Workflows with Service Accounts

The real power of this approach comes from flexible authentication. For Google Workspace developers, this also unlocks the ability to use service accounts with domain-wide delegation to make API calls on behalf of other users in your domain.

To handle the authentication flow, you’ll need an OAuth2 library. The following example uses the OAuth2 for Apps Script library, but other options are also available. Once you have your chosen library set up, you can use the following pattern:

// The email of the user to impersonate (for domain-wide delegation).
const USER_EMAIL = '[email protected]'; 

function getService_() {
  // Credentials from the service account's JSON key file.
  const serviceAccountCreds = {
    "private_key": "-----BEGIN PRIVATE KEY-----\n...",
    "client_email": "[email protected]",
  };

  // Use a unique name for the service, like 'Drive' or 'BigQuery', to avoid
  // token collisions between different services.
  return OAuth2.createService('Drive:' + USER_EMAIL)
      .setTokenUrl('https://oauth2.googleapis.com/token')
      .setPrivateKey(serviceAccountCreds.private_key)
      .setIssuer(serviceAccountCreds.client_email)
      .setSubject(USER_EMAIL)
      .setCache(CacheService.getUserCache())
      .setScope('https://www.googleapis.com/auth/drive');
}

/**
 * Lists files using the configured service account.
 */
function listFilesWithServiceAccount() {
  const service = getService_();
  if (!service.hasAccess()) {
    console.log('Service Account authentication failed: ' + service.getLastError());
    return;
  }
  
  const token = service.getAccessToken();

  // This is where the generated library is used with the custom token.
  const drive = new Drive({
    token: token 
  });

  const files = drive.files.list({
    supportsAllDrives: true,
    pageSize: 10
  });
  
  console.log('Files found via service account:', JSON.stringify(files, null, 2));
}

Under the Bonnet: The Generator

For those who want to tweak the generation logic or integrate it into their own workflows, the generator itself is included in the repository. It’s a self-contained Apps Script project that fetches API metadata and programmatically constructs modern, robust ES6 classes with features like automatic exponential backoff for handling API errors.

Join the Community and Contribute

This project was heavily inspired by the work of Spencer Easton and aims to build upon that foundation. It’s a community effort.

While libraries for all APIs are generated, not all have been extensively tested. If you use a library and find a bug, or have an idea for an improvement, please open a GitHub Issue. Pull requests are, of course, always welcome. Happy scripting!

Source: GitHub – mhawksey/Google-API-Client-Library-Generator-for-Apps-Script

Solutions, Gmail, Web App, Intermediate

Creating a ‘full fat’ RSS feed for Google Gmail labels with Google Apps Script

Tags:
| | 0 Comments |

In this post I want to cover three things. First I want to introduce a little app I’ve developed which allows you to create a RSS feed for any of your Gmail labels (with the option to remove certain links – useful if you don’t want others unsubscribing you from mailing lists). Secondly I explain how it was made and how you can use it yourself. Finally I want to discuss how this could be used in an open course environment, utilising the vast processing power from services like Twitter and reusing their target marketing emails to your benefit with a bit of ‘dark social judo’.

This solution was first published in May 2013 and since then Google Apps Script has evolved deprecating services that originally made this solution possible, in particular, ScriptDB and the original XML service which includes a handy .parseJS() method.

Following a request I’ve recently updated the solution to make it work again. As well as swapping out ScriptDB in favor of using the Properties Service I used the makeRSS method previously highlighted here in Apps Script Pulse.

Source: Creating a ‘full fat’ RSS feed for Google Gmail labels (enabling some dark social judo)

Solutions, Sheets

Everything a Google Apps Script Developer wanted to know about reading hyperlinks in Google Sheets … but was afraid to ask

Tags:
| | 0 Comments |

The problem: hyperlinks in Google Sheets can be in three different formats so if you have a script or add-on that relies on handling links in cells it can cause some headaches.

This article covers a thorough walkthrough of using Advanced Sheets Service to read hyperlinks from cells with different link formats.

Source: Everything a Google Apps Script Developer wanted to know about reading hyperlinks in Google Sheets … but was afraid to ask

Solutions, Sheets

Google Apps Script Patterns: Writing rows of data to Google Sheets the V8 way

Tags:
| | 0 Comments |

For some context for seasoned Google Apps Script developers like me until V8 we’ve been working in a bit of an old school JavaScript bubble. With V8 there is an opportunity to write less verbose and more succinct code. To see some of the differences below I’ve copied the Writing JSON data mapped to row headings example from my original post and updated this with a V8 version and will highlight the changes.

This post covers a range of techniques and includes a typical pattern for writing structured data like JSON responses from third party sources.

Source: Google Apps Script Patterns: Writing rows of data to Google Sheets the V8 way