Skip to main content

Section 6: Parallel Agent Architectures

Companion Guide

This documentation serves as the written companion to the Master Google ADK video course. It aggregates content from Lectures 29 through 35.

Bestseller
Master Google ADK - Agent Development Kit

Master Google ADK - Agent Development Kit

Build Multi Agent Systems | Mac, Windows, Ubuntu | Deploy to Google Cloud | Free Gemini Key

★ 4.4👥 470+
View on Udemy

In this section, we will build a multi-agent system using Google's Agent Development Kit (ADK) that showcases how to run agents concurrently. By combining parallel workflows with a sequential pipeline, we will create a high-performance Research Suite capable of taking a complex topic, generating research questions, researching them all at the same time, and synthesizing the findings into a complete, well-designed HTML report.

1. Parallel Agent Architecture and Code Structure​

To build our Research Suite, we need an architecture that supports both step-by-step logic and simultaneous execution. Our architecture involves two primary concepts:

  1. Parallel Workflow Agent: An ADK agent that runs its defined sub-agents at the exact same time.
  2. Sequential Pipeline: An orchestrator that runs agents one after another. We will integrate our parallel agent as a single "step" within this broader sequential pipeline.

When a user submits a topic (e.g., "Model Context Protocol"), the system passes it to our root sequential orchestrator. The pipeline flows as follows:

  • Questions Generator: Breaks the topic down into 5 specific research questions.
  • Parallel Researcher: Spawns 5 concurrent agents to research each question simultaneously.
  • Query Generator: Merges the 5 research outputs into a single comprehensive prompt.
  • Requirements Writer, Designer, and Code Writer: Standard sequential agents (built in previous sections) that turn the research into a finalized HTML webpage.

Code Structure​

To keep our code clean and modular, every agent gets its own directory containing its logic, instructions, and descriptions.

agents/
├── root_website_builder/       # Orchestrator: Manages the 6-agent sequence
├── questions_generator/        # Agent 1: Generates 5 research questions
├── questions_researcher/       # Agent 2: 5 parallel agents research each question
├── query_generator/            # Agent 3: Synthesizes research into web dev query
├── requirements_writer/        # Agent 4: Converts query into detailed requirements
├── designer/                   # Agent 5: Creates visual design specifications
└── code_writer/                # Agent 6: Generates final HTML/CSS/JS code

Each of these directories follows a standard structure containing __init__.py, agent.py, description.txt, and instructions.txt.

2. Root Sequential Agent​

The Root Sequential Agent serves as the entry point for our multi-agent system. We call it "root" because it receives the initial user query and orchestrates the entire workflow.

Because it just runs the sub-agents in a strict order without needing to "reason" about which one to run next, we define it using the pre-built SequentialAgent class from the ADK.

agents/root_website_builder/agent.py
from google.adk.agents import SequentialAgent

# Import all sub-agents from their respective modules
from agents.questions_generator.agent import questions_generator_agent
from agents.questions_researcher.agent import parallel_questions_researcher_agent
from agents.query_generator.agent import query_generator_agent
from agents.requirements_writer.agent import requirements_writer_agent
from agents.designer.agent import designer_agent
from agents.code_writer.agent import code_writer_agent

root_agent = SequentialAgent(
    name="root_website_builder_agent",
    sub_agents=[
        questions_generator_agent,
        parallel_questions_researcher_agent,
        query_generator_agent,
        requirements_writer_agent,
        designer_agent,
        code_writer_agent
    ],
    description="This is a sequential agent that executes sub-agents in the provided order."
)
note

Notice that the second agent in our list is parallel_questions_researcher_agent. The sequential orchestrator treats this parallel group as a single step, waiting for all parallel tasks to complete before moving to the query_generator_agent.

3. Questions Generator LLM Agent​

The first active step in the pipeline is the Questions Generator. Its job is to take the user's topic and generate exactly 5 thought-provoking questions that will guide our research.

We use the standard LlmAgent for this, equipped with the google:search tool so it can gather initial context if the topic is new or highly technical.

agents/questions_generator/agent.py
from google.adk.agents import LlmAgent
from google.adk.tools import google_search

questions_generator_agent = LlmAgent(
    name="questions_generator_agent",
    model="gemini-2.0-flash",
    instructions=load_instructions_file("agents/questions_generator/instructions.txt"),
    description="An agent that takes a topic and generates 5 important questions.",
    tools=[google_search],
    output_key="questions_generator_output"
)

By defining the output_key, we ensure that the 5 generated questions are saved into the session state where subsequent agents can access them.

4. Questions Researcher Parallel Agent​

Here is where the magic happens. We want to research the 5 generated questions, but running 5 deep research tasks sequentially would take too long. Instead, we use a Parallel Workflow Agent.

Inside the questions_researcher module, we define 5 separate LlmAgent instances. Each agent is specifically instructed to grab its assigned question from the state, use the google_search tool to research it deeply, and output its findings.

agents/questions_researcher/agent.py
from google.adk.agents import LlmAgent, ParallelAgent
from google.adk.tools import google_search

# Define Researcher 1
question_researcher_agent_1 = LlmAgent(
    name="QuestionResearcher1",
    model="gemini-2.0-flash",
    instructions="You are assigned to answer QUESTION NUMBER 1 only. \n" + base_instructions,
    tools=[google_search],
    output_key="Question_1_research_output"
)

# ... (Repeat for Researchers 2, 3, 4, and 5) ...

# Group them into a ParallelAgent
parallel_questions_researcher_agent = ParallelAgent(
    name="parallel_questions_researcher_agent",
    sub_agents=[
        question_researcher_agent_1,
        question_researcher_agent_2,
        question_researcher_agent_3,
        question_researcher_agent_4,
        question_researcher_agent_5
    ],
    description="Runs five question research agents in parallel."
)
Why Parallel Execution?

By wrapping these 5 distinct LlmAgent instances in a ParallelAgent, ADK automatically handles invoking them concurrently. This dramatically reduces the total execution time of the research phase.

5. Query Generator LLM Agent​

Once the parallel agents finish, we have 5 separate chunks of detailed research scattered across our session state. Our downstream web-building agents (requirements writer, designer) expect a single, cohesive prompt.

The Query Generator acts as a synthesizer. It reads the specific state keys populated by the parallel agents and merges them.

agents/query_generator/agent.py
from google.adk.agents import LlmAgent

query_generator_agent = LlmAgent(
    name="query_generator_agent",
    model="gemini-2.0-flash",
    instructions=load_instructions_file("agents/query_generator/instructions.txt"),
    output_key="merged_query_output"
)

In the instructions.txt for this agent, we explicitly tell the LLM how to find the data using state bracket notation:

agents/query_generator/instructions.txt
You will receive research outputs from five question researcher agents:
- Question 1 Research: state['Question_1_research_output']
- Question 2 Research: state['Question_2_research_output']
- Question 3 Research: state['Question_3_research_output']
- Question 4 Research: state['Question_4_research_output']
- Question 5 Research: state['Question_5_research_output']

Synthesize, Don't Concatenate: Extract key insights and merge them into a coherent narrative.

6. Review of Agents​

To recap our data flow:

  1. The user provides a topic to the Root Sequential Agent.
  2. The Questions Generator creates 5 questions and stores them in questions_generator_output.
  3. The Parallel Agent fires up 5 sub-agents. Each looks at the questions, picks its assigned number, researches it via Google, and saves it to an isolated output key (e.g., Question_1_research_output).
  4. The Query Generator reads all 5 research keys, synthesizes them into a single comprehensive web development query, and saves it to merged_query_output.
  5. The Requirements Writer, Designer, and Code Writer ingest this synthesized data to produce the final generated_page.html file using our custom write_to_file tool.

7. Agent Setup and Demo​

To run this architecture, we will use the ADK's local development web UI. Ensure your code is set up properly by following these terminal commands in your project root:

# 1. Create a virtual environment
uv venv

# 2. Activate the virtual environment (Mac/Linux)
source .venv/bin/activate
# (For Windows: .venv\Scripts\activate)

# 3. Install dependencies from pyproject.toml
uv sync

# 4. Start the ADK Web Server
adk web ./agents

Running the Demo​

  1. Navigate to http://localhost:8000 in your browser.
  2. From the dropdown menu on the left, select root_website_builder_agent (our main orchestrator).
  3. Ensure Token Streaming is enabled at the top of the interface so you can watch the agents "think" in real time.
  4. Type a topic into the prompt, such as: "Model Context Protocol" and hit Enter.

You will see the orchestrator kick off. The first agent will generate questions, followed by a burst of simultaneous activity as all 5 parallel agents hit Google Search and generate their deep dives. Finally, the synthesis and coding agents will take over, ultimately outputting a beautifully structured HTML file in your output/ directory containing all the researched information!

What's Next?​

In the next section, we will take our agents off localhost and deploy them to production.

Bestseller
Master Google ADK - Agent Development Kit

Master Google ADK - Agent Development Kit

Build Multi Agent Systems | Mac, Windows, Ubuntu | Deploy to Google Cloud | Free Gemini Key

★ 4.4👥 470+
View on Udemy