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

DEV Community

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.