Level: Intermediate ยท Env: Google Cloud Shell
Four small multi-agent apps, one per orchestration pattern, then deploy one of them to Cloud Run:
Pattern | Folder | What it teaches |
Router / Coordinator |
| An LLM dynamically picks which sub-agent should answer |
Sequential |
| A fixed pipeline: step 1 always runs before step 2 |
Parallel |
| Independent sub-agents run concurrently, then get merged |
Loop |
| Repeat a critique/revise cycle until a condition is met |
Finish Workshop 1 first (or at least the one-time environment setup). You should have adk --version working, your Gemini backend exported, and be sitting inside the ai-workshops/google-adk folder you cloned in Workshop 1's Environment Check step.
ADK gives you a small set of workflow agents you compose like building blocks. Each one just controls how its sub_agents run:
flowchart TB
subgraph Router["Router / Coordinator - LLM picks a specialist"]
R0([Root Agent]) -. delegates .-> R1[Billing Agent]
R0 -. delegates .-> R2[Tech Support Agent]
R0 -. delegates .-> R3[General Agent]
end
subgraph Sequential["Sequential - fixed pipeline, order guaranteed"]
S1[Step 1] --> S2[Step 2] --> S3[Step 3]
end
subgraph Parallel["Parallel - fan-out, then fan-in"]
P0([Fan-out]) --> P1[Agent A]
P0 --> P2[Agent B]
P0 --> P3[Agent C]
P1 --> P4([Fan-in / Merge])
P2 --> P4
P3 --> P4
end
subgraph Loop["Loop - repeat until approved or max_iterations"]
L1[Critic] --> L2[Reviser]
L2 -- not approved --> L1
L2 -- exit_loop called --> L3([Done])
end
SequentialAgent - runs sub-agents one after another, in order. Use when step B needs step A's output.ParallelAgent - runs sub-agents at the same time. Use when steps are independent and you want speed.LoopAgent - repeats its sub-agents until something calls escalate (or it hits max_iterations). Use for iterative refinement.Agent with sub_agents=[...] and no tools of its own. ADK auto-wires a transfer_to_agent tool, and the LLM decides at runtime which specialist gets the message. Use when the right handler depends on user intent.All four can nest inside each other - a SequentialAgent step can itself be a ParallelAgent, which is exactly what parallel_agent_demo does.
Open router_agent_demo/agent.py. Three specialists (billing_agent, tech_support_agent, general_agent), and a root agent that has no tools - only sub_agents and an instruction telling it to always delegate.
router_agent_demo/agent.py
root_agent = Agent(
name="support_router",
model=MODEL,
description="Routes a user's message to the right support specialist.",
instruction=(
"You are a routing coordinator for a support desk. Read the user's "
"message and immediately delegate to exactly one specialist:\n"
"- billing_agent: charges, payments, refunds, invoices, subscriptions\n"
"- tech_support_agent: bugs, errors, crashes, 'how do I' technical asks\n"
"- general_agent: everything else\n"
"Do not attempt to answer the question yourself - always delegate."
),
sub_agents=[billing_agent, tech_support_agent, general_agent],
)
Run it:
adk web
Pick router_agent_demo and try, in order:
billing_agenttech_support_agentgeneral_agentOpen the trace panel: the very first event from the root agent is a transfer_to_agent function call - it never generates a text answer itself.
Exercise: each specialist's description field is what the router reads to decide where to send things. Try weakening tech_support_agent's description to something vague and watch routing accuracy degrade - good lesson that description quality is routing quality.
Open research_assistant/agent.py and look at the bottom:
root_agent = SequentialAgent(
name="research_assistant",
sub_agents=[researcher, writer, refine_loop],
)
researcher writes to state["research"], writer reads {research} and writes state["draft"], and refine_loop (Part D, below) reads/rewrites {draft}. Order is guaranteed - writer never runs before researcher has finished.
Run it:
adk web
Pick research_assistant and ask: "Summarize the latest on Google ADK". Watch researcher -> writer -> the loop fire strictly in order in the trace panel.
Open parallel_agent_demo/agent.py:
gather = ParallelAgent(
name="gather",
sub_agents=[weather_agent, clock_agent, trivia_agent],
)
root_agent = SequentialAgent(
name="city_briefing",
sub_agents=[gather, synthesizer],
)
weather_agent, clock_agent, and trivia_agent don't depend on each other, so they run concurrently inside gather, each writing to its own output_key. Then synthesizer (a plain sequential step) reads all three and merges them into one answer.
Run it:
adk web
Pick parallel_agent_demo and ask: "Give me a briefing on Tokyo". In the trace panel, compare the timestamps on weather_agent, clock_agent, and trivia_agent - they overlap, unlike the strictly sequential steps in Part B. That overlap is the performance win ParallelAgent buys you.
Exercise: add a fourth parallel branch (e.g. a news_agent using google_search) and wire its output_key into the synthesizer instruction template.
Back in research_assistant/agent.py, look at the refine_loop:
def exit_loop(tool_context: ToolContext) -> dict:
"""Signal that the draft is approved and the refinement loop should stop."""
tool_context.actions.escalate = True
return {"status": "approved"}
critic = Agent(..., tools=[exit_loop], output_key="critique")
reviser = Agent(..., output_key="draft")
refine_loop = LoopAgent(
name="refine_loop",
max_iterations=3,
sub_agents=[critic, reviser],
)
Every pass: critic reads {draft} and either calls exit_loop (draft is good) or writes actionable feedback to {critique}; reviser applies that feedback and overwrites {draft}. The loop keeps going until exit_loop fires or max_iterations is hit - that cap is your safety net against an agent that never agrees its own work is good enough.
Run it: same research_assistant session from Part B - watch the trace panel count critic -> reviser passes and stop the moment exit_loop is called (often before hitting the 3-pass cap).
Combine two patterns: make router_agent_demo's tech_support_agent a SequentialAgent of its own (e.g. a "diagnose" step then a "suggest fix" step), or give it its own small LoopAgent for iterative troubleshooting. Nesting is the whole point - a workflow agent is just another Agent as far as its parent is concerned.
We'll deploy research_assistant since it already ships with .env-style docs. Same command shape as Workshop 1, just a different folder - use whichever backend column matches your setup.
Option A - Gemini Developer API:
adk deploy cloud_run research_assistant -- \
--region=us-central1 \
--set-env-vars=GOOGLE_API_KEY=YOUR_GEMINI_API_KEY,GOOGLE_GENAI_USE_VERTEXAI=FALSE
Option B - Vertex AI:
# One-time per project (skip if you already did this in Workshop 1):
PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format='value(projectNumber)')
gcloud projects add-iam-policy-binding $(gcloud config get-value project) \
--member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
--role="roles/aiplatform.user"
adk deploy cloud_run research_assistant -- \
--region=us-central1 \
--set-env-vars=GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID,GOOGLE_CLOUD_LOCATION=us-central1,GOOGLE_GENAI_USE_VERTEXAI=TRUE
Note the service URL, then create a session and invoke it exactly like Workshop 1:
export SERVICE_URL="https://adk-default-service-name-XXXXXXXXXX.us-central1.run.app"
curl -X POST "$SERVICE_URL/apps/research_assistant/users/u_123/sessions/s_1" \
-H "Content-Type: application/json" -d '{}'
curl -X POST "$SERVICE_URL/run" \
-H "Content-Type: application/json" \
-d '{
"appName": "research_assistant",
"userId": "u_123",
"sessionId": "s_1",
"newMessage": {
"role": "user",
"parts": [{"text": "Help me research Google ADK."}]
}
}'
The response event stream will show the full pipeline: researcher -> writer -> critic/reviser loop passes -> final draft.
gcloud run services delete adk-default-service-name --region=us-central1
Agent + sub_agents, no tools of its own -> LLM picks the specialist at runtime.SequentialAgent -> guaranteed order, data flows via state/output_key.ParallelAgent -> concurrent independent work, fanned back in by a following step.LoopAgent + an exit_loop tool that sets tool_context.actions.escalate = True, capped by max_iterations.adk deploy cloud_run plus the folder name.