Level: Advanced ยท Env: Google Cloud Shell (or a local machine with gcloud, kubectl, docker, and Node.js 22+)
A travel planner made of three independent agents that have never seen each other's source code: a travel-orchestrator (ADK, Python) on Cloud Run that delegates flight questions to a flight-search-agent (ADK, Python) on GKE Autopilot, and hotel questions to a hotel-search-agent (LangGraph.js, Node) on a bare Compute Engine VM. All three speak A2A (Agent2Agent) - one shared JSON-RPC protocol, three different runtimes, three different platforms.
By the end you'll be able to:
RemoteA2aAgent up to a specialist agent running anywhere on the networkIn Workshop 2, a Sequential or Router agent delegated to sub_agents that lived in the same Python process, the same codebase, the same deployment. A2A (Agent2Agent) is what happens when the specialist isn't in your codebase at all - it's a completely separate service, possibly written in a different language, running on different infrastructure, that you reach over plain HTTP and JSON-RPC.
flowchart TD
User["User / CLI"]
Orch["travel-orchestrator (ADK, Python) - Cloud Run"]
Flight["flight-search-agent (ADK, Python) - GKE Autopilot"]
Hotel["hotel-search-agent (LangGraph.js, Node) - Compute Engine VM"]
User -- "A2A (JSON-RPC over HTTP)" --> Orch
Orch -- "A2A (JSON-RPC over HTTP)" --> Flight
Orch -- "A2A (JSON-RPC over HTTP)" --> Hotel
Every A2A agent publishes an AgentCard - a small JSON document at a well-known URL describing its name, skills, and the RPC endpoint that accepts requests - and that card is the entire contract between the two sides. The orchestrator never imports flight-search-agent's Python or hotel-search-agent's JavaScript, it fetches the card, reads the skills, and calls the RPC endpoint exactly the same way for both.
Workshop 2's | This workshop's | |
Lives in | Same Python process | A separate, independently deployed service |
Language/framework | Must be ADK, same process | Anything that speaks A2A - ADK, LangGraph.js, or otherwise |
Discovery | Python import | Fetch the remote AgentCard over HTTP |
Call | Direct in-process function call | JSON-RPC over HTTP |
Deployment | Ships together | Each agent has its own platform, its own scaling, its own IAM |
Agent | Framework | Platform | Deploy tool |
| ADK (Python) | Cloud Run |
|
| ADK (Python) | GKE Autopilot |
|
| LangGraph.js (Node) | Compute Engine VM |
|
flight-search-agent and travel-orchestrator are scaffolded with agents-cli, a different and newer toolchain than the bare adk CLI used in Workshops 1 to 3 - it layers infrastructure scaffolding, evaluation tooling, and CI/CD generation on top of the exact same underlying ADK agent code you already know. hotel-search-agent is a plain Node project built on LangGraph.js and the official @a2a-js/sdk, proof that A2A interop works across language boundaries, not just cloud platforms.
git clone https://github.com/adityajoshi12/ai-workshops/
cd ai-workshops/a2a-communication
Install the tools this workshop needs beyond what Workshops 1 to 3 used:
uv tool install google-agents-cli
agents-cli login -i
You'll also need gcloud, kubectl, and docker on PATH (all pre-installed in Cloud Shell), plus Node.js 22 or newer for hotel-search-agent. Authenticate everything once:
gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR_PROJECT_ID
gcloud services enable run.googleapis.com container.googleapis.com compute.googleapis.com aiplatform.googleapis.com
Install each agent's own dependencies:
(cd flight-search-agent && agents-cli install)
(cd hotel-search-agent && npm install)
(cd travel-orchestrator && agents-cli install)
Start with the specialist that's easiest to reason about. flight-search-agent/app/agent.py is a completely ordinary ADK agent, no A2A-specific code in sight:
flight-search-agent/app/agent.py
def search_flights(origin: str, destination: str, date: str) -> dict:
"""Searches mock flight options between two airports on a given date."""
...
root_agent = Agent(
name="flight_search_agent",
model=Gemini(model="gemini-3.7-flash"),
instruction="You are a flight search specialist...",
tools=[search_flights],
)
app = App(root_agent=root_agent, name="app")
The A2A surface gets attached separately, by app_utils/a2a.py's attach_a2a_routes - it builds an AgentCard from the agent's own name, description, and tools, then mounts a JSON-RPC endpoint at /a2a/{app.name}, both wired into the same FastAPI app the agent already runs on. You never hand-write the card yourself, ADK generates it straight from the agent you already built.
Now open the piece that makes this workshop different from Workshop 2: travel-orchestrator/app/agent.py.
travel-orchestrator/app/agent.py
import google.adk.agents.remote_a2a_agent as ra
from google.adk.agents.remote_a2a_agent import AGENT_CARD_WELL_KNOWN_PATH, RemoteA2aAgent
ra._is_loopback_host = lambda host: True
FLIGHT_AGENT_URL = os.environ.get("FLIGHT_AGENT_URL", "http://localhost:8001")
HOTEL_AGENT_URL = os.environ.get("HOTEL_AGENT_URL", "http://localhost:8002")
flight_agent = RemoteA2aAgent(
name="flight_search_agent",
description="Searches mock flight options between an origin and destination.",
agent_card=f"{FLIGHT_AGENT_URL}/a2a/app{AGENT_CARD_WELL_KNOWN_PATH}",
)
hotel_agent = RemoteA2aAgent(
name="hotel_search_agent",
description="Searches mock hotel options in a city for a date range.",
agent_card=f"{HOTEL_AGENT_URL}/a2a/app{AGENT_CARD_WELL_KNOWN_PATH}",
)
root_agent = Agent(
name="travel_orchestrator",
model=Gemini(model="gemini-3.7-flash"),
instruction="Delegate flight questions to flight_search_agent and hotel questions to hotel_search_agent...",
sub_agents=[flight_agent, hotel_agent],
)
Two things worth stopping on. First, RemoteA2aAgent still goes straight into sub_agents=[...] - from the orchestrator's own LLM's point of view, a remote A2A specialist looks exactly like a local one, right down to the name and description the model reads when it decides whom to delegate to. Second, that ra._is_loopback_host = lambda host: True line: ADK's RemoteA2aAgent refuses plain HTTP for any non-localhost URL by default, as a security guardrail, and this demo patches that check off so a direct-IP GKE or VM target can be reached over plain HTTP instead of HTTPS.
Last, hotel-search-agent's card and executor prove the same protocol works from a completely different stack. agentCard.js hand-builds the exact same AgentCard shape ADK generates automatically:
hotel-search-agent/src/agentCard.js
export const agentCard = {
name: "hotel_search_agent",
description: "Searches mock hotel options in a city for a date range.",
supportedInterfaces: [{ url: `${APP_URL}${RPC_PATH}`, protocolBinding: "JSONRPC", protocolVersion: A2A_PROTOCOL_VERSION }],
capabilities: { streaming: true, pushNotifications: false },
securitySchemes: {},
skills: [{ id: "search_hotels", name: "Search Hotels", description: "..." }],
};
And executor.js bridges A2A's task lifecycle (submitted, then working, then completed, with an artifact carrying the result) to a real LangGraph.js agent call - the same states ADK's own executor emits internally, just implemented by hand instead of by a framework, and travel-orchestrator's RemoteA2aAgent doesn't know or care which side generated them.
Before touching the cloud, prove the whole system works on your machine, for free:
./scripts/run-local.sh
This starts flight-search-agent on port 8001, hotel-search-agent on port 8002, and travel-orchestrator on port 8000, each with its own runtime's native start command - uvicorn for the two Python agents, node for the Node one. Give it a few seconds, then inspect a card directly:
curl http://localhost:8001/a2a/app/.well-known/agent-card.json | jq .
You should see the flight agent's name, its one search_flights skill, and the RPC URL it advertises. Now send a real trip-planning prompt through the orchestrator:
./scripts/test-local.sh "Plan a trip to Austin, Oct 3-5, flying out of SFO"
Watch the response combine results from both specialists into one itinerary - that's the orchestrator calling two remote AgentCards over two separate HTTP connections, then merging the answers itself. Tear it down when you're satisfied:
./scripts/stop-local.sh
cd flight-search-agent
agents-cli infra single-project --project YOUR_PROJECT_ID --apply
Terraform provisions the VPC, a GKE Autopilot cluster, and a placeholder deployment. Replace the placeholder with the real container:
agents-cli deploy --no-confirm-project --project YOUR_PROJECT_ID
Wait for the LoadBalancer to get an external IP, then bake that address into the pod so its AgentCard advertises somewhere other than a bare 0.0.0.0:
kubectl get svc flight-search-agent -n flight-search-agent -w
GKE_IP=$(kubectl get svc flight-search-agent -n flight-search-agent -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
kubectl set env deployment/flight-search-agent APP_URL="http://${GKE_IP}:8080" -n flight-search-agent
kubectl rollout status deployment/flight-search-agent -n flight-search-agent
Verify the card is healthy before moving on:
curl -s http://${GKE_IP}:8080/a2a/app/.well-known/agent-card.json | jq .
hotel-search-agent deploys to a bare Container-Optimized OS VM, no managed platform at all, on purpose, to prove A2A doesn't need one. From the a2a-communication root directory:
./scripts/deploy-hotel-vm.sh
This one script builds the container with Cloud Build, opens firewall port 8080 if it isn't already, provisions the COS VM with a self-configuring startup script, and prints the VM's external IP. The startup script is worth reading once, because it does two things a managed platform would normally handle for you automatically:
export HOME=/var/lib/docker
docker-credential-gcr configure-docker --registries=gcr.io
docker run -d --restart=always -p 8080:8080 -e APP_URL=http://${VM_IP}:8080 gcr.io/${PROJECT_ID}/hotel-search-agent
Verify the card the same way as before:
VM_IP=$(gcloud compute instances describe hotel-search-agent-vm --zone=asia-south1-a --format='get(networkInterfaces[0].accessConfigs[0].natIP)')
curl -s http://${VM_IP}:8080/a2a/app/.well-known/agent-card.json | jq .
Deploy the orchestrator last, once you have both GKE_IP and VM_IP in hand:
cd ../travel-orchestrator
agents-cli deploy --no-confirm-project --project YOUR_PROJECT_ID \
--update-env-vars "FLIGHT_AGENT_URL=http://${GKE_IP}:8080,HOTEL_AGENT_URL=http://${VM_IP}:8080,GOOGLE_GENAI_USE_VERTEXAI=true,GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID,GOOGLE_CLOUD_LOCATION=global"
Cloud Run defaults to requiring authentication, so grant public access for this demo:
gcloud run services add-iam-policy-binding travel-orchestrator --region=asia-south1 --member="allUsers" --role="roles/run.invoker"
Verify the orchestrator's own card now lists both remote skills:
curl -s https://<orchestrator-cloud-run-url>/a2a/app/.well-known/agent-card.json | jq .
You should see flight_search_agent and hotel_search_agent both listed under skills - proof the orchestrator successfully fetched both remote AgentCards at startup.
agents-cli run --url https://<orchestrator-cloud-run-url> --mode a2a "Plan a trip to Austin, Oct 3-5, flying out of SFO"
This single request now travels through three cloud platforms and two frameworks - Cloud Run calls a Kubernetes pod on GKE and a bare VM on Compute Engine over plain HTTP and JSON-RPC, and the wire protocol never notices that one of them is Node instead of Python. Try the two single-specialist prompts as well, to confirm the orchestrator's LLM correctly routes each one to only the relevant agent:
agents-cli run --url https://<orchestrator-cloud-run-url> --mode a2a "Find round-trip flights between SFO and Austin for Oct 3-5"
agents-cli run --url https://<orchestrator-cloud-run-url> --mode a2a "Find hotels in Austin for Oct 3-5"
"Agent card URL must use https, or http on a loopback host": ADK's RemoteA2aAgent blocks plain HTTP to non-localhost targets by default, so confirm the ra._is_loopback_host = lambda host: True patch in travel-orchestrator/app/agent.py is actually present.
403 Forbidden calling the orchestrator's Cloud Run URL: the service still requires authentication - re-run the add-iam-policy-binding command for allUsers.
"No API key was provided": google-genai defaults to Google AI Studio unless told otherwise - set GOOGLE_GENAI_USE_VERTEXAI=true.
GKE card still advertises a bare 0.0.0.0 address: the APP_URL env var never reached the pod - re-run kubectl set env and wait for kubectl rollout status to finish before curling again.
COS VM error "mkdir /root/.docker: read-only file system": Container-Optimized OS mounts /root read-only, so the startup script must export HOME=/var/lib/docker before any docker-credential-gcr command.
Docker build fails on
uv sync --frozen
: the uv.lock file is missing from the build context - run uv lock locally first, then rebuild.
Every A2A endpoint in this demo is unauthenticated and reachable over plain HTTP once you know its address - deliberate simplifications for a workshop, not patterns to ship. A production version of this same architecture would add TLS termination in front of every agent (removing the need for the loopback patch entirely), authenticate agent-to-agent calls with Google-signed ID tokens the same way Workshop 3's MCP server does, and scope each agent's runtime service account down to exactly the APIs it calls instead of reusing a broad default identity.
Tear resources down to avoid ongoing GKE, VM, and Cloud Run charges:
cd flight-search-agent/deployment/terraform/single-project
terraform destroy -var-file=vars/env.tfvars
gcloud compute instances delete hotel-search-agent-vm --zone=asia-south1-a --quiet
gcloud compute firewall-rules delete allow-hotel-agent-8080 --quiet
gcloud container images delete gcr.io/YOUR_PROJECT_ID/hotel-search-agent --force-delete-tags --quiet
gcloud run services delete travel-orchestrator --region=asia-south1 --quiet
RemoteA2aAgent slots into sub_agents=[...] exactly like a local specialist - the orchestrator's LLM never knows the difference.run-local.sh before spending a single cloud dollar across three separate platforms.