DEV Community: Google Developer Experts

Building a Multimodal Agent with the ADK, AWS Fargate, and Gemini Flash Live 3.1

xbill — Sat, 18 Apr 2026 13:41:02 +0000

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build Agentic apps using the Gemini Live API with the Python programming language deployed to Amazon Fargate.

Aren’t There a Billion Python ADK Demos?

Yes there are.

Python has traditionally been the main coding language for ML and AI tools. The goal of this article is to provide a minimal viable basic working ADK streaming multi-modal agent using the latest Gemini Live Models.

In the Spirit of Mr. McConaughey’s “alright, alright, alright”

So what is different about this lab compared to all the others out there?

This is one of the first implementations of the latest Gemini 3.1 Flash Live Model with the Agent Development Kit (ADK). The starting point for the demo was an existing Code lab- which was updated and re-engineered with Gemini CLI.

The original Codelab- is here:

Way Back Home - Building an ADK Bi-Directional Streaming Agent | Google Codelabs

What Is Python?

Python is an interpreted language that allows for rapid development and testing and has deep libraries for working with ML and AI:

Welcome to Python.org

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.13

Amazon Fargate

AWS Fargate is a serverless, pay-as-you-go compute engine for containers that works with Amazon Elastic Container Service (ECS) or Elastic Kubernetes Service (EKS). It eliminates the need to manage, patch, or scale underlying EC2 virtual machines. Fargate automatically allocates, scales, and manages compute infrastructure, allowing developers to focus solely on designing and operating applications.

Details are here:

Serverless Compute - AWS Fargate - AWS

More information on Fargate is available here:

Architect for AWS Fargate for Amazon ECS

Gemini Live Models

Gemini Live is a conversational AI feature from Google that enables free-flowing, real-time voice, video, and screen-sharing interactions, allowing you to brainstorm, learn, or problem-solve through natural dialogue. Powered by the Gemini 3.1 Flash Live model , it provides low-latency, human-like, and emotionally aware speech in over 200 countries.

More details are available here:

Gemini 3.1 Flash Live Preview | Gemini API | Google AI for Developers

The Gemini Live Models bring unique real-time capabilities than can be used directly from an Agent. A summary of the model is also available here:

https://deepmind.google/models/model-cards/gemini-3-1-flash-live/

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The Google Agent Development Kit (ADK) is an open-source, Python-based framework designed to streamline the creation, deployment, and orchestration of sophisticated, multi-agent AI systems. It treats agent development like software engineering, offering modularity, state management, and built-in tools (like Google Search) to build autonomous agents.

The ADK can be installed from here:

Agent Development Kit (ADK)

Where do I start?

The strategy for starting multimodal real time agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, a minimal ADK Agent is built and tested locally. Next — the entire solution is deployed to Amazon ECS Express.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. All of the relevant code examples and documentation is available in GitHub. This repo has a wide variety of samples- but this lab will focus on the ‘gemini31-ecsexpress’ setup.

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-aws
cd gemini31-fargate

Then run init.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:


xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ source init.sh
Environment setup complete.
GOOGLE_GENAI_USE_VERTEXAI=false
GOOGLE_CLOUD_PROJECT=aisprint-491218
GOOGLE_CLOUD_LOCATION=us-central1

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Build the User Interface

The front end files provide the user interface:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ make frontend
cd frontend && npm install && npm run build

up to date, audited 219 packages in 800ms

49 packages are looking for funding
  run `npm fund` for details

1 high severity vulnerability

To address all issues, run:
  npm audit fix

Run `npm audit` for details.

> frontend@0.0.0 build
> vite build

vite v7.3.1 building client environment for production...
✓ 33 modules transformed.
dist/index.html 0.46 kB │ gzip: 0.29 kB
dist/assets/index-xOQlTZZB.css 21.60 kB │ gzip: 4.54 kB
dist/assets/index-DZmIx3HW.js 214.58 kB │ gzip: 67.45 kB
✓ built in 1.18s

Test The User Interface

The mock server test script allows the interface and Browser settings to be set to allow multimedia — without using any external Model calls or tokens:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ make mock
python mock/mock_server.py
Serving static files from: /home/xbill/gemini-cli-aws/gemini31-fargate/frontend/dist
INFO: Started server process [8689]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

The Deployed mock front-end will look similar to:

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the biometric_agent:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ source testadk.sh
connect to local ADK CLI 

/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260415_200105.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/cli/cli.py:204: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
Running agent biometric_agent, type exit to exit.

[biometric_agent]: Scanner Online.

[user]:

Test The ADK Web Interface

This tests the Audio / Video ADK agent interactions:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ source runadk.sh 
connect on http://127.0.0.1:8000/

/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-15 20:01:46,272 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-15 20:01:46,272 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/gemini31-fargate/backend/app
2026-04-15 20:01:46,272 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/gemini-cli-aws/gemini31-fargate/backend/app/.adk/artifacts
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/cli/fast_api.py:198: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [10520]
INFO: Waiting for application startup.

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

INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
INFO: 127.0.0.1:41986 - "GET / HTTP/1.1" 307 Temporary Redirect
INFO: 127.0.0.1:41986 - "GET /dev-ui/ HTTP/1.1" 200 OK
INFO: 127.0.0.1:41986 - "GET /dev-ui/styles-YY6V3TJU.css HTTP/1.1" 200 OK
INFO: 127.0.0.1:41990 - "GET /dev-ui/chunk-RGCH6K7F.js HTTP/1.1" 200 OK
INFO: 127.0.0.1:42002 - "GET /dev-ui/chunk-W7GRJBO5.js HTTP/1.1" 200 OK
INFO: 127.0.0.1:42026 - "GET /dev-ui/main-7SJG752M.js HTTP/1.1" 200 OK
INFO: 127.0.0.1:42016 - "GET /dev-ui/polyfills-5CFQRCPP.js HTTP/1.1" 200 OK
INFO: 127.0.0.1:42026 - "GET /dev-ui/assets/config/runtime-config.json HTTP/1.1" 200 OK
INFO: 127.0.0.1:42026 - "GET /list-apps?relative_path=./ HTTP/1.1" 200 OK
INFO: 127.0.0.1:41986 - "GET /dev-ui/assets/ADK-512-color.svg HTTP/1.1" 200 OK
INFO: 127.0.0.1:42026 - "GET /dev-ui/adk_favicon.svg HTTP/1.1" 200 OK
2026-04-15 20:01:49,369 - INFO - local_storage.py:60 - Creating local session service at /home/xbill/gemini-cli-aws/gemini31-fargate/backend/app/biometric_agent/.adk/session.db
INFO: 127.0.0.1:42016 - "GET /builder/app/biometric_agent?ts=1776297709357 HTTP/1.1" 200 OK
2026-04-15 20:01:49,393 - INFO - adk_web_server.py:867 - New session created: b1b2e791-b792-414a-9d46-90a3ddac1e53

Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:

Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:

adk web --host 0.0.0.0 --allow_origins 'regex:.*'

Lint and Test the Main Python Code

The final step is to build, lint, and test the main Python code.

To Lint:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ make lint
Linting Python code with Ruff...
ruff check backend
All checks passed!
Linting Frontend code with ESLint...
cd frontend && npm run lint

> frontend@0.0.0 lint
> eslint .

To Test:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ make test
Running backend and connectivity tests...
python3 -m pytest test_live_connection.py test_ws_backend.py test_ws_backend_v2.py backend/app/biometric_agent/test_agent.py
================================================================ test session starts ================================================================
platform linux -- Python 3.13.13, pytest-9.0.3, pluggy-1.6.0
rootdir: /home/xbill/gemini-cli-aws/gemini31-fargate
plugins: anyio-4.13.0, asyncio-1.3.0
asyncio: mode=Mode.STRICT, debug=False, asyncio_default_fixture_loop_scope=None, asyncio_default_test_loop_scope=function
collected 8 items                                                                                                                                   

test_live_connection.py . [12%]
test_ws_backend.py . [25%]
test_ws_backend_v2.py . [37%]
backend/app/biometric_agent/test_agent.py ..... [100%]

================================================================= warnings summary ==================================================================
../../.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72
  /home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
    check_feature_enabled()

-- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html
=========================================================== 8 passed, 1 warning in 2.67s ============================================================
xbill@penguin:~/gemini-cli-aws/gemini31-fargate$

Running Locally

The main Python Code can then be run locally:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ source biosync.sh
Local URL
http://127.0.0.1:8080/
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-15 20:06:48,642 - INFO - System Config: 2.0 FPS, 10.0s Heartbeat
Serving static files from: /home/xbill/gemini-cli-aws/gemini31-fargate/frontend/dist
INFO: Started server process [11513]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

Then connect to the local front end:

Deploying to ECS Express

A utility script runs the deployment to AWS ECS Express. Use the deploy version from the local system:

aws login --remote

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ source save-aws-creds.sh 
Exporting AWS credentials...
Successfully saved credentials to .aws_creds
The Makefile will now automatically use these for deployments.
xbill@penguin:~/gemini-cli-aws/gemini31-fargate$

The system can now be deployed:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ make deploy
./save-aws-creds.sh
Exporting AWS credentials...
Successfully saved credentials to .aws_creds
The Makefile will now automatically use these for deployments.
./deploy-fargate.sh

And status checked:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ make status
--- Fargate Cluster Status ---
-------------------------------------------------------------
| DescribeClusters |
+--------------------------+----------+----------+----------+
| Name | Pending | Running | Status |
+--------------------------+----------+----------+----------+
| biometric-scout-cluster | 0 | 1 | ACTIVE |
+--------------------------+----------+----------+----------+
--- Fargate Service Status ---
-------------------------------------------------------------
| DescribeServices |
+---------+----------+---------------------------+----------+
| Desired | Running | Service | Status |
+---------+----------+---------------------------+----------+
| 1 | 1 | biometric-scout-service | ACTIVE |
+---------+----------+---------------------------+----------+
xbill@penguin:~/gemini-cli-aws/gemini31-fargate$

Once the container is deployed- you can then get the endpoint:

xbill@penguin:~/gemini-cli-aws/gemini31-fargate$ make endpoint
--- Fargate HTTPS Endpoint ---
Application URL: https://biometric-scout-alb-1410555012.us-east-1.elb.amazonaws.com

The service will be visible in the AWS console:

Running the Web Interface

Start a connection to the deployed app:

https://biometric-scout-alb-1410555012.us-east-1.elb.amazonaws.com

Then connect to the app :

Then use the Live model to process audio and video:

Finally — complete the sequence:

Gemini CLI Code Review

As a final step — Gemini CLI was used for a full code review of the project:

✦ Based on my comprehensive review of the "Alpha Rescue Drone - Biometric Security System," the codebase is exceptionally well-structured,
  follows modern engineering standards, and strictly adheres to the specialized requirements for Gemini 3.1 Flash Live and the Google Agent
  Development Kit (ADK).

Core Architecture & Integration
  The system excels at orchestrating a high-frequency, multimodal data stream. The use of a binary protocol (0x01 for audio, 0x02 for video)
  in useGeminiSocket.js minimizes overhead, while the monkey-patching utility in patch_adk.py demonstrates a sophisticated understanding of
  the evolving Gemini 3.1 Live API. This proactive approach ensures compatibility with features like send_realtime_input that are not yet
  natively handled by the standard ADK.

Backend Analysis
   - Agent Intelligence: The instructions in agent.py are precise and prioritize safety (offensive gesture detection) and hidden overrides
     ("Devil's Horns") effectively.
   - Resilience: The backend implements a heartbeat stimulus (CONTINUE_SURVEILLANCE) and a neural handshake, which are critical for
     maintaining model engagement during visual-only periods.
   - Model Fallback: The get_model_id() logic is clever, automatically switching to gemini-2.5-flash for CLI runs to prevent 404 errors,
     while defaulting to the high-performance gemini-3.1-flash-live-preview for production.

Frontend & UI/UX
   - Aesthetic: The "Neon Cyan" HUD in BiometricLock.jsx provides a high-fidelity, futuristic feel that aligns with the "Mission Alpha"
     theme.
   - Feedback Loop: The synchronization between the random sequence generation, visual matching, and the special "Heavy Metal" audio event
     creates a compelling user experience.
   - Efficiency: Utilizing toBlob with JPEG compression (0.6) for the 2 FPS video stream is an optimal choice for balancing visual clarity
     with network latency.

Testing & Maintainability
   - Validation: The project maintains a clean slate with 100% test and linting compliance. The inclusion of mock.sh is a significant
     developer productivity boost.
   - Standards: The use of Ruff for Python and ESLint for the frontend ensures long-term code quality.

Recommendations
   1. Connection Resilience: While the SYSTEM_ERROR closes the socket correctly, the frontend could benefit from a more graceful
      "Reconnecting..." state if the network fluctuates during a mission.
   2. Patch Management: As the Gemini Live API stabilizes, keep an eye on official ADK updates to deprecate the manual unrolling of
      media_chunks in patch_adk.py.
   3. Security: Verify that the .env variables are correctly injected into the Cloud Run environment via the Makefile or cloudbuild.yaml
      without being exposed in the build logs.

Overall, the system is a robust and creative implementation of real-time multimodal AI. Authentication Protocol: Stable. 🤘
                                                                                                                             ? for shortcuts

Summary

The Agent Development Kit was used to enable a multi-modal agent using the Gemini Live Model. This Agent was tested locally with the CLI and then deployed to Amazon Fargate. Several key take-aways and lessons learned were summarized from working with the transition to a new Live Gemini LLM model. Finally, Gemini CLI was used for a complete project code review.

Extending a Video with Angular, Veo 3.1 Lite, Firebase Cloud Functions, and Firebase Cloud Storage [GDE]

Connie Leung — Sat, 18 Apr 2026 06:50:21 +0000

Google released the Veo 3.1 Lite model for AI video generation in the Gemini API, Gemini in Vertex AI, and Gemini AI Studio. This model solves a common developer pain point: generating high-quality videos quickly and at a lower cost.

In this blog post, I migrate my application to use the Veo 3.1 Lite model and implement a new Firebase Cloud Function to extend a video using the GenAI TypeScript SDK.

The application supports image-to-video generation, video interpolation using the first and last frames, and extending Veo videos.

Prerequisites

The technical stack of the project:

Angular 21, the latest version as of April 2026.
Node LTS, the LTS version as of April 2026.
Firebase Remote Config: To manage dynamic parameters.
Firebase Cloud Functions: To be called by the frontend to generate a video, interpolate a video between two images, or extend a Veo video.
Firebase Cloud Storage: To host the generated video files in the default Firebase Storage bucket.
Firebase Local Emulator Suite: To test the functions locally at http://localhost:5001.
Gemini in Vertex AI: Use Gemini in Vertex AI to generate videos and store them in Firebase Cloud Storage.

The public Google AI Studio API is restricted in my region (Hong Kong). However, Vertex AI (Google Cloud) offers enterprise access that works reliably here, so I chose Vertex AI for this demo.

npm i -g firebase-tools

Install firebase-tools globally using npm.

firebase logout

firebase login

Log out of Firebase and log in again to perform proper Firebase authentication.

firebase init

Execute firebase init and follow the prompts to set up Firebase Cloud Functions, the Firebase Local Emulator Suite, Firebase Cloud Storage, and Firebase Remote Config.

If you have an existing project or multiple projects, you can specify the project ID on the command line.

firebase init --project <PROJECT_ID>

In both cases, the Firebase CLI automatically installs the firebase-admin and firebase-functions dependencies.

After completing the setup steps, the Firebase tools generate the functions emulator, functions, a storage rules file, remote config templates, and configuration files such as .firebaserc and firebase.json.

Angular dependency

npm i firebase

The Angular application requires the firebase dependency to initialize a Firebase app, load remote config, and invoke the Firebase Cloud Functions to generate videos.

Firebase dependencies

npm i @cfworker/json-schema @google/genai @modelcontextprotocol/sdk

Install the above dependencies to access Gemini in Vertex AI. @google/genai depends on @cfworker/json-schema and @modelcontextprotocol/sdk. Without these, the Cloud Functions cannot start.

With our project configured, let's look at how the frontend and backend communicate.

Architecture

The frontend application is built with Angular. It relies on Firebase AI Logic to generate images using the Gemini 3.1 Flash Image Preview model. Then, the text prompt and the image are submitted to a Firebase Cloud Function to generate a video, store it in a Firebase Cloud Storage bucket, and return the GCS URI, MIME type, and HTTP URL to the client.

When the client extends the Veo video, it provides the prompt, the GCS URI, and the MIME type to another Firebase Cloud Function to generate an extended video, store it in the Firebase Cloud Storage bucket, and return the GCS URI, MIME type, and HTTP URL to the client.

Similarly, the HTML video player element plays the HTTP URL in the client application.

Difference between Veo 3.1 Lite in Gemini AI Studio and Gemini in Vertex AI

Difference	Gemini AI Studio	Gemini in Vertex AI
Model Name	veo-3.1-lite-generate-preview	veo-3.1-lite-generate-001
Number of extensions	Extend by 7 seconds and up to 20 times	Extend by 7 seconds and up to 4 times
Video length	Extend 141 seconds and the total length is 148 seconds	Extend 28 seconds and the total length is 36 seconds

What Veo 3.1 Does Not Support in Gemini Vertex AI

Unlike Veo 3.1 and Veo 3.1 Fast (which only lack support for Reference style images), Veo 3.1 Lite does not support either Reference asset images or Reference style images.
Supported input resolution does not support 4K.
Supported output resolution does not support 4K.

This limitation does not impact our application, as the demo focuses exclusively on video extension and the resolution of generated videos is hardcoded to 720p.

Firebase Integration

1. Configure Environment Variables

I define the environment variables in the Firebase project. This ensures the functions know the regions for storage, function hosting, and the Veo model to use for video generation.

.env.example

GOOGLE_CLOUD_LOCATION="us-central1"
GEMINI_VIDEO_MODEL_NAME="veo-3.1-lite-generate-001"
IS_VEO31_USED="true"
POLLING_PERIOD_MS="10000"
GOOGLE_FUNCTION_LOCATION="us-central1"
WHITELIST="http://localhost:4200"
REFERER="http://localhost:4200/"

Variable	Description
GOOGLE_CLOUD_LOCATION	The location of the bucket. I chose `us-central1` because the bucket is always free in this region.
GEMINI_VIDEO_MODEL_NAME	The name of the Gemini video model.
IS_VEO31_USED	Whether Veo 3.1 is used. If false, it falls back to generating a video instead of interpolation.
POLLING_PERIOD_MS	The polling period of the video operation in milliseconds.
GOOGLE_FUNCTION_LOCATION	The region of the Cloud Functions. I chose `us-central1` so the functions and the bucket are in the same region.
WHITELIST	Requests must come from http://localhost:4200.
REFERER	Requests originate from http://localhost:4200/.

2. Validating Environment Variables

Before the Cloud Function proceeds with any AI calls, it is critical to ensure that all necessary environment variables are present. I implemented a VIDEO_CONFIG IIFE (Immediately Invoked Function Expression) to run once to validate environment variables such as the polling period, whether Veo 3.1 is used, the Veo model name, the project ID, and the location.

import logger from "firebase-functions/logger";

export function validate(value: string | undefined, fieldName: string, missingKeys: string[]) {
  const err = `${fieldName} is missing.`;
  if (!value) {
    logger.error(err);
    missingKeys.push(fieldName);
    return "";
  }

  return value;
}

export const VIDEO_CONFIG = (() => {
  process.loadEnvFile();

  const env = process.env;
  const isVeo31Used = (env.IS_VEO31_USED || "false") === "true";
  const pollingPeriod = Number(env.POLLING_PERIOD_MS || "10000");

  const missingKeys: string[] = [];
  const model = validate(env.GEMINI_VIDEO_MODEL_NAME, "Gemini Video Model Name", missingKeys);
  const project = validate(env.GCLOUD_PROJECT, "Project ID", missingKeys);
  const location = validate(env.GOOGLE_CLOUD_LOCATION, "Google Cloud Location", missingKeys);

  if (missingKeys.length > 0) {
    throw new Error(`Missing environment variables: ${missingKeys.join(", ")}`);
  }

  return {
    genAIOptions: {
      project,
      location,
      vertexai: true,
    },
    aiVideoOptions: {
      model,
      storageBucket: `${project}.firebasestorage.app`,
      isVeo31Used,
      pollingPeriod,
    },
  };
})();

I am using Node 24 as of April 2026. Since Node 20, we can use the built-in process.loadEnvFile function that loads environment variables from the .env file.

If you are using a Node version that does not support process.loadEnvfile, the alternative is to install dotenv to load the environment variables.

npm i dotenv

import dotenv from "dotenv";

dotenv.config();

Firebase provides the GCLOUD_PROJECT variable, so it is not defined in the .env file.

When the missingKeys array is not empty, VIDEO_CONFIG throws an error that lists all the missing variable names. If the validation is successful, the genAIOptions and aiVideoOptions are returned. The genAIOptions is used to initialize the GoogleGenAI and aiVideoOptions contains parameters for extending a Veo video.

3. Extending a Video and Storing in Firebase Storage

The extendVideo Cloud Function passes the payload to the extendVideoFunction function.

All Cloud Functions enforce App Check, CORS, and a timeout period of 600 seconds. If WHITELIST is unspecified, CORS defaults to true. It is acceptable in a demo, but it is safer to default to false or a specific domain in production.

const cors = process.env.WHITELIST ? process.env.WHITELIST.split(",").map((origin) => origin.trim()): true;
const options = {
  cors,
  enforceAppCheck: true,
  timeoutSeconds: 600,
};

export const extendVideo = onCall( options,
  ({ data }) => extendVideoFunction(data)
);

extendVideoFunction delegates to the extendVideoByPolling function to construct the video arguments and poll the video operation until it finishes. When the function completes successfully, it returns the GCS URI and the MIME type. In the error case, the function throws an error.

import { GoogleGenAI } from "@google/genai";
import { ExtendVideoRequest } from "./types/video.type";
import { extendVideoByPolling, VIDEO_CONFIG } from "./video.util";

export async function extendVideoFunction(data: ExtendVideoRequest) {
  const { genAIOptions, aiVideoOptions } = VIDEO_CONFIG;

  try {
    if (!aiVideoOptions.isVeo31Used) {
      throw new Error("Video extension is only supported for Veo 3.1 model");
    }

    const ai = new GoogleGenAI(genAIOptions);
    return await extendVideoByPolling({ ai, ...aiVideoOptions }, {
      prompt: data.prompt,
      video: data.video,
      config: data.config,
    });
  } catch (error) {
    console.error("Error generating video:", error);
    throw new Error("Error generating video");
  }
}

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

export type AIVideoBucket = {
  ai: GoogleGenAI;
  model: string;
  storageBucket: string;
  isVeo31Used: boolean;
  pollingPeriod: number;
}

export type ExtendVideoRequest = {
  prompt: string;
  video: Video;
  config?: GenerateVideosConfig;
}

export async function extendVideoByPolling(
  aiVideo: AIVideoBucket,
  request: ExtendVideoRequest,
) {
  return processVideoPolling(aiVideo, {
    prompt: request.prompt,
    config: request.config,
    video: request.video,
  });
}

async function processVideoPolling(
  { ai, model, storageBucket, pollingPeriod }: AIVideoBucket,
  mediaParams: VideoMediaParams
) {
  const genVideosParams: GenerateVideosParameters = {
    model,
    ...mediaParams,
    config: {
      ...mediaParams.config,
      numberOfVideos: 1,
      outputGcsUri: `gs://${storageBucket}`,
    },
  };

  return getVideoUri(ai, genVideosParams, pollingPeriod);
}

The extendVideoByPolling function invokes the processVideoPolling function to poll the video operation until it completes.

The processVideoPolling function constructs the video parameters and invokes the getVideoUri function to return the GCS URI and the MIME type. Most importantly, the config property specifies that the number of generated videos is one, and the outputGcsUri keeps the generated video in the storage bucket.

4. Asynchronous Polling

Video extension is a long-running task. Because Vertex AI processes them asynchronously, the functions must poll the operation status in a while loop until the done flag is true.

The Gemini API cannot see the Cloud Storage for Firebase Local Emulator, so it requires a real output GCS URI, which is gs://${storageBucket}.

When the done flag is true, the operation ends and one of three outcomes occurs:

Outcome 1: The error is true, and the video failed to generate. Therefore, the function throws an error.
Outcome 2: The video is successfully stored in the GCS bucket. The function returns the GCS URI and the MIME type to the client application.
Outcome 3: Neither happens. There is no error and no GCS URI, so the function returns an unknown error.

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

async function getVideoUri(
  ai: GoogleGenAI,
  genVideosParams: GenerateVideosParameters,
  pollingPeriod: number,
): Promise<{ uri: string, mimeType: string }> {
  let operation = await ai.models.generateVideos(genVideosParams);

  while (!operation.done) {
    await new Promise((resolve) => setTimeout(resolve, pollingPeriod));
    operation = await ai.operations.getVideosOperation({ operation });
  }

  if (operation.error) {
    const strError = `Video generation failed: ${operation.error.message}`;
    console.error(strError);
    throw new Error(strError);
  }

  const video = operation.response?.generatedVideos?.[0]?.video || {};
  const { uri, mimeType } = video;
  if (uri && mimeType) {
    console.log("video uri", uri, mimeType);
    return { uri, mimeType };
  }

  const strError = "Video generation finished but no uri was provided.";
  console.error(strError);
  throw new Error(strError);
}

The environment variable, POLLING_PERIOD_MS, sets the polling period to 10 seconds. If the wait time is too long, the polling period can be decreased. If the polling cost is expensive or too frequent, the polling period can be increased.

Note: For demo purposes, polling is a decent solution to handle asynchronous video generation. However, it is expensive and creates unnecessary load and latency. For production usage, you may consider push notifications such as WebSockets and Server-Sent Events.

5. Firebase App Configuration and reCAPTCHA Site Key

getFirebaseConfig is a Firebase Cloud Function that returns both the Firebase app configuration and the reCAPTCHA site key.

import logger from "firebase-functions/logger";
import { validate } from "./validate";

function validateFirebaseConfigFields(env: NodeJS.ProcessEnv) {
  const missingKeys: string[] = [];
  const apiKey = validate(env.APP_API_KEY, "API Key", missingKeys);
  const appId = validate(env.APP_ID, "App Id", missingKeys);
  const messagingSenderId = validate(env.APP_MESSAGING_SENDER_ID, "Messaging Sender ID", missingKeys);
  const recaptchaSiteKey = validate(env.RECAPTCHA_ENTERPRISE_SITE_KEY, "Recaptcha site key", missingKeys);
  const projectId = validate(env.GCLOUD_PROJECT, "Project ID", missingKeys);

  if (missingKeys.length > 0) {
    throw new Error(`Missing environment variables: ${missingKeys.join(", ")}`);
  }

  return {
    app: {
      apiKey,
      appId,
      projectId,
      messagingSenderId,
      authDomain: `${projectId}.firebaseapp.com`,
      storageBucket: `${projectId}.firebasestorage.app`,
    },
    recaptchaSiteKey,
  };
}

export const getFirebaseConfigFunction = () => {
  logger.info("getFirebaseConfig called");

  process.loadEnvFile();

  const variables = validateFirebaseConfigFields(process.env);
  if (!variables) {
    return undefined;
  }

  return variables;
};

The Angular application receives the Firebase app configuration and reCAPTCHA site key from the Cloud Function to initialize Firebase AI Logic and protect resources from unauthorized access and abuse.

6. Local Development with Emulators

For local development, I used the Firebase Local Emulator Suite. In the bootstrapFirebase process, the app calls connectFunctionsEmulator to link to the Cloud Functions running at http://localhost:5001.

The port number defaulted to 5001 when firebase init was executed.

Note: While the Cloud Function runs locally (at zero cost), the Storage emulator is not used. This is because the Gemini API requires an actual accessible GCS bucket to store the generated videos.

export function connectEmulators({ remoteConfig, functions }: FirebaseObjects) {
  const useEmulators = getValue(remoteConfig, 'useEmulators').asBoolean();
  if (useEmulators) {
    console.log('Connecting to emulators...');
    const host = getValue(remoteConfig, 'functionEmulatorHost').asString();
    const port = getValue(remoteConfig, 'functionEmulatorPort').asNumber();
    console.log('functionEmulator', `${host}:${port}`);
    connectFunctionsEmulator(functions, host, port);
  }
}

loadFirebaseConfig is a helper function that makes request to the Cloud function to obtain the Firebase App configuration and the reCAPTCHA site key.

{
  "getFirebaseConfigUrl": "http://127.0.0.1:5001/vertexai-firebase-6a64f/us-central1/getFirebaseConfig"
}

import { HttpClient } from '@angular/common/http';
import { inject } from '@angular/core';
import { initializeAppCheck, ReCaptchaEnterpriseProvider } from 'firebase/app-check';
import { catchError, lastValueFrom, throwError } from 'rxjs';
import config from '../../public/config.json';
import { ConfigService } from './ai/services/config.service';
import { FirebaseConfigResponse } from './ai/types/firebase-config.type';
import { connectEmulators, initFirebaseApp } from './firebase.util';

async function loadFirebaseConfig() {
  const httpService = inject(HttpClient);
  const firebaseConfig$ =
    httpService.get<FirebaseConfigResponse>(`${config.getFirebaseConfigUrl}`)
      .pipe(catchError((e) => throwError(() => e)));
  return lastValueFrom(firebaseConfig$);
}

export async function bootstrapFirebase() {
    try {
      const configService = inject(ConfigService);
      const firebaseConfig = await loadFirebaseConfig();
      const { app, recaptchaSiteKey } = firebaseConfig;
      const firebaseObjects = await initFirebaseApp(app);
      const { firebaseApp } = firebaseObjects;

      initializeAppCheck(firebaseApp, {
        provider: new ReCaptchaEnterpriseProvider(recaptchaSiteKey),
        isTokenAutoRefreshEnabled: true,
      });

      connectEmulators(firebaseObjects);
      configService.loadConfig(firebaseObjects);
    } catch (err) {
      console.error(err);
    }
}

The AppConfig remains unchanged.

import { ApplicationConfig, provideAppInitializer } from '@angular/core';
import { bootstrapFirebase } from './app.bootstrap';

export const appConfig: ApplicationConfig = {
  providers: [
    provideAppInitializer(async () => bootstrapFirebase()),
  ]
};

7. Firebase Remote Configuration

New variables are introduced for extending a Veo video in Firebase Remote Config. For the Gemini API, a video can be extended as many as 20 times. For Gemini in Vertex AI, a video can be extended as many as 4 times because the video length exceeds 30 seconds. Therefore, this is externalized into the maxVideoExtendAllowed variable.

Variable	Description	Value
maxVideoExtendAllowed	Maximum number of extensions allowed	4

8. Video Player Component in Angular

The Angular frontend triggers the process using httpsCallable. Once the function returns the Cloud Storage path and the MIME type, the app fetches the download URL for playback.

The ConfigService stores the Firebase app, Remote Config, and functions to be used throughout the application.

import { FirebaseApp } from 'firebase/app';
import { Functions } from 'firebase/functions';
import { RemoteConfig } from 'firebase/remote-config';

export type FirebaseObjects = {
  firebaseApp: FirebaseApp;
  remoteConfig: RemoteConfig;
  functions: Functions;
}

import { Injectable } from '@angular/core';
import { FirebaseObjects } from '../types/firebase-objects';

@Injectable({
  providedIn: 'root'
})
export class ConfigService  {
    firebaseObjects: FirebaseObjects | undefined = undefined;

    loadConfig(firebaseObjects: FirebaseObjects) {
      this.firebaseObjects = firebaseObjects;
    }
}

The retrieveVideoUri method calls the Cloud Function directly to retrieve the GCS URI and the MIME type.

The downloadVideoUriAndUrl method resolves the URI to an HTTP URL so that an HTML video player can play it immediately.

export type VideoGenerationResponse = {
  uri: string;
  url: string;
  mimeType: string;
}

export type DownloadVideoResponse = {
  uri: string;
  mimeType: string;
}

import { inject, Injectable } from '@angular/core';
import { httpsCallable } from 'firebase/functions';
import { getDownloadURL, getStorage, ref } from 'firebase/storage';
import { GenerateVideoRequest } from '../types/video.type';
import { ConfigService } from './config.service';

@Injectable({
  providedIn: 'root'
})
export class VeoService {
  private readonly storage = getStorage();
  private readonly configService = inject(ConfigService);

  private async retrieveVideoUri<T = GenerateVideoRequest>(request: T, methodName: string): Promise<DownloadVideoResponse> {
    try {
      const { functions } = this.configService.firebaseObjects || {};
      if (!functions) {
        throw new Error('Functions does not exist.');
      }

      const downloadGcsUri = httpsCallable<T, DownloadVideoResponse>(
        functions, methodName, { timeout: 600000 }
      );
      const { data } = await downloadGcsUri(request);
      return data;
    } catch (err) {
        console.error(err);
        throw err;
    }
  }

  async downloadVideoUriAndUrl<T = GenerateVideoRequest>(request: T, methodName: CallableNames = 'videos-generateVideo'): Promise<VideoGenerationResponse> {
    const { uri, mimeType } = await this.retrieveVideoUri(request, methodName);

    if (!uri) {
      throw new Error('Video operation completed but no URI was returned.');
    }

    return getDownloadURL(ref(this.storage, uri))
      .then((url) => {
        console.log("download url", url);
        return { uri, url, mimeType };
      })
      .catch((error) => {
        switch (error.code) {
          case 'storage/object-not-found':
            throw new Error("File doesn't exist");
          case 'storage/unauthorized':
            throw new Error("User doesn't have permission to access the object");
          case 'storage/canceled':
            throw new Error("User canceled the upload");
          case 'storage/unknown':
            throw new Error("Unknown storage error occurred, inspect the server response");
        }
        throw new Error("Unknown error occurred");
      });
  }
}

The VideoPlayerComponent has a required videoUrl signal input that is assigned to the source of the video player. It has an "Extend Video" button that emits an extendVideo custom event when clicked. This event notifies the parent component to extend the video in the videoUrl signal input.

import { LoaderComponent } from '@/shared/loader/loader.component';
import { ChangeDetectionStrategy, Component, input, output } from '@angular/core';
import { ExtendVideoIconComponent } from '../../icons/extend-video-icon.component';

@Component({
  selector: 'app-video-player',
  imports: [LoaderComponent, ExtendVideoIconComponent],
  template: `
@if (isGeneratingVideo()) {
  <div class="mt-6">
    <app-loader [loadingText]="loadingText()">
      <p class="text-sm">This can take several minutes. Please be patient.</p>
    </app-loader>
  </div>
} @else if (videoUrl()) {
  <div class="mt-6 flex flex-col gap-4">
    <div class="video-container">
      <video [src]="videoUrl()" controls autoplay loop class="w-full rounded-md"></video>
    </div>

    <div class="flex justify-center">
      <button
        (click)="extendVideo.emit()"
        aria-label="Extend video"
        title="Extend video"
        class="extend-btn"
      >
        <app-extend-video-icon />
        <span>Extend Video</span>
      </button>
    </div>
  </div>
}
  `,
  styleUrl: './video-player.component.css',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class VideoPlayerComponent {
  isGeneratingVideo = input(false);
  videoUrl = input.required<string>();
  extendVideo = output<void>();

  loadingText = input('Generating your video...');
}

9. Angular Integration with Gemini to Extend Video

import { VideoPlayerComponent } from './video-player/video-player.component';

@Component({
  selector: 'app-gen-media',
  imports: [
    VideoPlayerComponent,
  ],
  template: `
  <app-video-player
    [isGeneratingVideo]="isGeneratingVideo()" 
    [videoUrl]="videoUrl()"
    (extendVideo)="extendVideo()"
    [loadingText]="loadingVideoText()"
  />`,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class GenMediaComponent {
  private readonly genMediaService = inject(GenMediaService);
  private readonly genVideoService = inject(GenVideoService);

  genMediaInput = input<GenMediaInput>();
  videoUrl = this.genVideoService.videoUrl;
  isGeneratingVideo = this.genVideoService.isGeneratingVideo.asReadonly();
  loadingVideoText = signal('Generating your video...');

  trimmedUserPrompt = computed(() => this.genMediaInput()?.userPrompt.trim() || '');

  async extendVideo() {
    if (this.trimmedUserPrompt()) {
      try {
        this.loadingVideoText.set('Extending your video...');
        await this.genVideoService.extendVideo(this.trimmedUserPrompt());
      } finally {
        this.loadingVideoText.set('Generating your video...');
      }
    }
  }
}

The GenMediaComponent calls extendVideo with the prompt and the Veo video URL to create an extended video.

import { ConfigService } from '@/ai/services/config.service';
import { VeoService } from '@/ai/services/veo.service';
import { ExtendVideoRequest, GenerateVideoFromFramesRequest, GenerateVideoRequest, VideoGenerationResponse } from '@/ai/types/video.type';
import { computed, inject, Injectable, signal, WritableSignal } from '@angular/core';
import { getValue } from 'firebase/remote-config';

@Injectable({
  providedIn: 'root'
})
export class GenVideoService {
  private readonly veoService = inject(VeoService);
  private readonly configService = inject(ConfigService);

  videoError = signal('');
  videoResponse = signal<VideoGenerationResponse>({ uri: '', url: '', mimeType: '' });
  #extendVideoCounter = signal(0);
  isGeneratingVideo = signal(false);

  videoUrl = computed(() => this.videoResponse().url);

  isVideoExtensionAllowed(counter: number) {
    const remoteConfig = this.configService.firebaseObjects?.remoteConfig;
    if (!remoteConfig) {
      console.warn('Remote config does not exist.');
      return false;
    }

    const max_extend_allowed = getValue(remoteConfig,'maxVideoExtendAllowed').asNumber();
    if (counter >= max_extend_allowed) {
      console.warn('Maximum extension limit reached.');
      return false;
    }

    return true;
  }

  async extendVideo(prompt: string): Promise<void> {
    try {
      const result = await this.extendInterpolatedVideo(
        prompt,
        this.#extendVideoCounter(),
        this.videoResponse()
      );

      if (!result) {
        return;
      }

      this.videoResponse.set(result);
      this.#extendVideoCounter.update(count => count + 1);
      console.log(`Video extended successfully. Current extension count: ${this.#extendVideoCounter()}`);
    } catch (e) {
      console.error(e);
      const errMsg = e instanceof Error ?
        e.message :
        'An unexpected error occurred in video generation.'
      this.videoError.set(errMsg);
    } finally {
      this.isGeneratingVideo.set(false);
    }
  }

  async extendInterpolatedVideo(
    prompt: string,
    counter: number,
    customVideo: Pick<VideoGenerationResponse, 'uri' | 'mimeType'>,
    generatingSignal?: WritableSignal<boolean>,
    error?: WritableSignal<string>
  ) {
    const { uri, mimeType } = customVideo;

    if (!mimeType || !uri) {
      console.warn('No video to extend. Please generate a video first.');
      return null;
    }

    if (!prompt) {
      console.warn('Prompt is required to extend the video.');
      return null;
    }

    if (!this.isVideoExtensionAllowed(counter)) {
      return null;
    }

    const actualErrorSignal = error || this.videoError;
    const actualGeneratingSignal = generatingSignal || this.isGeneratingVideo;
    try {
      actualErrorSignal.set('');
      actualGeneratingSignal.set(true);

      const extendVideoParams: ExtendVideoRequest = {
        prompt,
        video: { uri, mimeType },
      }

      return await this.veoService.downloadVideoUriAndUrl(extendVideoParams, 'videos-extendVideo');
    } catch (e) {
      console.error(e);
      throw e;
    } finally {
      actualGeneratingSignal.set(false);
    }
  }
}

The extendVideo and extendInterpolatedVideo methods validate that an extension is allowed by comparing the #extendVideoCounter signal value against the maxVideoExtendAllowed Remote Config value. If the check fails, nothing happens. If the check succeeds, the videos-extendVideo Cloud Function is called to extend the video. Then, the #extendVideoCounter is incremented by 1 until the extension limit is reached. When extending a Veo video that is too long, Gemini throws an error, and I want to block this from happening on the client side.

This is the end of the walkthrough for the demo. You should now be able to extend generated videos in a Cloud Function, store them securely in a bucket, and play them in a video player within a user interface.

Conclusion

Combining Veo 3.1 with the serverless scalability of Firebase is a powerful workflow.

First, the Angular application neither installs the genai dependency nor maintains the Vertex AI environment variables in a .env file. The client application calls the Cloud Functions to perform intensive tasks and waits for the results.

The Cloud Functions receive arguments from the client, execute complex AI operations like generation, interpolation, and video extension, and write the videos to the dedicated bucket securely. During local development, the Firebase Emulator calls the functions at http://localhost:5001 instead of the ones deployed on the Cloud Run platform.

Try cloning the GitHub repository, generating images, and using those images to generate and interpolate videos. Then, you can extend these Veo videos to create extended videos that are more than 7 seconds long.

Resources

Building a Multimodal Agent with the ADK, Azure ACI, and Gemini Flash Live 3.1

xbill — Sat, 18 Apr 2026 03:07:51 +0000

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build Agentic apps using the Gemini Live API with the Python programming language deployed to Azure Container Instances.

Aren’t There a Billion Python ADK Demos?

Yes there are.

In the Spirit of Mr. McConaughey’s “alright, alright, alright”

So what is different about this lab compared to all the others out there?

The original Codelab- is here:

Way Back Home - Building an ADK Bi-Directional Streaming Agent | Google Codelabs

What Is Python?

Python is an interpreted language that allows for rapid development and testing and has deep libraries for working with ML and AI:

Welcome to Python.org

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.12

Azure Container Instances

Azure Container Instances (ACI) is a serverless, managed service that allows you to run Docker containers in the cloud without managing virtual machines. It is ideal for rapid deployment, bursting, and simple, isolated applications, offering per-second billing and quick startup times. ACI supports Linux and Windows containers, with options for volume mounting and GPU resources.

More details are available here:

https://azure.microsoft.com/en-us/products/container-instances

Why would I want Gemini CLI with Azure? Isn’t that a Google Thing?

Yes- Gemini CLI leverages the Google Cloud console and Gemini models but it is also open source and platform agnostic. Many applications are already cross-cloud so this enables familiar tools to be run natively on Microsoft Azure.

Azure Container Instance Configuration

To configure your Azure Service with the base system tools- this article provides a reference:

MCP Development with Python, and the Azure Container Instance

Gemini Live Models

More details are available here:

Gemini 3.1 Flash Live Preview | Gemini API | Google AI for Developers

The Gemini Live Models bring unique real-time capabilities than can be used directly from an Agent. A summary of the model is also available here:

https://deepmind.google/models/model-cards/gemini-3-1-flash-live/

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

Where do I start?

The strategy for starting multimodal real time agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, a minimal ADK Agent is built and tested locally. Next — the entire solution is deployed to Azure ACA.

Setup the Basic Environment

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-azure
cd gemini31-aci

Then run init.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Build the User Interface

The front end files provide the user interface:

xbill@penguin:~/gemini-cli-azure/gemini31-aci$ make frontend
cd frontend && npm install && npm run build

added 218 packages, and audited 219 packages in 2s

49 packages are looking for funding
  run `npm fund` for details

1 high severity vulnerability

To address all issues, run:
  npm audit fix

Run `npm audit` for details.

> frontend@0.0.0 build
> vite build

vite v7.3.1 building client environment for production...
✓ 33 modules transformed.
dist/index.html 0.46 kB │ gzip: 0.29 kB
dist/assets/index-xOQlTZZB.css 21.60 kB │ gzip: 4.54 kB
dist/assets/index-0hbet2qm.js 214.56 kB │ gzip: 67.44 kB
✓ built in 1.02s
xbill@penguin:~/gemini-cli-azure/gemini31-aca$

Test The User Interface

The mock server test script allows the interface and Browser settings to be set to allow multimedia — without using any external Model calls or tokens:

xbill@penguin:~/gemini-cli-azure/gemini31-aci$ make mock
. ./mock.sh
http://127.0.0.1:8080/
Serving static files from: /home/xbill/way-back-home/level_3_gemini/frontend/dist
INFO: Started server process [24098]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

The Deployed mock front-end will look similar to:

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the biometric_agent:

xbill@penguin:~/gemini-cli-azure/gemini31-aci$ make testadk
. ./testadk.sh
connect to local ADK CLI 

Log setup complete: /tmp/agents_log/agent.20260406_160553.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/cli.py:204: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.local/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
Running agent biometric_agent, type exit to exit.

[biometric_agent]: Scanner Online.




  
  
  Test The ADK Web Interface


This tests the Audio / Video ADK agent interactions:



xbill@penguin:~/gemini-cli-azure/gemini31-aci$ make adk
. ./runadk.sh
connect on http://127.0.0.1:8000/

2026-04-06 16:06:25,026 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-06 16:06:25,026 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/way-back-home/level_3_gemini/backend/app
2026-04-06 16:06:25,026 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/way-back-home/level_3_gemini/backend/app/.adk/artifacts
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/fast_api.py:193: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.local/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [24350]
INFO: Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at [http://0.0.0.0:8000.](http://0.0.0.0:8000.) |
+-----------------------------------------------------------------------------+

INFO: Application startup complete.
INFO: Uvicorn running on [http://0.0.0.0:8000](http://0.0.0.0:8000) (Press CTRL+C to quit)






Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:



Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:




adk web --host 0.0.0.0 --allow_origins 'regex:.*'







  
  
  Lint and Test the Main Python Code


The final step is to build, lint, and test the main Python code.

To Lint:




xbill@penguin:~/gemini-cli-azure/gemini31-aci$ make lint
ruff check .
All checks passed!
ruff format --check .
10 files already formatted
cd frontend && npm run lint

> frontend@0.0.0 lint
> eslint .

xbill@penguin:~/gemini-cli-azure/gemini31-aca$






To Test:




xbill@penguin:~/gemini-cli-azure/gemini31-aci$ make test
python -m pytest
============================================================ test session starts ============================================================
platform linux -- Python 3.13.12, pytest-9.0.2, pluggy-1.6.0
rootdir: /home/xbill
configfile: pyproject.toml
plugins: anyio-4.11.0
collected 9 items / 1 skipped                                                                                                               

backend/app/biometric_agent/test_agent.py ..... [55%]
test_ws_backend.py .. [77%]
test_ws_backend_v2.py ..







  
  
  Running Locally


The main Python Code can then be run locally:




xbill@penguin:~/gemini-cli-azure/gemini31-aci$ make run
. ./biosync.sh
Local URL
http://127.0.0.1:8080/
2026-04-06 16:09:42,868 - INFO - System Config: 2.0 FPS, 10.0s Heartbeat
Serving static files from: /home/xbill/way-back-home/level_3_gemini/frontend/dist
INFO: Started server process [25860]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)






Then connect to the local front end:




  
  
  Deploying to Google Azure ACA


A utility script runs the deployment to Azure ACA. Use the deploy version from the local system:




xbill@penguin:~/gemini-cli-azure/gemini31-aci$ make deploy
./deploy.sh
                                                                    0.0s 0.0s






You can validate the final result by checking the messages:




Azure Deployment complete.
URL: https://biometric-scout-app.wonderfuldune-ec8eec50.eastus.azurecontainerapps.io
xbill@penguin:~/gemini-cli-azure/gemini31-aci$






Once the container is deployed- you can then get the endpoint:




xbill@penguin:~/gemini-cli-azure/gemini31-aca$ make status
Name State URL
------------------- --------- -----------------------------------------------------------------------
biometric-scout-app Succeeded biometric-scout-app.wonderfuldune-ec8eec50.eastus.azurecontainerapps.io
xbill@penguin:~/gemini-cli-azure/gemini31-aca$ make endpoint
biometric-scout-app.wonderfuldune-ec8eec50.eastus.azurecontainerapps.io
xbill@penguin:~/gemini-cli-azure/gemini31-aca$






The service will be visible in the Azure console:




biometric-scout-ssl-pengu.eastus.azurecontainer.io









  
  
  Running the Web Interface


Start a connection to the Azure deployed app:




biometric-scout-ssl-pengu.eastus.azurecontainer.io






Then connect to the app :



Then use the Live model to process audio and video:



Finally — complete the sequence:




  
  
  Project Code Review


Gemini CLI was used for a final project review:




✦ The code is in great shape. All 8 tests passed, and the entire project is compliant with the linter rules.

  There is one warning related to an experimental feature (PLUGGABLE_AUTH) in the Google ADK, but this is informational and doesn't indicate an
  error.

  Since the automated checks are clean, what specific part of the codebase would you like me to review? For example, we could look at:

   * The agent's logic in backend/app/biometric_agent/agent.py
   * The frontend WebSocket and component logic in frontend/src/BiometricLock.jsx
   * The Azure deployment scripts
   * The overall architecture







  
  
  Summary


The Agent Development Kit was used to enable a multi-modal agent using the Gemini Live Model. This Agent was tested locally with the CLI and then deployed to Azure ACI. Several key take-aways and lessons learned were summarized from working with the transition to a new Live Gemini LLM model. Finally, Gemini CLI was used for a complete project code review.

Multi-Agent A2A with the Agent Development Kit(ADK), Amazon ECS Express, and Gemini CLI

xbill — Fri, 17 Apr 2026 14:42:33 +0000

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build Multi-Agent Applications with A2A protocol support using the Python programming language deployed to AWS ECS Express.

Aren’t There a Billion Python ADK Demos?

Yes there are.

Python has traditionally been the main coding language for ML and AI tools. The goal of this article is to provide a multi-agent test bed for building, debugging, and deploying multi-agent applications.

Rock and roll ain’t noise pollution

So what is different about this lab compared to all the others out there?

This is one of the first deep dives into a Multi-Agent application leveraging the advanced tooling of Gemini CLI. The starting point for the demo was an existing Codelab- which was updated and re-engineered with Gemini CLI.

The original Codelab- is here:

Building a Multi-Agent System | Google Codelabs

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.13

Amazon ECS Express

Amazon ECS Express Mode (announced Nov 2025) is a simplified deployment feature for Amazon Elastic Container Service (ECS) designed to rapidly launch containerized applications, APIs, and web services on AWS Fargate. It automates infrastructure setup — including load balancing, networking, scaling, and HTTPS endpoints — allowing developers to deploy from container image to production in a single step.

More details are available here:

Amazon ECS Express Mode

The ECS status is visible from the AWS Console:

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

Agent Skills

Gemini CLI can be customized to work with ADK agents. Both an Agent Development MCP server, and specific Agent skills are available.

More details are here:

Agent Development Kit (ADK)

To get the Agent Skills in Gemini CLI:

> /skills list
Available Agent Skills:

and the ADK documentation:

> /mcp list
Configured MCP servers:
🟢 adk-docs-mcp (from adk-docs-ext) - Ready (2 tools)
  Tools:
  - mcp_adk-docs-mcp_fetch_docs
  - mcp_adk-docs-mcp_list_doc_sources

Where do I start?

The strategy for starting multi agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, ADK Multi-Agent is built, debugged, and tested locally. Finally — the entire solution is deployed to Google Cloud Run.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. All of the relevant code examples and documentation is available in GitHub.

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-aws
cd multi-ecsexpress

Then run init2.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init2.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

aws login --remote

Finally install the packages and dependencies:

make install

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the researcher agent:

xbill@penguin:~/gemini-cli-aws/multi-eks/agents$ adk run researcher
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260412_164250.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
{"asctime": "2026-04-12 16:42:50,986", "name": "root", "levelname": "INFO", "message": "Logging initialized for researcher", "filename": "logging_config.py", "lineno": 54, "service": "researcher", "log_level": "INFO"}
{"asctime": "2026-04-12 16:42:50,987", "name": "researcher.agent", "levelname": "INFO", "message": "Initialized researcher agent with model: gemini-2.5-flash", "filename": "agent.py", "lineno": 85}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.envs", "levelname": "INFO", "message": "Loaded .env file for researcher at /home/xbill/gemini-cli-aws/multi-eks/.env", "filename": "envs.py", "lineno": 83}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/multi-eks/agents", "filename": "local_storage.py", "lineno": 84}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using file artifact service at /home/xbill/gemini-cli-aws/multi-eks/agents/researcher/.adk/artifacts", "filename": "local_storage.py", "lineno": 110}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.service_factory", "levelname": "INFO", "message": "Using in-memory memory service", "filename": "service_factory.py", "lineno": 266}
{"asctime": "2026-04-12 16:42:50,993", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Creating local session service at /home/xbill/gemini-cli-aws/multi-eks/agents/researcher/.adk/session.db", "filename": "local_storage.py", "lineno": 60}
Running agent researcher, type exit to exit.



  
  
  Test The ADK Web Interface


This tests the ADK agent interactions with a browser:



xbill@penguin:~/gemini-cli-aws/multi-eks/agents$ adk web --host 0.0.0.0
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-12 16:43:14,152 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-12 16:43:14,153 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/multi-eks/agents
2026-04-12 16:43:14,153 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/gemini-cli-aws/multi-eks/agents/.adk/artifacts
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/fast_api.py:198: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.local/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [32675]
INFO: Waiting for application startup.






Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:



Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:




adk web --host 0.0.0.0 --allow_origins 'regex:.*'







  
  
  Multi Agent Design


The multi-agent deployment consists of 5 agents:


Researcher
Judge
Orchestrator
Content Builder
Course Builder


For a detailed analysis of the multi-agent architecture- this article provides the background information:

Multi-Agent A2A with the Agent Development Kit(ADK), Cloud Run, and Gemini CLI


  
  
  Running/Testing/Debugging Locally


The main Makefile has been extended with extensive targets for managing the agents on the local development environment.

The key targets include:




xbill@penguin:~/multi-agent$ make help
Available commands:
  install - Install all dependencies for root, agents, and app
  start - Start all services locally (alias for start-local)
  stop - Stop all local services (alias for stop-local)
  run - Start all services locally (alias for start-local)
  local - Show local service URLs
  start-local - Start all local services in background
  stop-local - Stop all local processes
  test - Run all tests (pytest)
  test-researcher - Test the Researcher agent directly
  test-judge - Test the Judge agent directly
  test-orchestrator - Test the Orchestrator logic
  lint - Run linting checks (ruff)
  deploy - Deploy all services to Cloud Run
  destroy - Delete all Cloud Run services
  clean - Remove caches and logs






First check for local running agents:




xbill@penguin:~/gemini-cli-aws$ make status
Checking status of locally running agents and servers...
--- Network Status ---
No services listening on expected ports (8000-8004, 5173).
--- Process Status ---
No matching processes found.






Then all the agents can be started together:




✦ The frontend has been built and all local services (Researcher, Judge, Content Builder, Orchestrator, App Backend, and Frontend dev server) have
  been started in the background.

   - Frontend: http://localhost:5173 (http://localhost:5173)
   - Backend: http://localhost:8000 (http://localhost:8000)

  Logs for each service are available in the project root: researcher.log, judge.log, content_builder.log, orchestrator.log, backend.log, and
  frontend.log.






Then connect to the front end locally:



And the entire agent system will run in the local environment:




  
  
  Local Logging / Debugging


Gemini CLI has full access to the local agent logs for debugging and troubleshooting:




> review the local logs for the multi-agent run
✦ I will check run_local.sh and the project structure to determine where logs are stored or how they are generated.






This will verify the local operation of the code:




✦ The local logs confirm a successful multi-agent run for the topic "the history of the internet." Here is a summary of the execution flow:

* Orchestrator (orchestrator.log): Successfully managed the pipeline. It captured the topic, coordinated the Research-Judge loop, and escalated to
     content generation after the first iteration.
   * Researcher (researcher.log): Gathered approximately 9.2KB of research data using the google_search tool. It completed its task with a 200 OK
     response.
   * Judge (judge.log): Evaluated the findings and gave a "pass" status. The judge noted that the research was "comprehensive, accurate, and
     well-structured," making it an "excellent foundation for educational content."
   * Content Builder (content_builder.log): Successfully transformed the validated research into a structured Markdown course module and finished
     execution.
   * Backend & Frontend (backend.log, frontend.log): The FastAPI backend (port 8000) and Vite frontend (port 5173) are running and communicating with
     the orchestrator as expected.

Notable Observation:
   * A minor warning appeared in researcher.log: Researcher callback: 'response' not found or has no parts. However, this did not impact the
     successful completion of the research or the overall pipeline.

All services are currently active and logged at the DEBUG level as specified in run_local.sh.







  
  
  Deploying to Amazon Elastic Container Service (ECS)


The project level Makefile has targets for managing the Agent deployment to serverless endpoints. You can submit the build for ECS Express deployment:




make deploy
✦ The deployment was successful, and all 5 services are active on AWS ECS Express. You can access the Web App at the following URL:

  Web App (Course Creator): https://ad-65d6861112ff49099782001efe5e2721.ecs.us-east-1.on.aws

  The other microservices are also deployed and integrated:
   - Researcher: https://ad-8779b3dc720e4d9e9ca9b1091499084a.ecs.us-east-1.on.aws
   - Judge: https://ad-ab123be1fad04a9390e1d918f9b8ec04.ecs.us-east-1.on.aws
   - Content Builder: https://ad-622b8527fd1f41668624714f62deee0f.ecs.us-east-1.on.aws
   - Orchestrator: https://ad-c0f70b2d021744ec9761c2e54ca60287.ecs.us-east-1.on.aws






Once the containers are deployed- you can then get the endpoint:




✦ The Web App (Course Creator) endpoint is:

  https://ad-65d6861112ff49099782001efe5e2721.ecs.us-east-1.on.aws






The service will be visible in the AWS console:



And the entire system can be tested:




> make e2e-test-ecsexpress

✦ The end-to-end test of the AI Course Creator on AWS ECS Express was successful. The system, comprising 5 microservices, correctly researched
  "The History of the Internet," evaluated the findings, and generated a structured 4-module course. The public URL for the Web App is:

  https://ad-65d6861112ff49099782001efe5e2721.ecs.us-east-1.on.aws








  
  
  Running the Web Interface


Start a connection to the Cloud Run deployed app:




http://a27c61bc6fb3c425ca13d862e0fe4aed-865627292.us-east-1.elb.amazonaws.com






Then connect to the app :



Then use online course generator:




  
  
  Final Gemini CLI Code Review


As a final step — Gemini CLI was used for a full code review of the project:




✦ This multi-agent project is a well-engineered application of ADK 2.5 and the A2A protocol. The separation of specialized agents (Researcher,
  Judge, Content Builder) coordinated by a central Orchestrator demonstrates a mature microservice-oriented design.

Key Strengths
   * Coordinated Orchestration: The use of SequentialAgent and LoopAgent creates a robust, iterative research-judge cycle.
   * Resilient State Flow: The strategy of passing data through event content and "recovering" it via before_agent_callback heuristics is a clever
     way to handle state across distributed, independent session stores.
   * Polished Streaming: The web app's SSE implementation, specifically the greedy overlap deduplication (merge_strings) and system message
     cleanup, ensures a high-quality user experience despite the inherent noise in multi-agent LLM streams.
   * Cloud-Native Readiness: Using Identity Tokens for authenticated service-to-service communication and middleware for dynamic A2A URL rewriting
     makes the system ready for production deployment on Cloud Run.







  
  
  Summary


The Agent Development Kit (ADK) was used to build a multi-agent system with A2A support using the Gemini Flash LLM Model. This application was tested locally with Gemini CLI and then deployed to AWS ECS Express. Finally, Gemini CLI was used for a complete project code review.

Multi-Agent A2A with the Agent Development Kit(ADK), Azure ACA, and Gemini CLI

xbill — Thu, 16 Apr 2026 18:48:19 +0000

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build Multi-Agent Applications with A2A protocol support using the Python programming language.

Aren’t There a Billion Python ADK Demos?

Yes there are.

What you talkin ‘bout Willis?

So what is different about this lab compared to all the others out there?

The original Codelab- is here:

Building a Multi-Agent System | Google Codelabs

What Is Python?

Python is an interpreted language that allows for rapid development and testing and has deep libraries for working with ML and AI:

Welcome to Python.org

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.13

Azure Container App Service

Azure Container Apps (ACA) is a fully managed, serverless platform designed for running containerized applications and microservices without managing underlying infrastructure. Built on Azure Kubernetes Service (AKS), it offers built-in autoscaling (including to zero), traffic splitting for blue/green deployments, and Dapr integration, making it ideal for event-driven, API, and background processing workloads.

https://azure.microsoft.com/en-us/products/container-apps

Why would I want Gemini CLI with Azure? Isn’t that a Google Thing?

Azure Container App Configuration

To configure your Azure Service with the base system tools- this article provides a reference:

MCP Development with Python, and Azure Container Apps

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

Agent Skills

Gemini CLI can be customized to work with ADK agents. Both an Agent Development MCP server, and specific Agent skills are available.

More details are here:

Agent Development Kit (ADK)

To get the Agent Skills in Gemini CLI:

> /skills list
Available Agent Skills:

- adk-cheatsheet
      MUST READ before writing or modifying ADK agent code. ADK API quick reference for Python — agent types, tool definitions, orchestration
      patterns, callbacks, and state management. Includes an index of all ADK documentation pages. Do NOT use for creating new projects (use
      adk-scaffold).
  - adk-deploy-guide
      MUST READ before deploying any ADK agent. ADK deployment guide — Agent Engine, Cloud Run, GKE, CI/CD pipelines, secrets, observability, and
      production workflows. Use when deploying agents to Google Cloud or troubleshooting deployments. Do NOT use for API code patterns (use
      adk-cheatsheet), evaluation (use adk-eval-guide), or project scaffolding (use adk-scaffold).
  - adk-dev-guide
      ALWAYS ACTIVE — read at the start of any ADK agent development session. ADK development lifecycle and mandatory coding guidelines —
      spec-driven workflow, code preservation rules, model selection, and troubleshooting.
  - adk-eval-guide
      MUST READ before running any ADK evaluation. ADK evaluation methodology — eval metrics, evalset schema, LLM-as-judge, tool trajectory
      scoring, and common failure causes. Use when evaluating agent quality, running adk eval, or debugging eval results. Do NOT use for API code
      patterns (use adk-cheatsheet), deployment (use adk-deploy-guide), or project scaffolding (use adk-scaffold).
  - adk-observability-guide
      MUST READ before setting up observability for ADK agents or when analyzing production traffic, debugging agent behavior, or improving agent
      performance. ADK observability guide — Cloud Trace, prompt-response logging, BigQuery Agent Analytics, third-party integrations, and
      troubleshooting. Use when configuring monitoring, tracing, or logging for agents, or when understanding how a deployed agent handles real
      traffic.
  - adk-scaffold
      MUST READ before creating or enhancing any ADK agent project. Use when the user wants to build a new agent (e.g. "build me a search agent")
      or enhance an existing project (e.g. "add CI/CD to my project", "add RAG").

and the ADK documentation:

> /mcp list
Configured MCP servers:

🟢 adk-docs-mcp (from adk-docs-ext) - Ready (2 tools)
  Tools:
  - mcp_adk-docs-mcp_fetch_docs
  - mcp_adk-docs-mcp_list_doc_sources

Where do I start?

The strategy for starting multi agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, ADK Multi-Agent is built, debugged, and tested locally. Finally — the entire solution is deployed to Azure ACA.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. All of the relevant code examples and documentation is available in GitHub.

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-azure
cd mulit-aca

Then run init2.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init2.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Finally install the packages and dependencies:

make install

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the researcher agent:

xbill@penguin:~/multi-agent/agents$ adk run researcher
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260410_174725.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
{"asctime": "2026-04-10 17:47:25,496", "name": "root", "levelname": "INFO", "message": "Logging initialized for researcher", "filename": "logging_config.py", "lineno": 54, "service": "researcher", "log_level": "INFO"}
{"asctime": "2026-04-10 17:47:25,496", "name": "researcher.agent", "levelname": "INFO", "message": "Initialized researcher agent with model: gemini-2.5-flash", "filename": "agent.py", "lineno": 85}
{"asctime": "2026-04-10 17:47:25,497", "name": "google_adk.google.adk.cli.utils.envs", "levelname": "INFO", "message": "Loaded .env file for researcher at /home/xbill/multi-agent/agents/researcher/.env", "filename": "envs.py", "lineno": 83}
{"asctime": "2026-04-10 17:47:25,497", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using per-agent session storage rooted at /home/xbill/multi-agent/agents", "filename": "local_storage.py", "lineno": 84}
{"asctime": "2026-04-10 17:47:25,497", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using file artifact service at /home/xbill/multi-agent/agents/researcher/.adk/artifacts", "filename": "local_storage.py", "lineno": 110}
{"asctime": "2026-04-10 17:47:25,498", "name": "google_adk.google.adk.cli.utils.service_factory", "levelname": "INFO", "message": "Using in-memory memory service", "filename": "service_factory.py", "lineno": 266}
{"asctime": "2026-04-10 17:47:25,501", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Creating local session service at /home/xbill/multi-agent/agents/researcher/.adk/session.db", "filename": "local_storage.py", "lineno": 60}
Running agent researcher, type exit to exit.



  
  
  Test The ADK Web Interface


This tests the ADK agent interactions with a browser:



xbill@penguin:~/multi-agent/agents$ adk web --host 0.0.0.0
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-10 17:49:11,850 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-10 17:49:11,850 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/multi-agent/agents
2026-04-10 17:49:11,850 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/multi-agent/agents/.adk/artifacts
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/cli/fast_api.py:198: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [16063]
INFO: Waiting for application startup.

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






Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:



Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:




adk web --host 0.0.0.0 --allow_origins 'regex:.*'







  
  
  Multi Agent Design


The multi-agent deployment consists of 5 agents:


Researcher
Judge
Orchestrator
Content Builder
Course Builder


An overview of the multi-agent system can be found here:

Multi-Agent A2A with the Agent Development Kit(ADK), Cloud Run, Agent Skills, and Gemini CLI


  
  
  Running/Testing/Debugging Locally


The main Makefile has been extended with extensive targets for managing the agents on the local development environment.

The key targets include:




xbill@penguin:~/gemini-cli-azure/multi-aca$ make help
Available commands:
  install - Install all dependencies for root, agents, and app
  start - Start all services locally (alias for start-local)
  stop - Stop all local services (alias for stop-local)
  run - Start all services locally (alias for start-local)
  local - Show local service URLs
  start-local - Start all local services in background
  stop-local - Stop all local processes
  test - Run all tests (pytest)
  test-researcher - Test the Researcher agent directly
  test-judge - Test the Judge agent directly
  test-orchestrator - Test the Orchestrator logic
  test-e2e-aca - Run ACA E2E test (Full Flow)
  lint - Run linting checks (ruff)
  deploy-aca - Deploy all services to Azure Container Apps (ACA)
  destroy-aca - Delete ACA resources
  status-aca - Show ACA status
  endpoint-aca - Show ACA service endpoint
  clean - Remove caches and logs






First check for local running agents:




 > make status
✦ I will run the make status command to check the status of your local services.

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Running 'make status' to check local services. │
│ │
│ Checking status of locally running agents and servers... │
│ --- Network Status --- │
│ No services listening on expected ports (8000-8004, 5173). │
│ --- Process Status --- │
│ No matching processes found. │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ No local services are currently running.






Then all the agents can be started together:




make start
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Starting all local services in the background. │
│ │
│ Stopping any existing agent and server processes... │
│ Starting all agents in background... │
│ Waiting for sub-agents to start... │
│ All agents started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log │
│ Starting App Backend in background... │
│ Starting Frontend dev server in background... │
│ All services started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log, backend.log, frontend.log │
│ Frontend: http://localhost:5173 │
│ Backend: http://localhost:8000 │
│                                        

make status
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Checking status of local services. │
│ │
│ ... first 22 lines hidden (Ctrl+O to show) ... │
│ dge/.well-known/agent-card.json; \ export CONTENT_BUILDER_AGENT_CARD_URL=http://localhost:8003/a2a/content_builder/.well-known/agent-card.jso │
│ n; \ /home/xbill/.pyenv/shims/python3 -m shared.adk_app --host 0.0.0.0 --port 8004 agents/orchestrator" │
│ xbill 14269 9.3 3.1 248416 148664 ? S 20:27 0:02 /home/xbill/.pyenv/versions/3.13.13/bin/python3 -m shared.adk_app --host 0.0 │
│ .0.0 --port 8004 agents/orchestrator │
│ xbill 14273 0.0 0.0 2584 1668 ? S 20:27 0:00 /bin/sh -c /bin/bash -c "source .env 2>/dev/null || true; \ export AGENT_SER │
│ VER_URL=http://localhost:8004; \ export AGENT_NAME=orchestrator; \ export PORT=8000; \ cd app && /home/xbill/.pyenv/shims/python3 main.py" │
│ xbill 14275 0.0 0.0 6940 3312 ? S 20:27 0:00 /bin/bash -c source .env 2>/dev/null || true; export AGENT_SERVER_URL=http:/ │
│ /localhost:8004; export AGENT_NAME=orchestrator; export PORT=8000; cd app && /home/xbill/.pyenv/shims/python3 main.py │
│ xbill 14278 8.4 3.1 1345296 144520 ? Sl 20:27 0:02 /home/xbill/.pyenv/versions/3.13.13/bin/python3 main.py │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The local agents and the backend server are running and listening on ports 8000-8004. The Vite dev server (port 5173) is still not appearing in the
  network status.






The entire project can be linted and tested as unit:




 > make lint
✦ I will run the make lint command to confirm that all linting checks pass.

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Run linting checks to confirm they pass. │
│ │
│ ruff check . │
│ All checks passed! │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ make lint completed successfully with no errors.

 > make test
✦ I will run the project's test suite using make test.

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Run all tests using pytest. │
│ │
│ ... first 41 lines hidden (Ctrl+O to show) ... │
│ agents/orchestrator/agent.py:294 │
│ /home/xbill/gemini-cli-azure/multi-aca/agents/orchestrator/agent.py:294: UserWarning: [EXPERIMENTAL] RemoteA2aAgent: ADK Implementation for │
│ A2A support (A2aAgentExecutor, RemoteA2aAgent and corresponding supporting components etc.) is in experimental mode and is subject to breaki │
│ ng changes. A2A protocol and SDK are themselves not experimental. Once it's stable enough the experimental mode will be removed. Your feedbac │
│ k is welcome. │
│ content_builder = RemoteA2aAgent( │
│ │
│ -- Docs: https://docs.pytest.org/en/stable/how-to/capture-warnings.html │
│ ====================================================== 30 passed, 4 warnings in 7.71s ======================================================= │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ make test passed all 30 tests successfully.






And end to end tested:




✓ Shell Running the end-to-end tests for the project. │
│ │
│ Running end-to-end test against http://localhost:8000... │
│ {"type": "progress", "text": "\ud83d\ude80 Connected to backend, starting research..."} │
│ {"type": "progress", "text": "\ud83d\ude80 Starting the course creation pipeline..."} │
│ {"type": "progress", "text": "\ud83d\udd0d Research is starting..."} │
│ {"type": "progress", "text": "\ud83d\udd0d Researcher is gathering information..."} │
│ {"type": "progress", "text": "\u2696\ufe0f Judge is evaluating findings..."} │
│ {"type": "progress", "text": "\u2696\ufe0f Judge is evaluating findings..."} │
│ {"type": "progress", "text": "\u270d\ufe0f Building the final course content..."} │
│ {"type": "progress", "text": "\u270d\ufe0f Content Builder is writing the course..."} │






Then connect to the local front end:



And the entire agent system will run in the local environment:




  
  
  Local Logging / Debugging


Gemini CLI has full access to the local agent logs for debugging and troubleshooting:




✦ I've analyzed the logs from your e2e run. All agents (researcher, judge, content_builder, orchestrator) and both frontend and backend services
  started successfully. The course creation pipeline ran as expected: the orchestrator initiated the "history of the internet" course, the researcher
  gathered information, the judge approved it, and the content builder generated the course content.







  
  
  Deploying to Azure ACA


The project level Makefile has targets for managing the Agent deployment to serverless endpoints:




xbill@penguin:~/gemini-cli-azure/multi-aca$ az login
A web browser has been opened at https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize. Please continue the login in the web browser. If no web browser is available or if the web browser fails to open, use device code flow with `az login --use-device-code`.







A utility script check the deployment to Azure ACA:





xbill@penguin:~/gemini-cli-azure/multi-aca$ make status-aca
./aca/status-aca.sh
Checking Azure Container Apps status in adk-rg-aca...







You can then deploy the services:




 > make deploy

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Execute the 'deploy' target in the Makefile to deploy services to Azure Container Apps. │
│ │
│ ... first 212 lines hidden (Ctrl+O to show) ... │
│ Orchestrator FQDN: orchestrator.prouddesert-76322785.westus2.azurecontainerapps.io │
│ Deploying course-creator to ACA on port 8080... │
│ WARNING: No credential was provided to access Azure Container Registry. Trying to look up credentials... │
│ WARNING: Adding registry password as a secret with name "adkacrpenguinazurecrio-adkacrpenguin" │
│ WARNING: │
│ Container app created. Access your app at https://course-creator.prouddesert-76322785.westus2.azurecontainerapps.io/ │
│ │
│ === Deployment Complete === │
│ Public App URL: https://course-creator.prouddesert-76322785.westus2.azurecontainerapps.io │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The make deploy command executed successfully, deploying all services to Azure Container Apps. The public URL for the course-creator application
  is: https://course-creator.prouddesert-76322785.westus2.azurecontainerapps.io.







Once the containers are deployed- you can then get the endpoint:




 > make status-aca

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Execute the 'status-aca' target in the Makefile to check the status of Azure Container Apps. │
│ │
│ ./aca/status-aca.sh │
│ Checking Azure Container Apps status in adk-rg-aca... │
│ Name State FQDN │
│ --------------- --------- ------------------------------------------------------------------ │
│ researcher Succeeded researcher.prouddesert-76322785.westus2.azurecontainerapps.io │
│ judge Succeeded judge.prouddesert-76322785.westus2.azurecontainerapps.io │
│ content-builder Succeeded content-builder.prouddesert-76322785.westus2.azurecontainerapps.io │
│ orchestrator Succeeded orchestrator.prouddesert-76322785.westus2.azurecontainerapps.io │
│ course-creator Succeeded course-creator.prouddesert-76322785.westus2.azurecontainerapps.io │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The make status-aca command has successfully reported the status of all Azure Container Apps, confirming they are all in a 'Succeeded' state.







And check the endpoint:




 > make endpoint-aca

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Execute the 'endpoint-aca' target in the Makefile to get the public URL of the Azure Container Apps. │
│ │
│ ./aca/endpoint-aca.sh │
│ --- Azure ACA Endpoint --- │
│ https://course-creator.prouddesert-76322785.westus2.azurecontainerapps.io │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The make endpoint-aca command has successfully retrieved and displayed the public URL for the Azure Container App.






The service will be visible in the Cloud Run console:




  
  
  Test End to End in ACA


The entire agent system is tested on the remote Azure endpoint:




✦ The make endpoint-aca command has successfully retrieved and displayed the public URL for the Azure Container App.
 > make e2e-test-aca

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Execute the 'e2e-test-aca' target in the Makefile to run end-to-end tests against the Azure Container Apps. │
│ │
│ ... first 69 lines hidden (Ctrl+O to show) ... │
│ Challenges:**\n * Concerns about data privacy and cybersecurity.\n * The \"digital divide\" highlights inequalities in internet acc │
│ ess.\n * Debates around net neutrality and potential social isolation.\n\n### Key Figures\n* **Mark Zuckerberg (b. 1984):** Co-founder │
│ of Facebook, a pioneering social media platform.\n* **Steve Jobs (1955-2011):** Co-founder of Apple Inc., whose iPhone spurred the mobile │
│ internet revolution.\n* **Chad Hurley (b. 1977) & Steve Chen (b. 1978):** Co-founders of YouTube.\n\n### Impact\n* The modern internet is │
│ an indispensable social, economic, and cultural ecosystem.\n* It facilitates communication, commerce, education, and governance on an unpr │
│ ecedented scale.\n* It continuously evolves with new technologies like AI, blockchain, and the Internet of Things (IoT)."} │
│ │
│ E2E Test Completed successfully! │
│ make[1]: Leaving directory '/home/xbill/gemini-cli-azure/multi-aca' │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The make e2e-test-aca command executed successfully, demonstrating the functional deployment of your multi-agent system on Azure ACA by generating
  a complete course on the history of the internet.







  
  
  Running the Web Interface


Start a connection to the Cloud Run deployed app:




https://course-creator.prouddesert-76322785.westus2.azurecontainerapps.io






Then connect to the app :



Then use online course generator:




  
  
  Final Gemini CLI Code Review


As a final step — Gemini CLI was used for a full code review of the project:




  Overall Code Review Summary

  After reviewing the app and agents directories, I can say this is an exceptionally well-engineered multi-agent system.

  High-Level Architecture:
  The architecture is sophisticated and effective. The use of a main orchestrator to manage a pipeline of specialized agents (researcher, judge,
  content_builder) is a strong and scalable pattern. The inclusion of a research-and-refine loop with the judge agent is a standout feature that
  significantly enhances the quality of the final output.

  Key Strengths:
   1. Expert ADK Usage: The project demonstrates a deep understanding of the Google ADK, using advanced features like SequentialAgent, LoopAgent,
      RemoteA2aAgent, structured Pydantic outputs, and agent callbacks to their full potential.
   2. Excellent Prompt Engineering: The instruction prompts for all agents are clear, specific, and well-crafted. This is the foundation of the
      system's success.
   3. Robust State Management: The custom StateCapturer agent is a brilliant, reusable utility that cleanly handles the flow of information between
      agents.
   4. Production-Ready Features: The system includes production-grade features like environment-aware authentication for service-to-service calls,
      robust error handling, and detailed logging.







  
  
  Summary


The Agent Development Kit (ADK) was used to build a multi-agent system with A2A support using the Gemini Flash LLM Model. This application was tested locally with Gemini CLI and then deployed to Azure ACA. Several key take-aways and lessons learned were summarized from debugging and testing the multi-agent system- including deep log reviews. Finally, Gemini CLI was used for a complete project code review.

Multi-Agent A2A with the Agent Development Kit(ADK), AWS Lightsail, and Gemini CLI

xbill — Thu, 16 Apr 2026 13:12:53 +0000

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build Multi-Agent Applications with A2A protocol support using the Python programming language.

Aren’t There a Billion Python ADK Demos?

Yes there are.

What you talkin ‘bout Willis?

So what is different about this lab compared to all the others out there?

The original Codelab- is here:

Building a Multi-Agent System | Google Codelabs

What Is Python?

Python is an interpreted language that allows for rapid development and testing and has deep libraries for working with ML and AI:

Welcome to Python.org

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.13

Amazon Lightsail

Amazon Lightsail is an easy-to-use virtual private server (VPS) provider and cloud platform designed by AWS for simpler workloads, offering developers pre-configured compute, storage, and networking for a low, predictable monthly price. It is ideal for hosting small websites, simple web apps, or creating development environments.

More information is available on the official site here:

Amazon's Simple Cloud Server | Amazon Lightsail

And this is the direct URL to the console:

https://lightsail.aws.amazon.com/ls/webapp/home/containers

The Lightsail console will look similar to:

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

Agent Skills

Gemini CLI can be customized to work with ADK agents. Both an Agent Development MCP server, and specific Agent skills are available.

More details are here:

Agent Development Kit (ADK)

To get the Agent Skills in Gemini CLI:

> /skills list
Available Agent Skills:

  - adk-cheatsheet
      MUST READ before writing or modifying ADK agent code. ADK API quick reference for Python — agent types, tool definitions, orchestration
      patterns, callbacks, and state management. Includes an index of all ADK documentation pages. Do NOT use for creating new projects (use
      adk-scaffold).
  - adk-deploy-guide
      MUST READ before deploying any ADK agent. ADK deployment guide — Agent Engine, Cloud Run, GKE, CI/CD pipelines, secrets, observability, and
      production workflows. Use when deploying agents to Google Cloud or troubleshooting deployments. Do NOT use for API code patterns (use
      adk-cheatsheet), evaluation (use adk-eval-guide), or project scaffolding (use adk-scaffold).
  - adk-dev-guide
      ALWAYS ACTIVE — read at the start of any ADK agent development session. ADK development lifecycle and mandatory coding guidelines —
      spec-driven workflow, code preservation rules, model selection, and troubleshooting.
  - adk-eval-guide
      MUST READ before running any ADK evaluation. ADK evaluation methodology — eval metrics, evalset schema, LLM-as-judge, tool trajectory
      scoring, and common failure causes. Use when evaluating agent quality, running adk eval, or debugging eval results. Do NOT use for API code
      patterns (use adk-cheatsheet), deployment (use adk-deploy-guide), or project scaffolding (use adk-scaffold).
  - adk-observability-guide
      MUST READ before setting up observability for ADK agents or when analyzing production traffic, debugging agent behavior, or improving agent
      performance. ADK observability guide — Cloud Trace, prompt-response logging, BigQuery Agent Analytics, third-party integrations, and
      troubleshooting. Use when configuring monitoring, tracing, or logging for agents, or when understanding how a deployed agent handles real
      traffic.
  - adk-scaffold
      MUST READ before creating or enhancing any ADK agent project. Use when the user wants to build a new agent (e.g. "build me a search agent")
      or enhance an existing project (e.g. "add CI/CD to my project", "add RAG").

and the ADK documentation:

> /mcp list
Configured MCP servers:

🟢 adk-docs-mcp (from adk-docs-ext) - Ready (2 tools)
  Tools:
  - mcp_adk-docs-mcp_fetch_docs
  - mcp_adk-docs-mcp_list_doc_sources

Where do I start?

The strategy for starting multi agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, ADK Multi-Agent is built, debugged, and tested locally. Finally — the entire solution is deployed to Google Cloud Run.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. All of the relevant code examples and documentation is available in GitHub.

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-aws

Then run init2.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init2.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Finally install the packages and dependencies:

cd multi-lightsail
make install


╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell make install [current working directory /home/xbill/multi-agent] (Running make install again after installing shared-utils in edita… │
│ │
│ ... first 101 lines hidden (Ctrl+O to show) ... │
│ Installing frontend dependencies... │
│ cd app/frontend && npm install │
│ │
│ up to date, audited 16 packages in 502ms │
│ │
│ 5 packages are looking for funding │
│ run `npm fund` for details │
│ │
│ found 0 vulnerabilities │
│ Output too long and was saved to: │
│ /home/xbill/.gemini/tmp/multi-agent/tool-outputs/session-7ec4dae7-3acf-49f5-b396-306929c22231/run_shell_command_1775912739511_0.txt │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the researcher agent:

xbill@penguin:~/gemini-cli-aws/multi-lightsail$ cd agents
xbill@penguin:~/gemini-cli-aws/multi-lightsail/agents$ adk run researcher/
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260415_170203.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
{"asctime": "2026-04-15 17:02:03,412", "name": "root", "levelname": "INFO", "message": "Logging initialized for researcher", "filename": "logging_config.py", "lineno": 54, "service": "researcher", "log_level": "INFO"}
{"asctime": "2026-04-15 17:02:03,413", "name": "researcher.agent", "levelname": "INFO", "message": "Initialized researcher agent with model: gemini-2.5-flash", "filename": "agent.py", "lineno": 85}
{"asctime": "2026-04-15 17:02:03,413", "name": "google_adk.google.adk.cli.utils.envs", "levelname": "INFO", "message": "Loaded .env file for researcher at /home/xbill/gemini-cli-aws/.env", "filename": "envs.py", "lineno": 83}
{"asctime": "2026-04-15 17:02:03,413", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/multi-lightsail/agents", "filename": "local_storage.py", "lineno": 84}
{"asctime": "2026-04-15 17:02:03,414", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using file artifact service at /home/xbill/gemini-cli-aws/multi-lightsail/agents/researcher/.adk/artifacts", "filename": "local_storage.py", "lineno": 110}
{"asctime": "2026-04-15 17:02:03,414", "name": "google_adk.google.adk.cli.utils.service_factory", "levelname": "INFO", "message": "Using in-memory memory service", "filename": "service_factory.py", "lineno": 266}
{"asctime": "2026-04-15 17:02:03,422", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Creating local session service at /home/xbill/gemini-cli-aws/multi-lightsail/agents/researcher/.adk/session.db", "filename": "local_storage.py", "lineno": 60}
Running agent researcher, type exit to exit.
[user]:

Test The ADK Web Interface

This tests the ADK agent interactions with a browser:

xbill@penguin:~/gemini-cli-aws/multi-lightsail/agents$ adk web --host 0.0.0.0
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-15 17:02:33,314 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-15 17:02:33,314 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/multi-lightsail/agents
2026-04-15 17:02:33,315 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/gemini-cli-aws/multi-lightsail/agents/.adk/artifacts
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/cli/fast_api.py:198: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [6882]
INFO: Waiting for application startup.

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

INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:

Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:

adk web --host 0.0.0.0 --allow_origins 'regex:.*'

Multi Agent Design

The multi-agent deployment consists of 5 agents:

Researcher
Judge
Orchestrator
Content Builder
Course Builder

A high level overview of the application can be found here:

Multi-Agent A2A with the Agent Development Kit(ADK), Cloud Run, Agent Skills, and Gemini CLI

Running/Testing/Debugging Locally

The main Makefile has been extended with extensive targets for managing the agents on the local development environment.

The key targets include:

xbill@penguin:~/gemini-cli-aws/multi-lightsail$ make help
Available commands:
  install - Install all dependencies for root, agents, and app
  start - Start all services locally (alias for start-local)
  stop - Stop all local services (alias for stop-local)
  run - Start all services locally (alias for start-local)
  local - Show local service URLs
  local-status - Check status of local processes
  start-local - Start all local services in background
  stop-local - Stop all local processes
  test - Run all tests (pytest)
  e2e-test - Run end-to-end test against localhost
  e2e-test-lightsail - Run end-to-end test against Lightsail endpoint
  lint - Run linting checks (ruff)
  deploy - Deploy all services to AWS Lightsail
  status - Show Lightsail service status
  endpoint - Show Lightsail service endpoint
  destroy - Delete Lightsail service
  deploy-lightsail - Deploy all services to AWS Lightsail
  lightsail-status - Show Lightsail service status
  endpoint-lightsail - Show Lightsail service endpoint
  destroy-lightsail - Delete Lightsail service
  clean - Remove caches and logs

First check for local running agents:

xbill@penguin:~/gemini-cli-aws/multi-lightsail$ make local-status
Checking status of locally running agents and servers...
--- Network Status ---
No services listening on expected ports (8000-8004, 5173).
--- Process Status ---
No matching processes found.

Then all the agents can be started together:

xbill@penguin:~/gemini-cli-aws/multi-lightsail$ make start
Stopping any existing agent and server processes...
Starting all agents in background...
Waiting for sub-agents to start...
All agents started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log
Starting App Backend in background...
Starting Frontend dev server in background...
All services started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log, backend.log, frontend.log
Frontend: [http://localhost:5173](http://localhost:5173)
Backend: [http://localhost:8000](http://localhost:8000)

The entire project can be linted and tested as unit:

> make local-status

xbill@penguin:~/gemini-cli-aws/multi-lightsail$ make local-status
Checking status of locally running agents and servers...
--- Network Status ---
tcp 0 0 0.0.0.0:8000 0.0.0.0:* LISTEN 8052/python3        
tcp 0 0 0.0.0.0:8001 0.0.0.0:* LISTEN 7673/python3        
tcp 0 0 0.0.0.0:8002 0.0.0.0:* LISTEN 7676/python3        
tcp 0 0 0.0.0.0:8003 0.0.0.0:* LISTEN 7678/python3        
tcp 0 0 0.0.0.0:8004 0.0.0.0:* LISTEN 8040/python3        
tcp 0 0 0.0.0.0:5173 0.0.0.0:* LISTEN 8393/node           
--- Process Status ---
xbill 7670 0.0 0.0 2584 1712 pts/1 S 17:06 0:00 /bin/sh -c /bin/bash -c "source .env 2>/dev/null || true; \ /home/xbill/.pyenv/shims/python3 -m shared.adk_app --host 0.0.0.0 --port 8001 --a2a agents/researcher"
xbill 7673 6.5 2.6 276948 172316 pts/1 S 17:06 0:03 /home/xbill/.pyenv/versions/3.13.13/bin/python3 -m shared.adk_app --host 0.0.0.0 --port 8001 --a2a agents/researcher
xbill 7674 0.0 0.0 2584 1716 pts/1 S 17:06 0:00 /bin/sh -c /bin/bash -c "source .env 2>/dev/null || true; \ /home/xbill/.pyenv/shims/python3 -m shared.adk_app --host 0.0.0.0 --port 8002 --a2a agents/judge"
xbill 7676 8.1 2.6 276952 172044 pts/1 S 17:06 0:03 /home/xbill/.pyenv/versions/3.13.13/bin/python3 -m shared.adk_app --host 0.0.0.0 --port 8002 --a2a agents/judge
xbill 7677 0.0 0.0 2584 1716 pts/1 S 17:06 0:00 /bin/sh -c /bin/bash -c "source .env 2>/dev/null || true; \ /home/xbill/.pyenv/shims/python3 -m shared.adk_app --host 0.0.0.0 --port 8003 --a2a agents/content_builder"
xbill 7678 5.8 2.6 277072 171964 pts/1 S 17:06 0:02 /home/xbill/.pyenv/versions/3.13.13/bin/python3 -m shared.adk_app --host 0.0.0.0 --port 8003 --a2a agents/content_builder
xbill 8037 0.0 0.0 2588 1648 pts/1 S 17:06 0:00 /bin/sh -c /bin/bash -c "source .env 2>/dev/null || true; \ export RESEARCHER_AGENT_CARD_URL=http://localhost:8001/a2a/researcher/.well-known/agent-card.json; \ export JUDGE_AGENT_CARD_URL=http://localhost:8002/a2a/judge/.well-known/agent-card.json; \ export CONTENT_BUILDER_AGENT_CARD_URL=http://localhost:8003/a2a/content_builder/.well-known/agent-card.json; \ /home/xbill/.pyenv/shims/python3 -m shared.adk_app --host 0.0.0.0 --port 8004 agents/orchestrator"
xbill 8040 6.3 2.3 259240 153756 pts/1 S 17:06 0:02 /home/xbill/.pyenv/versions/3.13.13/bin/python3 -m shared.adk_app --host 0.0.0.0 --port 8004 agents/orchestrator
xbill 8047 0.0 0.0 2584 1716 pts/1 S 17:06 0:00 /bin/sh -c /bin/bash -c "source .env 2>/dev/null || true; \ export AGENT_SERVER_URL=http://localhost:8004; \ export AGENT_NAME=orchestrator; \ export PORT=8000; \ cd app && /home/xbill/.pyenv/shims/python3 main.py"
xbill 8049 0.0 0.0 6940 3284 pts/1 S 17:06 0:00 /bin/bash -c source .env 2>/dev/null || true; export AGENT_SERVER_URL=http://localhost:8004; export AGENT_NAME=orchestrator; export PORT=8000; cd app && /home/xbill/.pyenv/shims/python3 main.py
xbill 8052 5.6 2.1 316764 138524 pts/1 Sl 17:06 0:02 /home/xbill/.pyenv/versions/3.13.13/bin/python3 main.py
xbill 8392 0.0 0.0 2588 1792 pts/1 S 17:06 0:00 sh -c vite --host 0.0.0.0
xbill 8393 1.0 1.3 9956808 88484 pts/1 Sl 17:06 0:00 node /home/xbill/gemini-cli-aws/multi-lightsail/app/frontend/node_modules/.bin/vite --host 0.0.0.0

And tested end to end locally:

xbill@penguin:~/gemini-cli-aws/multi-lightsail$ make e2e-test
Running end-to-end test against http://localhost:8000...
Temporary JSON file content: {"message": "Create a short course about the history of the internet", "user_id": "e2e_test_user"}
Executing: curl -s -X POST http://localhost:8000/api/chat_stream -H "Content-Type: application/json" -d @/tmp/tmp.WIIdN0xDv4 --no-buffer
{"type": "progress", "text": "\ud83d\ude80 Connected to backend, starting research..."}
{"type": "progress", "text": "\ud83d\ude80 Starting the course creation pipeline..."}
{"type": "progress", "text": "\ud83d\udd0d Research is starting..."}
{"type": "progress", "text": "\ud83d\udd0d Researcher is gathering information..."}
{"type": "progress", "text": "\u2696\ufe0f Judge is evaluating findings..."}
{"type": "progress", "text": "\u2696\ufe0f Judge is evaluating findings..."}
{"type": "progress", "text": "\u270d\ufe0f Building the final course content..."}
{"type": "progress", "text": "\u270d\ufe0f Content Builder is writing the course..."}

Then connect to the front end locally:

And the entire agent system will run in the local environment:

Local Logging / Debugging

Gemini CLI has full access to the local agent logs for debugging and troubleshooting:

✦ I've identified that the log files are located in the project root: researcher.log, judge.log, content_builder.log, orchestrator.log,
  backend.log, and frontend.log. I will now check the last few lines of each to get an overview of their current status.

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Read the last 20 lines of each log file. │
│ │
│ ... first 236 lines hidden (Ctrl+O to show) ... │
│ │
│ > ai-course-creator-frontend@1.0.0 dev │
│ > vite --host 0.0.0.0 │
│ │
│ │
│ VITE v6.4.2 ready in 265 ms │
│ │
│ ➜ Local: http://localhost:5173/ │
│ ➜ Network: http://100.115.92.203:5173/ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The logs confirm a successful end-to-end run of the AI Course Creator. The backend received a request at 17:08:25, and the orchestrator
  coordinated the researcher, judge, and content_builder agents, finishing at 17:09:14 with 8,348 characters of generated content. Specifically,
  the judge approved the 11,888 characters of research findings at 17:09:02, triggering the final content construction. All services reported 200
  OK status codes and the Vite frontend remains active on http://localhost:5173.

Deploying to Amazon Lightsail

The project level Makefile has targets for managing the Agent deployment to serverless endpoints. First authenticate to AWS:

xbill@penguin:~/gemini-cli-aws/multi-lightsail$ aws login --remote
Browser will not be automatically opened.
Please visit the following URL:

And save the credentials:

xbill@penguin:~/gemini-cli-aws/multi-lightsail$ source save-aws-creds.sh 
Exporting AWS credentials...
Successfully saved credentials to .aws_creds
The Makefile will now automatically use these for deployments.
xbill@penguin:~/gemini-cli-aws/multi-lightsail$

A utility script does the deployment to Lightsail. You can submit the build for cloud deployment:

✦ The Lightsail deployment and E2E test were successful. I've refreshed the AWS credentials, deployed all five agent containers, verified the
  endpoint, and confirmed the system's functionality by generating a "History of the Internet" course.

  Deployment Summary
   - Service Name: course-creator-service
   - Region: us-east-1
   - Endpoint: https://course-creator-service.6wpv8vensby5c.us-east-1.cs.amazonlightsail.com/
     (https://course-creator-service.6wpv8vensby5c.us-east-1.cs.amazonlightsail.com/)
   - Status: ACTIVE (Verified via HTTP 200 and E2E test)

  Agents Deployed
   1. Researcher: gemini-2.5-flash with Google Search.
   2. Judge: Content validation agent.
   3. Content Builder: Markdown course generator.
   4. Orchestrator: Sequential pipeline manager.
   5. App: FastAPI backend/SSE streamer.

  You can now access the web UI at the endpoint URL above.

The deployment status:

✦ The service is RUNNING and ACTIVE. Although the URL is showing as None in the table output—likely because publicEndpoint.url is nested
  differently than expected—I've already confirmed the correct URL with make endpoint-lightsail.

  Service Status
   - State: RUNNING
   - Deployment: ACTIVE
   - Verified URL: https://course-creator-service.6wpv8vensby5c.us-east-1.cs.amazonlightsail.com/
     (https://course-creator-service.6wpv8vensby5c.us-east-1.cs.amazonlightsail.com/)

  You're all set! The multi-agent system is live and fully functional on AWS Lightsail.

Once the containers are deployed- you can then get the endpoint:


 > make endpoint
✦ I will run make endpoint to retrieve the Lightsail service URL.

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell make endpoint │
│ │
│ https://course-creator-service.6wpv8vensby5c.us-east-1.cs.amazonlightsail.com/ │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The Lightsail service endpoint is:
  https://course-creator-service.6wpv8vensby5c.us-east-1.cs.amazonlightsail.com/
  (https://course-creator-service.6wpv8vensby5c.us-east-1.cs.amazonlightsail.com/)

The service will be visible in the Lightsail console:

Running the Web Interface

Start a connection to the Cloud Run deployed app:

https://course-creator-service.6wpv8vensby5c.us-east-1.cs.amazonlightsail.com/

Then connect to the app :

Then use online course generator:

Final Gemini CLI Code Review

As a final step — Gemini CLI was used for a full code review of the project:

✦ This multi-agent project is a well-engineered application of ADK 2.5 and the A2A protocol. The separation of specialized agents (Researcher,
  Judge, Content Builder) coordinated by a central Orchestrator demonstrates a mature microservice-oriented design.

  Key Strengths
   * Coordinated Orchestration: The use of SequentialAgent and LoopAgent creates a robust, iterative research-judge cycle.
   * Resilient State Flow: The strategy of passing data through event content and "recovering" it via before_agent_callback heuristics is a clever
     way to handle state across distributed, independent session stores.
   * Polished Streaming: The web app's SSE implementation, specifically the greedy overlap deduplication (merge_strings) and system message
     cleanup, ensures a high-quality user experience despite the inherent noise in multi-agent LLM streams.
   * Cloud-Native Readiness: Using Identity Tokens for authenticated service-to-service communication and middleware for dynamic A2A URL rewriting
     makes the system ready for production deployment on Cloud Run.

Summary

The Agent Development Kit (ADK) was used to build a multi-agent system with A2A support using the Gemini Flash LLM Model. This application was tested locally with Gemini CLI and then deployed to AWS Lightsail. Several key take-aways and lessons learned were summarized from debugging and testing the multi-agent system- including deep log reviews. Finally, Gemini CLI was used for a complete project code review.

Multi-Agent A2A with the Agent Development Kit(ADK), Amazon Fargate, and Gemini CLI

xbill — Thu, 16 Apr 2026 13:11:52 +0000

Aren’t There a Billion Python ADK Demos?

Yes there are.

Rock and roll ain’t noise pollution

So what is different about this lab compared to all the others out there?

The original Codelab- is here:

Building a Multi-Agent System | Google Codelabs

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.13

Amazon Fargate

Details are here:

Serverless Compute - AWS Fargate - AWS

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

Agent Skills

Gemini CLI can be customized to work with ADK agents. Both an Agent Development MCP server, and specific Agent skills are available.

More details are here:

Agent Development Kit (ADK)

To get the Agent Skills in Gemini CLI:

> /skills list
Available Agent Skills:

and the ADK documentation:

> /mcp list
Configured MCP servers:
🟢 adk-docs-mcp (from adk-docs-ext) - Ready (2 tools)
  Tools:
  - mcp_adk-docs-mcp_fetch_docs
  - mcp_adk-docs-mcp_list_doc_sources

Where do I start?

The strategy for starting multi agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, ADK Multi-Agent is built, debugged, and tested locally. Finally — the entire solution is deployed to AWS Fargate.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. All of the relevant code examples and documentation is available in GitHub.

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-aws
cd multi-fargate

Then run init2.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init2.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Finally install the packages and dependencies:

make install

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the researcher agent:

xbill@penguin:~/gemini-cli-aws/multi-fargate/agents$ adk run researcher
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260412_164250.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
{"asctime": "2026-04-12 16:42:50,986", "name": "root", "levelname": "INFO", "message": "Logging initialized for researcher", "filename": "logging_config.py", "lineno": 54, "service": "researcher", "log_level": "INFO"}
{"asctime": "2026-04-12 16:42:50,987", "name": "researcher.agent", "levelname": "INFO", "message": "Initialized researcher agent with model: gemini-2.5-flash", "filename": "agent.py", "lineno": 85}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.envs", "levelname": "INFO", "message": "Loaded .env file for researcher at /home/xbill/gemini-cli-aws/multi-eks/.env", "filename": "envs.py", "lineno": 83}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/multi-eks/agents", "filename": "local_storage.py", "lineno": 84}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using file artifact service at /home/xbill/gemini-cli-aws/multi-eks/agents/researcher/.adk/artifacts", "filename": "local_storage.py", "lineno": 110}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.service_factory", "levelname": "INFO", "message": "Using in-memory memory service", "filename": "service_factory.py", "lineno": 266}
{"asctime": "2026-04-12 16:42:50,993", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Creating local session service at /home/xbill/gemini-cli-aws/multi-eks/agents/researcher/.adk/session.db", "filename": "local_storage.py", "lineno": 60}
Running agent researcher, type exit to exit.
[user]:

Test The ADK Web Interface

This tests the ADK agent interactions with a browser:

xbill@penguin:~/gemini-cli-aws/multi-fargate/agents$ adk web --host 0.0.0.0
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-12 16:43:14,152 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-12 16:43:14,153 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/multi-eks/agents
2026-04-12 16:43:14,153 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/gemini-cli-aws/multi-eks/agents/.adk/artifacts
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/fast_api.py:198: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.local/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [32675]
INFO: Waiting for application startup.

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

INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:

Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:

adk web --host 0.0.0.0 --allow_origins 'regex:.*'

Multi Agent Design

The multi-agent deployment consists of 5 agents:

Researcher
Judge
Orchestrator
Content Builder
Course Builder

For a detailed analysis of the multi-agent architecture- this article provides the background information:

Multi-Agent A2A with the Agent Development Kit(ADK), Cloud Run, and Gemini CLI

Running/Testing/Debugging Locally

The main Makefile has been extended with extensive targets for managing the agents on the local development environment.

First check for local running agents:

✦ I will run the make local-status command to show you the current status of all local services.

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Checking the status of local processes. │
│ │
│ --- Local Process Status --- │
│ Service Port Status PID │
│ Frontend 5173 STOPPED - │
│ Backend 8000 STOPPED - │
│ Researcher 8001 STOPPED - │
│ Judge 8002 STOPPED - │
│ Builder 8003 STOPPED - │
│ Orchestrator 8004 STOPPED - │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ All local processes are currently STOPPED.

Then all the agents can be started together:

xbill@penguin:~/gemini-cli-aws/multi-fargate/agents$ make start
Stopping any existing agent and server processes...
Starting all agents in background...
Waiting for sub-agents to start...
All agents started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log
Starting App Backend in background...
Starting Frontend dev server in background...
All services started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log, backend.log, frontend.log
Frontend: http://localhost:5173
Backend: http://localhost:8000

make local-status again to verify.

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Verifying corrected local-status with updated pattern. │
│ │
│ --- Local Process Status --- │
│ Service Port Status PID │
│ Frontend 5173 STOPPED - │
│ Backend 8000 RUNNING 20045 │
│ Researcher 8001 RUNNING 19668 │
│ Judge 8002 RUNNING 19673 │
│ Builder 8003 RUNNING 19676 │
│ Orchestrator 8004 RUNNING 20037 │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The backend is now showing as RUNNING, but the frontend has reverted to STOPPED. It appears the Vite process is exiting after its initial start.
  I'll check the frontend.log again.

Then connect to the front end locally:

And the entire agent system will run in the local environment:

Local Logging / Debugging

Gemini CLI has full access to the local agent logs for debugging and troubleshooting:

> review the local logs for the multi-agent run
✦ I will check run_local.sh and the project structure to determine where logs are stored or how they are generated.

This will verify the local operation of the code:

✦ The local logs confirm a successful multi-agent run for the topic "the history of the internet." Here is a summary of the execution flow:

* Orchestrator (orchestrator.log): Successfully managed the pipeline. It captured the topic, coordinated the Research-Judge loop, and escalated to
     content generation after the first iteration.
   * Researcher (researcher.log): Gathered approximately 9.2KB of research data using the google_search tool. It completed its task with a 200 OK
     response.
   * Judge (judge.log): Evaluated the findings and gave a "pass" status. The judge noted that the research was "comprehensive, accurate, and
     well-structured," making it an "excellent foundation for educational content."
   * Content Builder (content_builder.log): Successfully transformed the validated research into a structured Markdown course module and finished
     execution.
   * Backend & Frontend (backend.log, frontend.log): The FastAPI backend (port 8000) and Vite frontend (port 5173) are running and communicating with
     the orchestrator as expected.

Notable Observation:
   * A minor warning appeared in researcher.log: Researcher callback: 'response' not found or has no parts. However, this did not impact the
     successful completion of the research or the overall pipeline.

All services are currently active and logged at the DEBUG level as specified in run_local.sh.

Deploying to Amazon Fargate

The project level Makefile has targets for managing the Agent deployment to serverless endpoints. A utility script checks the deployment status:

make status

You can submit the build for GKE deployment:

✦ The application has been successfully deployed to AWS Fargate. All microservice images (Researcher, Judge, Content Builder, Orchestrator, and
  App) have been built and pushed to Amazon ECR, and the ECS service has been updated.

Once the containers are deployed- you can then get the endpoint:

make endpoint, to retrieve the public IP of your Fargate service.

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Retrieving the public endpoint for the Fargate service. │
│ │
│ Fargate Endpoint: http://54.221.168.167:8080 │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The public endpoint for your Fargate service is: http://54.221.168.167:8080

  You can use this URL to access your application or run an end-to-end test against it with make e2e-test-fargate.

The status can then be checked:

> make status
✦ I will check the status of the AWS Fargate services.

╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell Checking the status of the AWS Fargate services. │
│ │
│ ----------------------------------------------------------------------------------------------------------------------------------------- │
│ | DescribeServices | │
│ +---------+----------------------+----------+---------+---------------------------------------------------------------------------------+ │
│ | Desired | Name | Running | Status | TaskDef | │
│ +---------+----------------------+----------+---------+---------------------------------------------------------------------------------+ │
│ | 1 | adk-fargate-service | 1 | ACTIVE | arn:aws:ecs:us-east-1:106059658660:task-definition/adk-course-creator-task:2 | │
│ +---------+----------------------+----------+---------+---------------------------------------------------------------------------------+ │
│ │
╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The AWS Fargate service adk-fargate-service is currently ACTIVE with 1 running task.

The service will be visible in the AWS console:

And the entire system can be tested:


✦ The end-to-end test against the deployed AWS Fargate endpoint was successful! The system correctly orchestrated the microservices to create a
  structured "History of the Internet" course and streamed the results back via Server-Sent Events (SSE).

  Deployment & Verification Summary:
   - Status: The adk-fargate-service is ACTIVE and running.
   - Endpoint: http://54.221.168.167:8080
   - E2E Test: Completed successfully against the remote Fargate task.
   - Local Monitoring: make local-status is available and correctly reports local process states using robust pattern matching.

  Your multi-agent AI Course Creator is now fully deployed and operational on AWS Fargate.

Running the Web Interface

Start a connection to the Cloud Run deployed app:

Then connect to the app :

Then use online course generator:

Review Fargate Setup

Gemini CLI was used to review the Fargate Setup:

  ✓ ReadFile setup-fargate.sh

✦ All agents in this project are configured to run within a single AWS Fargate task. Therefore, they share a common pool of resources:

   * Total Task CPU: 1024 (1 vCPU)
   * Total Task Memory: 2048 (2 GB RAM)

  Components Sharing these Resources:
  The following five containers share the 1 vCPU and 2 GB RAM:
   1. app: The FastAPI backend and web interface.
   2. orchestrator: Manages the agent workflow.
   3. researcher: Performs topic research using Google Search.
   4. judge: Evaluates research findings.
   5. content-builder: Generates the final course modules.

  This configuration is defined in the setup-fargate.sh script, which registers the ECS task definition with these specific resource allocations.

and a deep dive into the deployment pattern:

> how is this app deployed on Fargate?
✦ I will examine the deploy-fargate.sh script and the root Makefile to understand the complete build and push process for the Fargate deployment.

  ✓ ReadFile deploy-fargate.sh

✦ The deployment of the AI Course Creator to AWS Fargate is a multi-step process managed by two primary scripts: setup-fargate.sh and
  deploy-fargate.sh.

  1. Infrastructure Provisioning (setup-fargate.sh)
  This script sets up the foundational AWS resources required to run the application:
   * ECS Cluster: Creates a cluster named adk-fargate-cluster.
   * IAM Roles: Provisions the ecsTaskExecutionRole-adk with the necessary permissions to pull images from ECR and send logs to CloudWatch.
   * Security Groups: Configures an adk-fargate-sg that allows inbound traffic on port 8080 (the web app port).
   * Task Definition: Defines how the 5 microservices (app, orchestrator, researcher, judge, content-builder) are run. It specifies a single
     Fargate task where all 5 containers share the same network stack (awsvpc) and resource pool (1 vCPU, 2 GB RAM). This allows them to
     communicate with each other using localhost.
   * ECS Service: Creates a Fargate service that maintains one running instance of the task definition.

  2. Build and Push Process (deploy-fargate.sh)
  This script handles the continuous delivery of the application code:
   * ECR Repositories: Ensures that Amazon Elastic Container Registry (ECR) repositories exist for each of the 5 microservices.
   * Authentication: Logs in the local Docker daemon to the ECR registry using the AWS CLI.
   * Container Builds: Iteratively builds Docker images for each service:
       * researcher
       * judge
       * content-builder
       * orchestrator
       * app (FastAPI backend + Frontend)
   * Image Push: Tags the built images and pushes them to their respective ECR repositories.
   * Deployment Trigger: Once the images are pushed, the ECS service can be updated (e.g., via aws ecs update-service --force-new-deployment) to
     pull the latest versions and restart the tasks.

  Summary of Deployment Flow
   1. Run setup-fargate.sh (once) to create the AWS infrastructure.
   2. Run deploy-fargate.sh to build and upload the container images.
   3. Monitor Status: Use make status-fargate (which likely wraps aws ecs describe-tasks) to verify the containers have successfully reached the
      RUNNING state.

  This architecture leverages Fargate's serverless nature to run a complex, multi-agent system without managing the underlying EC2 instances,
  while the single-task approach simplifies service discovery and reduces cross-service latency.

Final Gemini CLI Code Review

As a final step — Gemini CLI was used for a full code review of the project:

✦ I've analyzed the project's architecture, security, and agent logic. I'll now provide a code review of the AI Course Creator project, focusing
  on its distributed multi-agent design using ADK and A2A on AWS Fargate.

  1. Architecture & Orchestration
   * A2A Workflow: The system uses a clean SequentialAgent pipeline (course_creation_pipeline) in the orchestrator to chain specialized agents.
   * State Management: The StateCapturer pattern is an effective way to bridge the context between independent A2A services. It intercepts LLM
     responses and injects them into the session_state, which subsequent agents then consume.
   * Loop Logic: Using LoopAgent with a max_iterations=2 limit for the Research-Judge cycle is a best practice to prevent infinite loops and
     control costs.
   * Escalation Control: The EscalationChecker correctly uses structured Pydantic output (JudgeFeedback) to decide when to break the research
     loop.

  2. ADK Best Practices
   * Model Selection: The project correctly prioritizes gemini-2.5-flash for efficiency and reasoning, with gemini-2.5-pro as an alternative for
     complex tasks.
   * Tool Usage: The google_search tool in the researcher agent is well-integrated.
   * Structured Outputs: Using Pydantic schemas for the judge agent ensures that the orchestration logic is robust and type-safe.

  3. Security & Authentication
   * Service-to-Service Auth: The authenticated_httpx.py utility is a standout feature. It handles Google OIDC tokens for secure communication
     between agents, even when deployed on non-Google infrastructure like AWS Fargate.
   * Environment Variables: Sensitive information like GOOGLE_API_KEY is passed via environment variables, following standard security practices.
   * Dynamic A2A Cards: The a2a_utils.py middleware solves the challenge of discovering service URLs in dynamic container environments by
     rewriting the Agent Card's url based on the x-forwarded-host header.

  4. Infrastructure & Deployment
   * Resource Efficiency: Running all 5 containers in a single Fargate task (1 vCPU, 2 GB RAM) is cost-effective for a prototype but may lead to
     resource contention if multiple courses are generated simultaneously.
   * Docker Strategy: Using a standardized shared/adk_app.py entry point across all agents ensures consistent logging, A2A registration, and
     middleware application.

  Summary
  The project demonstrates a high level of technical maturity in distributed agent orchestration. It effectively adapts Google ADK patterns for a
  cross-cloud environment (AWS Fargate) while maintaining strong security and clean architectural boundaries.

Summary

Building Multimodal Real Time Agent with ADK, Azure AKS, Gemini CLI, and Gemini Flash Live 3.1

xbill — Tue, 14 Apr 2026 21:55:29 +0000

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build cross cloud apps with the Python programming language deployed to the Azure app service.

Aren’t There a Billion Python Agent Demos?

Yes there are.

Python has traditionally been the main coding language for ML and AI tools. The goal of this article is to provide a minimal viable basic working MCP stdio server that can be run locally without any unneeded extra code or extensions.

What Is Python?

Python is an interpreted language that allows for rapid development and testing and has deep libraries for working with ML and AI:

Welcome to Python.org

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

admin@ip-172-31-70-211:~/gemini-cli-azure$ python --version
Python 3.13.12

Azure Kubernates Service

Azure Kubernetes Service (AKS) is a fully managed, serverless Kubernetes service on Microsoft Azure that simplifies deploying, scaling, and managing containerized applications. It handles critical tasks like health monitoring, maintenance, and automated upgrades, reducing operational complexity. AKS is used for microservices, DevOps, and cloud-native app development.

More details are available here:

https://azure.microsoft.com/en-us/products/kubernetes-service

Isn’t that Overkill? A whole Cluster Just for some Agents?!

An entire cluster is a large deployment for just a basic ADK server. The goal was to validate that ADK servers can be deployed — and that opens the door for more complex deployments that can take advantage of the full services in the cluster.

Why would I want Gemini CLI with Azure? Isn’t that a Google Thing?

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

gemini

admin@ip-172-31-70-211:~/gemini-cli-azure$ gemini

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade

? for shortcuts 
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 shift+tab to accept edits 3 GEMINI.md files | 1 MCP server
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 > Type your message or @path/to/file
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 ~/.../gemini-cli-azure (main*) no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Docker Version Management

The Azure CLI tools need current version of Docker. If your environment does not provide a recent docker tool- the Docker Version Manager can be used to downlaod the latest supported Docker:

Install

Azure CLI

The Azure CLI provides a command line tool to directly access Azure services from your current environment. Full details on the CLI are available here:

Azure Command-Line Interface (CLI) documentation

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

This seems like a lot of Configuration!

Getting the key tools in place is the first step to working across Cloud environments. For a deeper dive- a project with a similar setup can be found here:

MCP Development with Python, and the Azure App Service

Where do I start?

The strategy for starting multimodal real time cross cloud agent development is a incremental step by step approach.

The agents in the demo are based on the original code lab:

Way Back Home - Building an ADK Bi-Directional Streaming Agent | Google Codelabs

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, a minimal ADK Agent is built with the visual builder. Next — the entire solution is deployed to Azure AKS.

Setup the Basic Environment

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-azure
cd gemini31-aks

Then run init.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with Agent1:


xbill@penguin:~/gemini-cli-azure/gemini31-aks/backend/app$ adk run biometric_agent/
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260412_171150.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/cli.py:204: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.local/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
Running agent biometric_agent, type exit to exit.

[biometric_agent]: Scanner Online.




  
  
  Deploying to Azure Kubernates Service


The first step is to refresh the Azure credentials in the current build environment:



xbill@penguin:~/gemini-cli-azure/gemini31-aks$ az login






Run the deploy version on the local system:




xbill@penguin:~/gemini-cli-azure/gemini31-aks$ make deploy
./deploy.sh
Ensuring Resource Group exists...
{
  "id": "/subscriptions/3db3ce66-50b6-4d11-91ef-5950cf4039ed/resourceGroups/aca",
  "location": "canadaeast",
  "managedBy": null,
  "name": "aca",
  "properties": {
    "provisioningState": "Succeeded"
  },
  "tags": null,
  "type": "Microsoft.Resources/resourceGroups"
}
Ensuring ACR exists...
Creating ACR biometricacrpenguinv3... 0.0s 0.0s






You can validate the final result by checking the messages:




✦ The AKS deployment is healthy and HTTPS-enabled. 

  Status Summary:
   - App Pods: Running (1/1 ready)
   - Ingress: biometric-scout-ingress is active for biometric-scout-penguinv3.eastus.cloudapp.azure.com.
   - Ingress Controller: Running with External IP 20.81.113.127.
   - Endpoint: https://biometric-scout-penguinv3.eastus.cloudapp.azure.com (https://biometric-scout-penguinv3.eastus.cloudapp.azure.com)

  Note: Since we are using a self-signed certificate, you will need to bypass the "Your connection is not private" warning in your browser to access
  the site.

make endpoint

✦ The endpoint command has been updated to reflect the new HTTPS URL:
  https://biometric-scout-penguinv3.eastus.cloudapp.azure.com (https://biometric-scout-penguinv3.eastus.cloudapp.azure.com)






The service will be visible in the Azure console:




  
  
  Running the Web Interface


Start a connection to the deployed app:




https://biometric-scout-penguinv3.eastus.cloudapp.azure.com








Then use the Live model to process audio and video:



Finally — complete the sequence:




  
  
  Summary


The Agent Development Kit was used to enable a multi-modal agent using the Gemini Live Model. This Agent was tested locally with the CLI and then deployed to Azure Kubernates Service (AKS). This approach validates that cross cloud tools can be used — even with more complex agents.

Building with the Google Cloud Run MCP Server for Multi-Agent A2A Deployment

xbill — Tue, 14 Apr 2026 16:35:08 +0000

Aren’t There a Billion Python Agent Demos?

Yes there are.

So is this the real Slim Shady?

So what is different about this lab compared to all the others out there?

The original Codelab- is here:

Building a Multi-Agent System | Google Codelabs

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.13

Google Cloud Run

Google Cloud Run is a fully managed, server less compute platform that enables you to run containerized applications and services without managing infrastructure. It automatically scales up or down — even to zero — based on traffic, allowing you to pay only for resources used, billed by the 100-millisecond.

More info is available here:

Cloud Run

Official Google MCP Servers

Google provides MCP servers for all the main components of GCP. The full details are here:

Google Cloud MCP servers overview | Google Cloud Documentation

More info is here:

Announcing official MCP support for Google services | Google Cloud Blog

Note this MCP server exposes MCP tools for the using underlying Cloud Run Services managed by Google. It is *not* just using Cloud Run to deploy your own MCP services.

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

Agent Skills

Gemini CLI can be customized to work with ADK agents. Both an Agent Development MCP server, and specific Agent skills are available.

More details are here:

Agent Development Kit (ADK)

To get the Agent Skills in Gemini CLI:

> /skills list

and the ADK documentation:

> /mcp list
Configured MCP servers:
🟢 adk-docs-mcp (from adk-docs-ext) - Ready (2 tools)
  Tools:
  - mcp_adk-docs-mcp_fetch_docs
  - mcp_adk-docs-mcp_list_doc_sources

Where do I start?

The strategy for starting multi agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, ADK Multi-Agent is built, debugged, and tested locally. Finally — the entire solution is deployed to Google Cloud Run.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. All of the relevant code examples and documentation is available in GitHub.

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/multi-agent

Then run init2.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init2.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Finally install the packages and dependencies:

make install

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the researcher agent:

xbill@penguin:~/multi-agent/agents$ adk run researcher
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260410_174725.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
{"asctime": "2026-04-10 17:47:25,496", "name": "root", "levelname": "INFO", "message": "Logging initialized for researcher", "filename": "logging_config.py", "lineno": 54, "service": "researcher", "log_level": "INFO"}
{"asctime": "2026-04-10 17:47:25,496", "name": "researcher.agent", "levelname": "INFO", "message": "Initialized researcher agent with model: gemini-2.5-flash", "filename": "agent.py", "lineno": 85}
{"asctime": "2026-04-10 17:47:25,497", "name": "google_adk.google.adk.cli.utils.envs", "levelname": "INFO", "message": "Loaded .env file for researcher at /home/xbill/multi-agent/agents/researcher/.env", "filename": "envs.py", "lineno": 83}
{"asctime": "2026-04-10 17:47:25,497", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using per-agent session storage rooted at /home/xbill/multi-agent/agents", "filename": "local_storage.py", "lineno": 84}
{"asctime": "2026-04-10 17:47:25,497", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using file artifact service at /home/xbill/multi-agent/agents/researcher/.adk/artifacts", "filename": "local_storage.py", "lineno": 110}
{"asctime": "2026-04-10 17:47:25,498", "name": "google_adk.google.adk.cli.utils.service_factory", "levelname": "INFO", "message": "Using in-memory memory service", "filename": "service_factory.py", "lineno": 266}
{"asctime": "2026-04-10 17:47:25,501", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Creating local session service at /home/xbill/multi-agent/agents/researcher/.adk/session.db", "filename": "local_storage.py", "lineno": 60}
Running agent researcher, type exit to exit.
[user]:

Test The ADK Web Interface

This tests the ADK agent interactions with a browser:

xbill@penguin:~/multi-agent/agents$ adk web --host 0.0.0.0
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-10 17:49:11,850 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-10 17:49:11,850 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/multi-agent/agents
2026-04-10 17:49:11,850 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/multi-agent/agents/.adk/artifacts
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/cli/fast_api.py:198: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.pyenv/versions/3.13.13/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [16063]
INFO: Waiting for application startup.

Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:

Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:

adk web --host 0.0.0.0 --allow_origins 'regex:.*'

Configure Cloud Run MCP Server

Basic setup instructions are available here:

Authenticate to Google and Google Cloud MCP servers | Google Cloud Documentation

A sample Cloud Run MCP server script is here:

source cloudrun-mcp.sh

This will enable the Cloud Run MCP server:

--- Setting up Cloud Run MCP for project: aisprint-491218 ---
Enabling Services...
Operation "operations/acat.p2-289270257791-6c5ec831-6f9a-4d44-b221-9ad9f3734f5e" finished successfully.

Testing the MCP server:

gemini
/mcp list

🟢 mcp_cloudrun - Ready (5 tools, 1 prompt)
  Tools:
  - mcp_cloudrun_deploy_service_from_archive
  - mcp_cloudrun_deploy_service_from_file_contents
  - mcp_cloudrun_deploy_service_from_image
  - mcp_cloudrun_get_service
  - mcp_cloudrun_list_services
  Prompts:
  - deploy

Multi Agent Design

The multi-agent deployment consists of 5 agents:

Researcher
Judge
Orchestrator
Content Builder
Course Builder

This article provides a breakdown of the multi-agent architecture:

Multi-Agent A2A with the Agent Development Kit(ADK), Cloud Run, and Gemini CLI

Running/Testing/Debugging Locally

The main Makefile has been extended with extensive targets for managing the agents on the local development environment.

The key targets include:

xbill@penguin:~/multi-agent$ make help
Available commands:
  install - Install all dependencies for root, agents, and app
  start - Start all services locally (alias for start-local)
  stop - Stop all local services (alias for stop-local)
  run - Start all services locally (alias for start-local)
  local - Show local service URLs
  start-local - Start all local services in background
  stop-local - Stop all local processes
  test - Run all tests (pytest)
  test-researcher - Test the Researcher agent directly
  test-judge - Test the Judge agent directly
  test-orchestrator - Test the Orchestrator logic
  lint - Run linting checks (ruff)
  deploy - Deploy all services to Cloud Run
  destroy - Delete all Cloud Run services
  clean - Remove caches and logs

First check for local running agents:

xbill@penguin:~/multi-agent$ make status
Checking status of locally running agents and servers...
--- Network Status ---
No services listening on expected ports (8000-8004, 5173).
--- Process Status ---
No matching processes found.

Then all the agents can be started together:

xbill@penguin:~/multi-agent$ make start
Stopping any existing agent and server processes...
Starting all agents in background...
Waiting for sub-agents to start...
All agents started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log
Starting App Backend in background...
Starting Frontend dev server in background...
All services started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log, backend.log, frontend.log
Frontend: http://localhost:5173
Backend: http://localhost:8000

make status

--- Local Service URLs ---
Frontend: [http://localhost:5173](http://localhost:5173)
Backend: [http://localhost:8000](http://localhost:8000) (main app)
Agents:
  Researcher: [http://localhost:8001](http://localhost:8001)
  Judge: [http://localhost:8002](http://localhost:8002)
  Content Builder: [http://localhost:8003](http://localhost:8003)
  Orchestrator: [http://localhost:8004](http://localhost:8004)

The entire project can be linted and tested as unit:

> make lint
✦ I will run the linting checks again as requested.
✦ All 32 tests passed successfully.

Then connect to the front end locally:

And the entire agent system will run in the local environment:

Local Logging / Debugging

Gemini CLI has full access to the local agent logs for debugging and troubleshooting:

✦ The local logs confirm a successful multi-agent run for the topic "the history of the internet." Here is a summary of the execution flow:

   * Orchestrator (orchestrator.log): Successfully managed the pipeline. It captured the topic, coordinated the Research-Judge loop, and escalated to
     content generation after the first iteration.
   * Researcher (researcher.log): Gathered approximately 9.2KB of research data using the google_search tool. It completed its task with a 200 OK
     response.
   * Judge (judge.log): Evaluated the findings and gave a "pass" status. The judge noted that the research was "comprehensive, accurate, and
     well-structured," making it an "excellent foundation for educational content."
   * Content Builder (content_builder.log): Successfully transformed the validated research into a structured Markdown course module and finished
     execution.
   * Backend & Frontend (backend.log, frontend.log): The FastAPI backend (port 8000) and Vite frontend (port 5173) are running and communicating with
     the orchestrator as expected.

  Notable Observation:
   * A minor warning appeared in researcher.log: Researcher callback: 'response' not found or has no parts. However, this did not impact the
     successful completion of the research or the overall pipeline.

  All services are currently active and logged at the DEBUG level as specified in run_local.sh.

Deploying to Google Cloud Run

The project level Makefile has targets for managing the Agent deployment to serverless endpoints:

xbill@penguin:~/multi-agent$ make help
Available commands:
  install - Install all dependencies for root, agents, and app
  start - Start all services locally (alias for start-local)
  stop - Stop all local services (alias for stop-local)
  run - Start all services locally (alias for start-local)
  local - Show local service URLs
  start-local - Start all local services in background
  stop-local - Stop all local processes
  test - Run all tests (pytest)
  test-researcher - Test the Researcher agent directly
  test-judge - Test the Judge agent directly
  test-orchestrator - Test the Orchestrator logic
  lint - Run linting checks (ruff)
  deploy - Deploy all services to Cloud Run
  destroy - Delete all Cloud Run services
  clean - Remove caches and logs

A utility script check the deployment to Cloud Run:

make status

--- Cloud Deployment Status ---
Checking deployment status for AI Course Creator services...
   SERVICE REGION URL LAST DEPLOYED BY LAST DEPLOYED AT
✔ content-builder us-central1 [https://content-builder-1056842563084.us-central1.run.app](https://content-builder-1056842563084.us-central1.run.app) xbill@glitnir.com 2026-04-10T20:18:40.053541Z
✔ course-creator us-central1 [https://course-creator-1056842563084.us-central1.run.app](https://course-creator-1056842563084.us-central1.run.app) xbill@glitnir.com 2026-04-10T20:19:39.704879Z
✔ judge us-central1 [https://judge-1056842563084.us-central1.run.app](https://judge-1056842563084.us-central1.run.app) xbill@glitnir.com 2026-04-10T20:18:40.417046Z
✔ orchestrator us-central1 [https://orchestrator-1056842563084.us-central1.run.app](https://orchestrator-1056842563084.us-central1.run.app) xbill@glitnir.com 2026-04-10T20:19:01.850264Z
✔ researcher us-central1 [https://researcher-1056842563084.us-central1.run.app](https://researcher-1056842563084.us-central1.run.app) xbill@glitnir.com 2026-04-10T20:18:38.584952Z 0.0s 0.0s

You can submit the build for cloud deployment:

xbill@penguin:~/multi-agent$ make deploy
Building all images using Cloud Build for project comglitn...
gcloud builds submit --project "comglitn" --config cloudbuild.yaml .

Once the containers are deployed- you can then get the endpoint:

./deploy.sh orchestrator
Using project comglitn.
Using compute region us-central1.
Deploying orchestrator...
Deploying container to Cloud Run service [orchestrator] in project [comglitn] region [us-central1]
✓ Deploying... Done.                                                                                                                             
  ✓ Creating Revision...                                                                                                                         
  ✓ Routing traffic...                                                                                                                           
  ✓ Setting IAM Policy...                                                                                                                        
Done.                                                                                                                                            
Service [orchestrator] revision [orchestrator-00002-9jg] has been deployed and is serving 100 percent of traffic.
Service URL: https://orchestrator-1056842563084.us-central1.run.app
make[1]: Leaving directory '/home/xbill/multi-agent'
Deploying course-creator app...
make[1]: Entering directory '/home/xbill/multi-agent'
./deploy.sh course-creator
Using project comglitn.
Using compute region us-central1.
Deploying course-creator...
Deploying container to Cloud Run service [course-creator] in project [comglitn] region [us-central1]
✓ Deploying... Done.                                                                                                                             
  ✓ Creating Revision...                                                                                                                         
  ✓ Routing traffic...                                                                                                                           
  ✓ Setting IAM Policy...                                                                                                                        
Done.                                                                                                                                            
Service [course-creator] revision [course-creator-00002-f74] has been deployed and is serving 100 percent of traffic.
Service URL: https://course-creator-1056842563084.us-central1.run.app
make[1]: Leaving directory '/home/xbill/multi-agent'


xbill@penguin:~/multi-agent$ make endpoint
Service URLs:
NAME URL
content-builder [https://content-builder-fgasxpwzoq-uc.a.run.app](https://content-builder-fgasxpwzoq-uc.a.run.app)
course-creator [https://course-creator-fgasxpwzoq-uc.a.run.app](https://course-creator-fgasxpwzoq-uc.a.run.app)
judge [https://judge-fgasxpwzoq-uc.a.run.app](https://judge-fgasxpwzoq-uc.a.run.app)
orchestrator [https://orchestrator-fgasxpwzoq-uc.a.run.app](https://orchestrator-fgasxpwzoq-uc.a.run.app)
researcher [https://researcher-fgasxpwzoq-uc.a.run.app](https://researcher-fgasxpwzoq-uc.a.run.app)

The service will be visible in the Cloud Run console:

Running the Web Interface

Start a connection to the Cloud Run deployed app:

https://course-creator-fgasxpwzoq-uc.a.run.app

Then connect to the app :

Then use online course generator:

Google Cloud Run MCP Server with Gemini CLI

Once the entire agent system has been deployed. The Cloud Run MCP server can be used for visibility of the application directly from Gemini CLI:

🟢 mcp_cloudrun - Ready (5 tools, 1 prompt)

  Tools:
  - mcp_cloudrun_deploy_service_from_archive
  - mcp_cloudrun_deploy_service_from_file_contents
  - mcp_cloudrun_deploy_service_from_image
  - mcp_cloudrun_get_service
  - mcp_cloudrun_list_services
  Prompts:
  - deploy

The status can be checked:

✦ Using the mcp_cloudrun_list_services tool for project aisprint-491218 in us-central1, I've confirmed the following services are currently deployed:

   - course-creator: https://course-creator-wgcq55zbfq-uc.a.run.app
   - orchestrator: https://orchestrator-wgcq55zbfq-uc.a.run.app
   - judge: https://judge-wgcq55zbfq-uc.a.run.app
   - researcher: https://researcher-wgcq55zbfq-uc.a.run.app
   - content-builder: https://content-builder-wgcq55zbfq-uc.a.run.app

and in-depth service status:

> use the MCP call mcp_cloudrun_get_service course-creator
╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ Action Required │
│ │
│ ? get_service (mcp_cloudrun MCP Server) {"project":"aisprint-491218","region":"us-central1","name":"course-creator"} │
│ │
│ MCP Server: mcp_cloudrun │
│ Tool: get_service │
│ │
│ MCP Tool Details: │
│ (press Ctrl+O to expand MCP tool details) │
│ Allow execution of MCP tool "get_service" from server "mcp_cloudrun"? │
│ │
│ 1. Allow once │
│ 2. Allow tool for this session │
│ 3. Allow all server tools for this session │
│ ● 4. Allow tool for all future sessions │
│ 5. No, suggest changes (esc) │
│ │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The details for the course-creator service in project aisprint-491218 (region us-central1) are as follows:

   - URI: https://course-creator-wgcq55zbfq-uc.a.run.app
   - Status: Ready (Succeeded)
   - Image: gcr.io/aisprint-491218/course-creator
   - Environment Variables:
     - AGENT_SERVER_URL: https://orchestrator-wgcq55zbfq-uc.a.run.app
     - AGENT_NAME: orchestrator
     - GOOGLE_CLOUD_PROJECT: aisprint-491218
   - Port: 8080 (http1)
   - Last Updated: 2026-04-12T17:03:11.304251Z

Final Gemini CLI Code Review

As a final step — Gemini CLI was used for a full code review of the project:

✦ This multi-agent project is a well-engineered application of ADK 2.5 and the A2A protocol. The separation of specialized agents (Researcher,
  Judge, Content Builder) coordinated by a central Orchestrator demonstrates a mature microservice-oriented design.

Key Strengths
   * Coordinated Orchestration: The use of SequentialAgent and LoopAgent creates a robust, iterative research-judge cycle.
   * Resilient State Flow: The strategy of passing data through event content and "recovering" it via before_agent_callback heuristics is a clever
     way to handle state across distributed, independent session stores.
   * Polished Streaming: The web app's SSE implementation, specifically the greedy overlap deduplication (merge_strings) and system message
     cleanup, ensures a high-quality user experience despite the inherent noise in multi-agent LLM streams.
   * Cloud-Native Readiness: Using Identity Tokens for authenticated service-to-service communication and middleware for dynamic A2A URL rewriting
     makes the system ready for production deployment on Cloud Run.

Summary

The Agent Development Kit (ADK) was used to build a multi-agent system with A2A support using the Gemini Flash LLM Model. This application was tested locally with Gemini CLI and then deployed to Google Cloud Run. The Official Google Cloud MCP server was used to review the deployment directly from Gemini CLI. Finally, Gemini CLI was used for a complete project code review.

Multi-Agent A2A with the Agent Development Kit(ADK), Azure AKS, and Gemini CLI

xbill — Mon, 13 Apr 2026 20:09:45 +0000

Aren’t There a Billion Python ADK Demos?

Yes there are.

Hold the Pickles, Hold the Lettuce!

So what is different about this lab compared to all the others out there?

The original Codelab- is here:

Building a Multi-Agent System | Google Codelabs

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.13

Azure Kubernates Service

More details are available here:

https://azure.microsoft.com/en-us/products/kubernetes-service

Isn’t that Overkill? A whole Cluster Just for some Agents?!

Why would I want Gemini CLI with Azure? Isn’t that a Google Thing?

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

Agent Skills

Gemini CLI can be customized to work with ADK agents. Both an Agent Development MCP server, and specific Agent skills are available.

More details are here:

Agent Development Kit (ADK)

To get the Agent Skills in Gemini CLI:

> /skills list
Available Agent Skills:

and the ADK documentation:

> /mcp list
Configured MCP servers:
🟢 adk-docs-mcp (from adk-docs-ext) - Ready (2 tools)
  Tools:
  - mcp_adk-docs-mcp_fetch_docs
  - mcp_adk-docs-mcp_list_doc_sources

Where do I start?

The strategy for starting multi agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, ADK Multi-Agent is built, debugged, and tested locally. Finally — the entire solution is deployed to Google Cloud Run.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. All of the relevant code examples and documentation is available in GitHub.

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-azure

cd multi-aks

Then run init2.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init2.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Finally install the packages and dependencies:

make install

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the researcher agent:

xbill@penguin:~/gemini-cli-azure/multi-aks/agents$ adk run researcher
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260412_151927.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
{"asctime": "2026-04-12 15:19:27,144", "name": "root", "levelname": "INFO", "message": "Logging initialized for researcher", "filename": "logging_config.py", "lineno": 54, "service": "researcher", "log_level": "INFO"}
{"asctime": "2026-04-12 15:19:27,145", "name": "researcher.agent", "levelname": "INFO", "message": "Initialized researcher agent with model: gemini-2.5-flash", "filename": "agent.py", "lineno": 85}
{"asctime": "2026-04-12 15:19:27,146", "name": "google_adk.google.adk.cli.utils.envs", "levelname": "INFO", "message": "Loaded .env file for researcher at /home/xbill/gemini-cli-azure/multi-aks/.env", "filename": "envs.py", "lineno": 83}
{"asctime": "2026-04-12 15:19:27,146", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using per-agent session storage rooted at /home/xbill/gemini-cli-azure/multi-aks/agents", "filename": "local_storage.py", "lineno": 84}
{"asctime": "2026-04-12 15:19:27,146", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using file artifact service at /home/xbill/gemini-cli-azure/multi-aks/agents/researcher/.adk/artifacts", "filename": "local_storage.py", "lineno": 110}
{"asctime": "2026-04-12 15:19:27,146", "name": "google_adk.google.adk.cli.utils.service_factory", "levelname": "INFO", "message": "Using in-memory memory service", "filename": "service_factory.py", "lineno": 266}
{"asctime": "2026-04-12 15:19:27,152", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Creating local session service at /home/xbill/gemini-cli-azure/multi-aks/agents/researcher/.adk/session.db", "filename": "local_storage.py", "lineno": 60}
Running agent researcher, type exit to exit.
[user]

Test The ADK Web Interface

This tests the ADK agent interactions with a browser:

xbill@penguin:~/gemini-cli-azure/multi-aks$ adk web --host 0.0.0.0
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-12 15:20:23,207 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-12 15:20:23,208 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/gemini-cli-azure/multi-aks
2026-04-12 15:20:23,208 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/gemini-cli-azure/multi-aks/.adk/artifacts
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/fast_api.py:198: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.local/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [13962]
INFO: Waiting for application startup.

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

INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:

Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:

adk web --host 0.0.0.0 --allow_origins 'regex:.*'

Multi Agent Design

The multi-agent deployment consists of 5 agents:

Researcher
Judge
Orchestrator
Content Builder
Course Builder

For a detailed analysis of the multi-agent architecture- this article provides the background information:

Multi-Agent A2A with the Agent Development Kit(ADK), Cloud Run, and Gemini CLI

Running/Testing/Debugging Locally

The main Makefile has been extended with extensive targets for managing the agents on the local development environment.

The key targets include:

xbill@penguin:~/multi-agent$ make help
Available commands:
  install - Install all dependencies for root, agents, and app
  start - Start all services locally (alias for start-local)
  stop - Stop all local services (alias for stop-local)
  run - Start all services locally (alias for start-local)
  local - Show local service URLs
  start-local - Start all local services in background
  stop-local - Stop all local processes
  test - Run all tests (pytest)
  test-researcher - Test the Researcher agent directly
  test-judge - Test the Judge agent directly
  test-orchestrator - Test the Orchestrator logic
  lint - Run linting checks (ruff)
  deploy - Deploy all services to Cloud Run
  destroy - Delete all Cloud Run services
  clean - Remove caches and logs

First check for local running agents:

xbill@penguin:~/multi-agent$ make status
Checking status of locally running agents and servers...
--- Network Status ---
No services listening on expected ports (8000-8004, 5173).
--- Process Status ---
No matching processes found.

Then all the agents can be started together:

xbill@penguin:~/multi-agent$ make start
Stopping any existing agent and server processes...
Starting all agents in background...
Waiting for sub-agents to start...
All agents started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log
Starting App Backend in background...
Starting Frontend dev server in background...
All services started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log, backend.log, frontend.log
Frontend: http://localhost:5173
Backend: http://localhost:8000

make status

--- Local Service URLs ---
Frontend: [http://localhost:5173](http://localhost:5173)
Backend: [http://localhost:8000](http://localhost:8000) (main app)
Agents:
  Researcher: [http://localhost:8001](http://localhost:8001)
  Judge: [http://localhost:8002](http://localhost:8002)
  Content Builder: [http://localhost:8003](http://localhost:8003)
  Orchestrator: [http://localhost:8004](http://localhost:8004)

Then connect to the front end locally:

And the entire agent system will run in the local environment:

Local Logging / Debugging

Gemini CLI has full access to the local agent logs for debugging and troubleshooting:

 > review the local logs for the multi-agent run
✦ I will check run_local.sh and the project structure to determine where logs are stored or how they are generated.

This will verify the local operation of the code:

✦ The local logs confirm a successful multi-agent run for the topic "the history of the internet." Here is a summary of the execution flow:

   * Orchestrator (orchestrator.log): Successfully managed the pipeline. It captured the topic, coordinated the Research-Judge loop, and escalated to
     content generation after the first iteration.
   * Researcher (researcher.log): Gathered approximately 9.2KB of research data using the google_search tool. It completed its task with a 200 OK
     response.
   * Judge (judge.log): Evaluated the findings and gave a "pass" status. The judge noted that the research was "comprehensive, accurate, and
     well-structured," making it an "excellent foundation for educational content."
   * Content Builder (content_builder.log): Successfully transformed the validated research into a structured Markdown course module and finished
     execution.
   * Backend & Frontend (backend.log, frontend.log): The FastAPI backend (port 8000) and Vite frontend (port 5173) are running and communicating with
     the orchestrator as expected.

  Notable Observation:
   * A minor warning appeared in researcher.log: Researcher callback: 'response' not found or has no parts. However, this did not impact the
     successful completion of the research or the overall pipeline.

  All services are currently active and logged at the DEBUG level as specified in run_local.sh.

Deploying to Azure Kubernates Service(AKS)

The project level Makefile has targets for managing the Agent deployment to serverless endpoints. A utility script checks the deployment status:

xbill@penguin:~/gemini-cli-azure/multi-aks$ make status
Checking AKS Deployment status...

You can submit the build for GKE deployment:

make deploy

│ deployment "orchestrator" successfully rolled out │
│ deployment "course-creator" successfully rolled out │
│ Deployment complete! │
│ Course Creator External IP (may take a moment to appear): │
│ 20.99.250.177         

✦ I have successfully deployed the AI Course Creator system to Azure AKS. 

  All services are now running and healthy:
   - Researcher: Running
   - Judge: Running
   - Content Builder: Running
   - Orchestrator: Running
   - Course Creator (Web App): Running at http://20.99.250.177 (http://20.99.250.177)

  Key fixes applied during deployment:
   - Tracing: Disabled mandatory Cloud Trace in app/main.py and removed the --trace_to_cloud flag from all agent Dockerfiles to prevent startup
     crashes caused by missing Google Cloud credentials on Azure.
   - Rollout: Forced a container restart to ensure the latest Docker images with the above fixes were pulled by the AKS cluster.

  You can now access the AI Course Creator at the external IP provided above.

Once the containers are deployed- you can then get the endpoint:

✦ I have retrieved the external IP of the AI Course Creator system on Azure AKS.

The application is now accessible at: http://20.99.250.177 (http://20.99.250.177)

The status can then be checked:


> make status

xbill@penguin:~/gemini-cli-azure/multi-aks$ make status
Checking AKS Deployment status...
NAME READY UP-TO-DATE AVAILABLE AGE
content-builder 0/1 1 0 119m
course-creator 1/1 1 1 119m
judge 0/1 1 0 119m
orchestrator 0/1 1 0 119m
researcher 0/1 1 0 119m
NAME READY STATUS RESTARTS AGE
content-builder-7b5c47d4ff-4r7xt 0/1 CrashLoopBackOff 6 (3m35s ago) 9m54s
course-creator-85769bfb77-9dn7t 1/1 Running 0 9m53s
judge-84d84b55f-6hkv2 0/1 CrashLoopBackOff 6 (3m39s ago) 9m54s
orchestrator-69cfb5c6dd-cv8kh 0/1 CrashLoopBackOff 6 (3m32s ago) 9m53s
researcher-6545fbcb8d-wsnbx 0/1 CrashLoopBackOff 6 (3m49s ago) 9m54s
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
content-builder ClusterIP 10.0.214.225 <none> 8000/TCP 119m
course-creator LoadBalancer 10.0.85.76 20.99.250.177 80:32394/TCP 119m
judge ClusterIP 10.0.106.30 <none> 8000/TCP 119m
kubernetes ClusterIP 10.0.0.1 <none> 443/TCP 123m
orchestrator ClusterIP 10.0.165.216 <none> 8000/TCP 119m
researcher ClusterIP 10.0.32.188 <none> 8000/TCP 119m

The service will be visible in the Azure console:

And the entire system can be tested:

✦ I will run the end-to-end test against the AKS cluster to ensure the deployment is functional.

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell make e2e-test-aks [current working directory /home/xbill/gemini-cli-azure/multi-aks] (Execute the end-to-end test against the AKS c… │
│ │
│ ... first 6 lines hidden (Ctrl+O to show) ... │
│ {"type": "progress", "text": "\ud83d\udd0d Researcher is gathering information..."} │
│ {"type": "progress", "text": "\u2696\ufe0f Judge is evaluating findings..."} │
│ {"type": "progress", "text": "\u2696\ufe0f Judge is evaluating findings..."} │
│ {"type": "progress", "text": "\u270d\ufe0f Building the final course content..."} │
│ {"type": "progress", "text": "\u270d\ufe0f Content Builder is writing the course..."} │
│ {"type": "result", "text": "# The History of the Internet\n\n## Module 1: The Dawn of Networking (Pre-1960s to 1970s)\n\n### Early Concepts │
│ and Cold War Context\n* **Cold War Imperatives** : The internet's origins are rooted in 1950s Cold War anxieties, specifically after │
│ Sputnik's launch in 1957. This prompted the U.S. to establish ARPA (Advanced Research Projects Agency) with a key driver being the desire for │
│ a communication network resilient to attack.\n* **Visionaries and Packet Switching** :\n * **Paul Baran** at RAND Corporation proposed │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The make e2e-test-aks command was executed successfully. 

  I first switched the kubectl context to the correct Azure AKS cluster (adk-aks-penguin). Then, I verified that the course-creator service was
  running with a public LoadBalancer IP. Finally, I ran the end-to-end test, which successfully communicated with the AKS-deployed microservices
  (Researcher, Judge, and Content Builder) to generate a course on "The History of the Internet."

Running the Web Interface

Start a connection to the Cloud Run deployed app:

http://20.99.250.177

Then connect to the app :

Then use online course generator:

Final Gemini CLI Code Review

As a final step — Gemini CLI was used for a full code review of the project:

✦ This multi-agent project is a well-engineered application of ADK 2.5 and the A2A protocol. The separation of specialized agents (Researcher,
  Judge, Content Builder) coordinated by a central Orchestrator demonstrates a mature microservice-oriented design.

Key Strengths
   * Coordinated Orchestration: The use of SequentialAgent and LoopAgent creates a robust, iterative research-judge cycle.
   * Resilient State Flow: The strategy of passing data through event content and "recovering" it via before_agent_callback heuristics is a clever
     way to handle state across distributed, independent session stores.
   * Polished Streaming: The web app's SSE implementation, specifically the greedy overlap deduplication (merge_strings) and system message
     cleanup, ensures a high-quality user experience despite the inherent noise in multi-agent LLM streams.
   * Cloud-Native Readiness: Using Identity Tokens for authenticated service-to-service communication and middleware for dynamic A2A URL rewriting
     makes the system ready for production deployment on Cloud Run.

Summary

Multi-Agent A2A with the Agent Development Kit(ADK), Amazon EKS, and Gemini CLI

xbill — Mon, 13 Apr 2026 18:42:04 +0000

Aren’t There a Billion Python ADK Demos?

Yes there are.

Where is the Beef?

So what is different about this lab compared to all the others out there?

The original Codelab- is here:

Building a Multi-Agent System | Google Codelabs

Python Version Management

One of the downsides of the wide deployment of Python has been managing the language versions across platforms and maintaining a supported version.

The pyenv tool enables deploying consistent versions of Python:

GitHub - pyenv/pyenv: Simple Python version management

As of writing — the mainstream python version is 3.13. To validate your current Python:

python --version
Python 3.13.13

Amazon EKS

Amazon Elastic Kubernetes Service (EKS) is a fully managed service from Amazon Web Services (AWS) that makes it easy to run Kubernetes on AWS without needing to install, operate, or maintain your own Kubernetes control plane. It automates cluster management, security, and scaling, supporting applications on both Amazon EC2 and AWS Fargate.

More information is available here:

What is Amazon EKS?

Gemini CLI

If not pre-installed you can download the Gemini CLI to interact with the source files and provide real-time assistance:

npm install -g @google/gemini-cli

Testing the Gemini CLI Environment

Once you have all the tools and the correct Node.js version in place- you can test the startup of Gemini CLI. You will need to authenticate with a Key or your Google Account:

▝▜▄ Gemini CLI v0.33.1
    ▝▜▄
   ▗▟▀ Logged in with Google /auth
  ▝▀ Gemini Code Assist Standard /upgrade no sandbox (see /docs) /model Auto (Gemini 3) | 239.8 MB

Node Version Management

Gemini CLI needs a consistent, up to date version of Node. The nvm command can be used to get a standard Node environment:

GitHub - nvm-sh/nvm: Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions

Agent Development Kit

The ADK can be installed from here:

Agent Development Kit (ADK)

Agent Skills

Gemini CLI can be customized to work with ADK agents. Both an Agent Development MCP server, and specific Agent skills are available.

More details are here:

Agent Development Kit (ADK)

To get the Agent Skills in Gemini CLI:

> /skills list
Available Agent Skills:

and the ADK documentation:

> /mcp list
Configured MCP servers:
🟢 adk-docs-mcp (from adk-docs-ext) - Ready (2 tools)
  Tools:
  - mcp_adk-docs-mcp_fetch_docs
  - mcp_adk-docs-mcp_list_doc_sources

Where do I start?

The strategy for starting multi agent development is a incremental step by step approach.

First, the basic development environment is setup with the required system variables, and a working Gemini CLI configuration.

Then, ADK Multi-Agent is built, debugged, and tested locally. Finally — the entire solution is deployed to Google Cloud Run.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. All of the relevant code examples and documentation is available in GitHub.

The next step is to clone the GitHub repository to your local environment:

cd ~
git clone https://github.com/xbill9/gemini-cli-aws
cd multi-eks

Then run init2.sh from the cloned directory.

The script will attempt to determine your shell environment and set the correct variables:

source init2.sh

If your session times out or you need to re-authenticate- you can run the set_env.sh script to reset your environment variables:

source set_env.sh

Variables like PROJECT_ID need to be setup for use in the various build scripts- so the set_env script can be used to reset the environment if you time-out.

Finally install the packages and dependencies:

make install

Verify The ADK Installation

To verify the setup, run the ADK CLI locally with the researcher agent:

xbill@penguin:~/gemini-cli-aws/multi-eks/agents$ adk run researcher
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
Log setup complete: /tmp/agents_log/agent.20260412_164250.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
{"asctime": "2026-04-12 16:42:50,986", "name": "root", "levelname": "INFO", "message": "Logging initialized for researcher", "filename": "logging_config.py", "lineno": 54, "service": "researcher", "log_level": "INFO"}
{"asctime": "2026-04-12 16:42:50,987", "name": "researcher.agent", "levelname": "INFO", "message": "Initialized researcher agent with model: gemini-2.5-flash", "filename": "agent.py", "lineno": 85}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.envs", "levelname": "INFO", "message": "Loaded .env file for researcher at /home/xbill/gemini-cli-aws/multi-eks/.env", "filename": "envs.py", "lineno": 83}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/multi-eks/agents", "filename": "local_storage.py", "lineno": 84}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Using file artifact service at /home/xbill/gemini-cli-aws/multi-eks/agents/researcher/.adk/artifacts", "filename": "local_storage.py", "lineno": 110}
{"asctime": "2026-04-12 16:42:50,988", "name": "google_adk.google.adk.cli.utils.service_factory", "levelname": "INFO", "message": "Using in-memory memory service", "filename": "service_factory.py", "lineno": 266}
{"asctime": "2026-04-12 16:42:50,993", "name": "google_adk.google.adk.cli.utils.local_storage", "levelname": "INFO", "message": "Creating local session service at /home/xbill/gemini-cli-aws/multi-eks/agents/researcher/.adk/session.db", "filename": "local_storage.py", "lineno": 60}
Running agent researcher, type exit to exit.
[user]:

Test The ADK Web Interface

This tests the ADK agent interactions with a browser:

xbill@penguin:~/gemini-cli-aws/multi-eks/agents$ adk web --host 0.0.0.0
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:72: UserWarning: [EXPERIMENTAL] feature FeatureName.PLUGGABLE_AUTH is enabled.
  check_feature_enabled()
2026-04-12 16:43:14,152 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-12 16:43:14,153 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/gemini-cli-aws/multi-eks/agents
2026-04-12 16:43:14,153 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/gemini-cli-aws/multi-eks/agents/.adk/artifacts
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/fast_api.py:198: UserWarning: [EXPERIMENTAL] InMemoryCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  credential_service = InMemoryCredentialService()
/home/xbill/.local/lib/python3.13/site-packages/google/adk/auth/credential_service/in_memory_credential_service.py:33: UserWarning: [EXPERIMENTAL] BaseCredentialService: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  super(). __init__ ()
INFO: Started server process [32675]
INFO: Waiting for application startup.

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

INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Then use the web interface — either on the local interface 127.0.0.1 or the catch-all web interface 0.0.0.0 -depending on your environment:

Special note for Google Cloud Shell Deployments- add a CORS allow_origins configuration exemption to allow the ADK agent to run:

adk web --host 0.0.0.0 --allow_origins 'regex:.*'

Multi Agent Design

The multi-agent deployment consists of 5 agents:

Researcher
Judge
Orchestrator
Content Builder
Course Builder

For a detailed analysis of the multi-agent architecture- this article provides the background information:

Multi-Agent A2A with the Agent Development Kit(ADK), Cloud Run, and Gemini CLI

Running/Testing/Debugging Locally

The main Makefile has been extended with extensive targets for managing the agents on the local development environment.

The key targets include:

xbill@penguin:~/multi-agent$ make help
Available commands:
  install - Install all dependencies for root, agents, and app
  start - Start all services locally (alias for start-local)
  stop - Stop all local services (alias for stop-local)
  run - Start all services locally (alias for start-local)
  local - Show local service URLs
  start-local - Start all local services in background
  stop-local - Stop all local processes
  test - Run all tests (pytest)
  test-researcher - Test the Researcher agent directly
  test-judge - Test the Judge agent directly
  test-orchestrator - Test the Orchestrator logic
  lint - Run linting checks (ruff)
  deploy - Deploy all services to Cloud Run
  destroy - Delete all Cloud Run services
  clean - Remove caches and logs

First check for local running agents:

xbill@penguin:~/multi-agent$ make status
Checking status of locally running agents and servers...
--- Network Status ---
No services listening on expected ports (8000-8004, 5173).
--- Process Status ---
No matching processes found.

Then all the agents can be started together:

xbill@penguin:~/multi-agent$ make start
Stopping any existing agent and server processes...
Starting all agents in background...
Waiting for sub-agents to start...
All agents started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log
Starting App Backend in background...
Starting Frontend dev server in background...
All services started. Logs: researcher.log, judge.log, content_builder.log, orchestrator.log, backend.log, frontend.log
Frontend: http://localhost:5173
Backend: http://localhost:8000

make status

--- Local Service URLs ---
Frontend: http://localhost:5173
Backend: http://localhost:8000 (main app)
Agents:
  Researcher: http://localhost:8001
  Judge: http://localhost:8002
  Content Builder: http://localhost:8003
  Orchestrator: http://localhost:8004

Then connect to the front end locally:

And the entire agent system will run in the local environment:

Local Logging / Debugging

Gemini CLI has full access to the local agent logs for debugging and troubleshooting:

> review the local logs for the multi-agent run
✦ I will check run_local.sh and the project structure to determine where logs are stored or how they are generated.

This will verify the local operation of the code:

✦ The local logs confirm a successful multi-agent run for the topic "the history of the internet." Here is a summary of the execution flow:

   * Orchestrator (orchestrator.log): Successfully managed the pipeline. It captured the topic, coordinated the Research-Judge loop, and escalated to
     content generation after the first iteration.
   * Researcher (researcher.log): Gathered approximately 9.2KB of research data using the google_search tool. It completed its task with a 200 OK
     response.
   * Judge (judge.log): Evaluated the findings and gave a "pass" status. The judge noted that the research was "comprehensive, accurate, and
     well-structured," making it an "excellent foundation for educational content."
   * Content Builder (content_builder.log): Successfully transformed the validated research into a structured Markdown course module and finished
     execution.
   * Backend & Frontend (backend.log, frontend.log): The FastAPI backend (port 8000) and Vite frontend (port 5173) are running and communicating with
     the orchestrator as expected.

  Notable Observation:
   * A minor warning appeared in researcher.log: Researcher callback: 'response' not found or has no parts. However, this did not impact the
     successful completion of the research or the overall pipeline.

  All services are currently active and logged at the DEBUG level as specified in run_local.sh.

Deploying to Amazon Elastic Kubernates Service(EKS)

The project level Makefile has targets for managing the Agent deployment to serverless endpoints. A utility script checks the deployment status:

make status

You can submit the build for GKE deployment:

make deploy

xbill@penguin:~/gemini-cli-aws/multi-eks$ make deploy
chmod +x eks/*.sh
./eks/deploy-eks.sh
=== AWS EKS Deployment ===
AWS Region: us-east-1
Account ID: 106059658660
EKS Cluster: adk-eks-penguin
==========================
=== AWS EKS Cluster Setup/Check ===
AWS Region: us-east-1
Account ID: 106059658660
EKS Cluster: adk-eks-penguin
===================================
Checking ECR Repository researcher...
ECR Repository researcher already exists.
Checking ECR Repository judge...
ECR Repository judge already exists.
Checking ECR Repository content-builder...
ECR Repository content-builder already exists.
Checking ECR Repository orchestrator...
ECR Repository orchestrator already exists.
Checking ECR Repository course-creator...
ECR Repository course-creator already exists.
Checking if EKS Cluster adk-eks-penguin exists and is ACTIVE...
Updating kubeconfig for EKS Cluster adk-eks-penguin...
Updated context arn:aws:eks:us-east-1:106059658660:cluster/adk-eks-penguin in /home/xbill/.kube/config
EKS/ECR Setup Check Complete!
Logging in to Amazon ECR...

Waiting for deployments to complete...
deployment "researcher" successfully rolled out
deployment "judge" successfully rolled out
deployment "content-builder" successfully rolled out
deployment "orchestrator" successfully rolled out
deployment "course-creator" successfully rolled out
Deployment complete!
Course Creator External URL (may take a moment to appear):
a27c61bc6fb3c425ca13d862e0fe4aed-865627292.us-east-1.elb.amazonaws.com

Once the containers are deployed- you can then get the endpoint:

xbill@penguin:~/gemini-cli-aws/multi-eks$ make endpoint
--- AWS EKS Endpoint ---
a27c61bc6fb3c425ca13d862e0fe4aed-865627292.us-east-1.elb.amazonaws.com

The status can then be checked:

xbill@penguin:~/gemini-cli-aws/multi-eks$ make status
Checking EKS Deployment status...
NAME READY UP-TO-DATE AVAILABLE AGE
content-builder 1/1 1 1 18m
course-creator 1/1 1 1 18m
judge 1/1 1 1 18m
orchestrator 1/1 1 1 18m
researcher 1/1 1 1 18m
NAME READY STATUS RESTARTS AGE
content-builder-8854b857b-rnb8q 1/1 Running 0 18m
course-creator-55b5864d58-79p56 1/1 Running 0 18m
judge-5cd7ff57f6-cscdc 1/1 Running 0 18m
orchestrator-6fcfd7cb8f-bgdm6 1/1 Running 0 18m
researcher-8694d7bcd5-r6cb4 1/1 Running 0 18m
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
content-builder ClusterIP 10.100.206.249 <none> 8000/TCP 18m
course-creator LoadBalancer 10.100.125.244 a27c61bc6fb3c425ca13d862e0fe4aed-865627292.us-east-1.elb.amazonaws.com 80:32483/TCP 18m
judge ClusterIP 10.100.229.35 <none> 8000/TCP 18m
kubernetes ClusterIP 10.100.0.1 <none> 443/TCP 147m
orchestrator ClusterIP 10.100.91.62 <none> 8000/TCP 18m
researcher ClusterIP 10.100.182.137 <none> 8000/TCP 18m
xbill@penguin:~/gemini-cli-aws/multi-eks$

The service will be visible in the AWS console:

And the entire system can be tested:

 > make e2e-test-eks
✦ I will execute the e2e-test-eks command, which will attempt to fetch the EKS endpoint and run the end-to-end test.

╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✓ Shell make e2e-test-eks [current working directory /home/xbill/gemini-cli-aws/multi-eks] │
│ │
│ ... first 6 lines hidden (Ctrl+O to show) ... │
│ {"type": "progress", "text": "\ud83d\udd0d Researcher is gathering information..."} │
│ {"type": "progress", "text": "\u2696\ufe0f Judge is evaluating findings..."} │
│ {"type": "progress", "text": "\u2696\ufe0f Judge is evaluating findings..."} │
│ {"type": "progress", "text": "\u270d\ufe0f Building the final course content..."} │
│ {"type": "progress", "text": "\u270d\ufe0f Content Builder is writing the course..."} │
│ {"type": "result", "text": "# The History of the Internet\n\n## Module 1: The Genesis of Connectivity (1960s-1970s)\n\n### 1.1 Early Concepts │
│ and Visionaries\n\n* **J.C.R. Licklider's \"Galactic Network\"** \n * In 1962, J.C.R. Licklider envisioned a globally interconnected │
│ set of computers for universal data and program access.\n * Licklider, from MIT and ARPA, described a concept strikingly similar to │
│ today's internet.\n* **Packet Switching** \n * **Paul Baran** (RAND Corporation, early 1960s) and **Donald Davies** (UK's National │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

✦ The e2e-test-eks command completed successfully, confirming that the EKS deployment is fully operational and reachable. The test successfully
  triggered the research and content generation pipeline, resulting in a detailed Markdown course on the history of the internet.

Running the Web Interface

Start a connection to the Cloud Run deployed app:

http://a27c61bc6fb3c425ca13d862e0fe4aed-865627292.us-east-1.elb.amazonaws.com

Then connect to the app :

Then use online course generator:

Final Gemini CLI Code Review

As a final step — Gemini CLI was used for a full code review of the project:

✦ This multi-agent project is a well-engineered application of ADK 2.5 and the A2A protocol. The separation of specialized agents (Researcher,
  Judge, Content Builder) coordinated by a central Orchestrator demonstrates a mature microservice-oriented design.

Key Strengths
   * Coordinated Orchestration: The use of SequentialAgent and LoopAgent creates a robust, iterative research-judge cycle.
   * Resilient State Flow: The strategy of passing data through event content and "recovering" it via before_agent_callback heuristics is a clever
     way to handle state across distributed, independent session stores.
   * Polished Streaming: The web app's SSE implementation, specifically the greedy overlap deduplication (merge_strings) and system message
     cleanup, ensures a high-quality user experience despite the inherent noise in multi-agent LLM streams.
   * Cloud-Native Readiness: Using Identity Tokens for authenticated service-to-service communication and middleware for dynamic A2A URL rewriting
     makes the system ready for production deployment on Cloud Run.

Summary

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.