Copied to Clipboard
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:
>makee2e-test-eks✦Iwillexecutethee2e-test-ekscommand,whichwillattempttofetchtheEKSendpointandruntheend-to-endtest.╭───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮│✓Shellmakee2e-test-eks[currentworkingdirectory/home/xbill/gemini-cli-aws/multi-eks]││││...first6lineshidden(Ctrl+Otoshow)...││{"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
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 EKS. Finally, Gemini CLI was used for a complete project code review.