Deploying ADK Agents on Azure ACA (Azure Container Apps)

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build Agents in...

title: Deploying ADK Agents on Azure ACA (Azure Container Apps) published: true series: Azure date: 2026-04-02 18:18:19 UTC tags: geminicli,azurecontainerapps,agents,googleadk canonical_url: https://xbill999.medium.com/deploying-adk-agents-on-azure-aca-azure-container-apps-12bb57d45658

Leveraging the Google Agent Development Kit (ADK) and the underlying Gemini LLM to build Agents in the Python programming language deployed on the Azure Cloud platform.

What is Gemini CLI?

The Gemini CLI is an open-source, terminal-based AI agent from Google that allows developers to interact directly with Gemini models, such as Gemini 2.5 Pro, for coding, content creation, and workflow automation. It supports file operations, shell commands, and connects to external tools via the Model Context Protocol (MCP).

The full details on Gemini CLI are available here:

Build, debug & deploy with AI

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?

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 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

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:

xbill@penguin:~/gemini-cli-azure/adkui-aca$ python --version
Python 3.13.12

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:

azureuser@azure-new:~/gemini-cli-azure$ gemini

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

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

To verify the Node version:

xbill@penguin:~/gemini-cli-azure/adkui-aca$ nvm --version
0.40.3
xbill@penguin:~/gemini-cli-azure/adkui-aca$ node --version
v25.9.0
xbill@penguin:~/gemini-cli-azure/adkui-aca$ npm --version
11.12.1
xbill@penguin:~/gemini-cli-azure/adkui-aca$ 

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 Agent development is a incremental step by step approach.

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

Create and deploy low code ADK (Agent Deployment Kit) agents using ADK Visual Builder | 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 Google Cloud Run.

Setup the Basic Environment

At this point you should have a working Python environment and a working Gemini CLI installation. The next step is to clone the GitHub samples repository with support scripts:

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

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.

Azure Login

All of the deployment is done with the az CLI tool- but it also needs an active login on the Azure environment. To check the version:

xbill@penguin:~/gemini-cli-azure/adkui-aca$ az --version
azure-cli 2.84.0

core 2.84.0
telemetry 1.1.0

Dependencies:
msal 1.35.0b1
azure-mgmt-resource 24.0.0

Python location '/opt/az/bin/python3'
Config directory '/home/xbill/.azure'
Extensions directory '/home/xbill/.azure/cliextensions'

Python (Linux) 3.13.11 (main, Feb 25 2026, 02:29:30) [GCC 12.2.0]

Legal docs and information: aka.ms/AzureCliLegal

Your CLI is up-to-date.
xbill@penguin:~/gemini-cli-azure/adkui-aca$

To login to Azure:

az login

Then you will see a message after successful authentication:

You have logged into Microsoft Azure!
You can close this window, or we will redirect you to the Azure CLI documentation in 1 minute.

Verify The ADK Installation

To verify the setup, run the ADK CLI with Agent3:

xbill@penguin:~/gemini-cli-azure/adkui-aca$ adk run Agent3
Log setup complete: /tmp/agents_log/agent.20260402_131951.log
To access latest log: tail -F /tmp/agents_log/agent.latest.log
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/utils/agent_loader.py:277: UserWarning: [EXPERIMENTAL] _load_from_yaml_config: This feature is experimental and may change or be removed in future versions without notice. It may introduce breaking changes at any time.
  if root_agent := self._load_from_yaml_config(actual_agent_name, agents_dir):
/home/xbill/.local/lib/python3.13/site-packages/google/adk/features/_feature_decorator.py:81: UserWarning: [EXPERIMENTAL] feature FeatureName.AGENT_CONFIG is enabled.
  check_feature_enabled()
/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 studio_director, type exit to exit.
[user]: hello
[studio_director]: Hello! I'm the Studio Director, ready to help you create a comic book. What kind of comic book would you like to create?

[user]: 

Running the ADK Web Interface

First- start the ADK interface:

xbill@penguin:~/gemini-cli-azure/adkui-aca$ adk web --host 0.0.0.0
2026-04-02 13:21:40,287 - INFO - service_factory.py:266 - Using in-memory memory service
2026-04-02 13:21:40,287 - INFO - local_storage.py:84 - Using per-agent session storage rooted at /home/xbill/gemini-cli-azure/adkui-aca
2026-04-02 13:21:40,287 - INFO - local_storage.py:110 - Using file artifact service at /home/xbill/gemini-cli-azure/adkui-aca/.adk/artifacts
/home/xbill/.local/lib/python3.13/site-packages/google/adk/cli/fast_api.py:192: 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 [11290]
INFO: Waiting for application startup.

Connecting to the ADK

The ADK web interface is started with the place holder 0.0.0.0 address — which tells the service to listen on all interfaces. Depending on your local environment setup- you may need to use the actual local interface. There are 2 potential options:

http://0.0.0.0:8000

http://127.0.0.1:8000

This will bring up the ADK UI:

Run a Sub Agent

Connect to the ADK and select “Agent3”:

The first interaction just verifies the connection to the agent:

what do you do?

I manage a linear pipeline of four ADK Sequential Agents to transform a user's seed idea into a fully rendered, responsive HTML5 comic book. If your request starts with "Create me a comic of...", I'll delegate the task to my sub-agent to begin the comic creation pipeline. Otherwise, I'll answer your question directly.

Give the Agent this prompt:

Create a comic of Bob and Clippy in a Battle Royal with Tux.

The sub agent will then generate the comic book images:

Visual Build an Agent

To use the ADK visual builder- select the pencil Icon next to Agent 2. You can drill down into the Agent design:

What did I just do?

The initial steps validate that the Python code and the ADK environment is functional and that the Agent code will run correctly. The next step is to deploy this environment to the Azure Container App Service.

Deploying to Azure Container App Service

To start the deployment:

xbill@penguin:~/gemini-cli-azure/adkui-aca$ make deploy
./deploy-aca.sh
=== Azure Container Apps Deployment ===
Resource Group: adk-rg-westus2
Location: westus2
ACR Name: adkacrpenguinv2
App Name: adk-app-penguin
Env Name: adk-env-penguin
Image: adkacrpenguinv2.azurecr.io/adk-image:latest
========================================

You can validate the final result by checking the messages:

│ Deploying to Azure Container App... │
│ Adding registry password as a secret with name "adkacrpenguinv2azurecrio-adkacrpenguinv2" │
│ │
│ Container app created. Access your app at │
│ https://adk-app-penguin.delightfulbeach-bf25c97b.westus2.azurecontainerapps.io/   

You can then get the endpoint:

xbill@penguin:~/gemini-cli-azure/adkui-aca$ make endpoint
--- Azure Container App Endpoint ---
adk-app-penguin.delightfulbeach-bf25c97b.westus2.azurecontainerapps.io

You can verify the service in the Azure console:

Running the ADK Web Interface

Start a connection to the Azure Deployed ADK:

 https://adk-app-penguin.delightfulbeach-bf25c97b.westus2.azurecontainerapps.io

This will bring up the ADK UI:

Select the sub-agent “Agent3” and ask the Agent to create a comic about Bit:

Bit the Raccoon is a popular, unofficial community mascot for Microsoft Azure,
specifically representing the Cloud Advocate team and open-source initiatives. 
Created by Ashley McNamara, Bit is often depicted in tech-related, helpful 
scenarios to make complex cloud concepts more accessible and approachable 
to developers. X X +2 Role: Known as the "Developer Advocate Mascot," 
Bit is often used in presentations and content to represent the "open" 
aspect of Azure. Context: While Azure has an official anime-style mascot 
in Japan (Claudia Madobe), Bit is beloved within the broader developer 
community as a fun, tech-savvy character.

Appearance: Bit is usually styled as an adorable, helpful raccoon, 
sometimes accompanied by other community mascots like "Brady the Ninja Sloth."
GitHub GitHub Bit is a favorite for stickers and frequently appears 
on social media to highlight new Azure features.

Create a story about bit

The Agent will get to work:

Run the Viewer Agent

Connect to the ADK and select “Agent4”:

I've exported the comic as ADK artifacts for you!

You can now view the comic directly within the ADK environment. Please check the 'Artifacts' pane or tab in your ADK Visual Builder / Studio UI.

You'll find the following:

view_full_comic.html: This is a complete, self-contained HTML file with embedded images for the full comic experience.
comic_preview.md: A markdown summary of the comic.
Individual panel images (e.g., panel_panel_1.png).
If you are working in a local terminal, you can still view the original local files by opening output/comic.html in your browser or by running ./comic.sh. However, the ADK artifacts are the best way to view it while hosted!

The Agent will generate the artifacts:

The Comic can then be viewed:

Summary

The Agent Development Kit was used to visually define a basic agent and added a tool that calls the ImageGen Gemini Model. This Agent was tested locally with the CLI and then with the ADK web tool. Then, the Agent was packaged and deployed to the Azure Container App Service. Several sample ADK agents were run directly from the deployment in Azure. This approach validates that cross cloud tools can be used — even with more complex agents.