Level: Advanced ยท Env: Google Cloud Shell (or a local machine with gcloud, kubectl, docker, and Node.js 22+)

What you'll build

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.

Learning objectives

By the end you'll be able to:

In 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
View diagram source
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 sub_agents

This workshop's RemoteA2aAgent

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

travel-orchestrator

ADK (Python)

Cloud Run

agents-cli deploy

flight-search-agent

ADK (Python)

GKE Autopilot

agents-cli deploy / kubectl

hotel-search-agent

LangGraph.js (Node)

Compute Engine VM

gcloud + a deploy script

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

A2A Protocol SpecGoogle ADK RemoteA2aAgent DocsBack to Workshop 3: MCP Servers