Skip to content

Commit 641e715

Browse files
eliasecchigeliasecchig
authored
feat: add adk gemini fullstack sample (#199)
1 parent 8260f8d commit 641e715

File tree

66 files changed

+18528
-2418
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

66 files changed

+18528
-2418
lines changed

‎.cloudbuild/terraform/build_triggers.tf‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,14 @@ locals {
8484
name = "live_api-cloud_run"
8585
value = "live_api,cloud_run"
8686
},
87+
{
88+
name = "adk_gemini_fullstack-agent_engine"
89+
value = "adk_gemini_fullstack,agent_engine"
90+
},
91+
{
92+
name = "adk_gemini_fullstack-cloud_run"
93+
value = "adk_gemini_fullstack,cloud_run"
94+
},
8795
]
8896

8997
agent_testing_included_files = { for combo in local.agent_testing_combinations :
@@ -126,8 +134,11 @@ locals {
126134
name = "live_api-cloud_run"
127135
value = "live_api,cloud_run"
128136
},
137+
{
138+
name = "adk_gemini_fullstack-agent_engine"
139+
value = "adk_gemini_fullstack,agent_engine"
140+
},
129141
]
130-
131142
# Create a safe trigger name by replacing underscores with hyphens and dots with hyphens
132143
# This ensures we have valid trigger names that don't exceed character limits
133144
trigger_name_safe = { for combo in local.agent_testing_combinations :

‎Makefile‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,3 +26,5 @@ install:
2626

2727
docs-dev:
2828
cd docs && npm install && NODE_OPTIONS="--no-warnings" npm run docs:dev
29+
30+

‎agents/adk_gemini_fullstack/README.md‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
# Gemini Fullstack Agent Development Kit (ADK) Quickstart
2+
3+
The **Gemini Fullstack Agent Development Kit (ADK) Quickstart** is a production-ready blueprint for building a sophisticated, fullstack research agent with Gemini. It's built to demonstrate how the ADK helps structure complex agentic workflows, build modular agents, and incorporate critical Human-in-the-Loop (HITL) steps.
4+
5+
<div style="display: flex; align-items: center; justify-content: space-between;">
6+
<table style="width: 50%;">
7+
<thead>
8+
<tr>
9+
<th colspan="2">Key Features</th>
10+
</tr>
11+
</thead>
12+
<tbody>
13+
<tr>
14+
<td>🏗️</td>
15+
<td><strong>Fullstack & Production-Ready:</strong> A complete React frontend and ADK-powered FastAPI backend, with deployment options for <a href="https://cloud.google.com/run">Google Cloud Run</a> and <a href="https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview">Vertex AI Agent Engine</a>.</td>
16+
</tr>
17+
<tr>
18+
<td>🧠</td>
19+
<td><strong>Advanced Agentic Workflow:</strong> The agent uses Gemini to <strong>strategize</strong> a multi-step plan, <strong>reflect</strong> on findings to identify gaps, and <strong>synthesize</strong> a final, comprehensive report.</td>
20+
</tr>
21+
<tr>
22+
<td>🔄</td>
23+
<td><strong>Iterative & Human-in-the-Loop Research:</strong> Involves the user for plan approval, then autonomously loops through searching (via Gemini function calling) and refining its results until it has gathered sufficient information.</td>
24+
</tr>
25+
</tbody>
26+
</table>
27+
<div style="width: 45%;">
28+
<img src="../../docs/images/adk_gemini_fullstack_preview.png" width="100%" alt="Gemini Fullstack ADK Preview">
29+
</div>
30+
</div>
31+
32+
This project adapts concepts from the [Gemini FullStack LangGraph Quickstart](https://github.com/google-gemini/gemini-fullstack-langgraph-quickstart) for the frontend app.
33+
34+
## 🚀 Getting Started: From Zero to Running Agent in 1 Minute
35+
36+
**Prerequisites:**
37+
38+
* **[Python 3.10+](https://www.python.org/downloads/)**
39+
* **[Node.js and npm](https://nodejs.org/)**
40+
* **[Google Cloud SDK](https://cloud.google.com/sdk/docs/install)**
41+
42+
### Step 1: Create Your Agent Project
43+
44+
45+
This command uses the [Agent Starter Pack](goo.gle/agent-starter-pack) to create a new directory (`my-fullstack-agent`) with all the necessary code.
46+
```bash
47+
# Create and activate a virtual environment
48+
python -m venv .venv && source .venv/bin/activate # On Windows: .venv\Scripts\activate
49+
50+
# Install the starter pack and create your project
51+
pip install agent-starter-pack
52+
agent-starter-pack create my-fullstack-agent -a adk_gemini_fullstack
53+
```
54+
55+
<details>
56+
<summary>⚡️ Alternative: Using uv</summary>
57+
58+
If you have [`uv`](https://github.com/astral-sh/uv) installed, you can create and set up your project with a single command:
59+
60+
```bash
61+
uvx agent-starter-pack create my-fullstack-agent -a adk_gemini_fullstack
62+
```
63+
This command handles creating the project without needing to pre-install the package into a virtual environment.
64+
65+
</details>
66+
67+
You'll be prompted to select a deployment option (Agent Engine or Cloud Run) and verify your Google Cloud credentials.
68+
69+
### Step 2: Install Dependencies & Run the Agent
70+
71+
Now, navigate into your new project, install the dependencies, and start the servers with a single command.
72+
73+
```bash
74+
cd my-fullstack-agent && make install && make dev
75+
```
76+
77+
Your agent should now be running!
78+
* Backend API: `http://localhost:8000`
79+
* Frontend UI: `http://localhost:5173`
80+
81+
## ☁️ Deployment
82+
83+
You can quickly deploy your agent to a **development environment** on Google Cloud. You can deploy your latest code at any time with:
84+
85+
```bash
86+
# Replace YOUR_DEV_PROJECT_ID with your actual Google Cloud Project ID
87+
gcloud config set project YOUR_DEV_PROJECT_ID
88+
make backend
89+
```
90+
91+
For robust, **production-ready deployments** with automated CI/CD, please follow the detailed instructions in the **[Agent Starter Pack Development Guide](https://googlecloudplatform.github.io/agent-starter-pack/guide/development-guide.html#b-production-ready-deployment-with-ci-cd)**.
92+
93+
## How the Agent Thinks: A Two-Phase Workflow
94+
95+
The backend agent, defined in `app/agent.py`, follows a sophisticated workflow to move from a simple topic to a fully-researched report.
96+
97+
The following diagram illustrates the agent's architecture and workflow:
98+
99+
![ADK Gemini Fullstack Architecture](../../docs/images/adk_gemini_fullstack_architecture.png)
100+
101+
This process is broken into two main phases:
102+
103+
### Phase 1: Plan & Refine (Human-in-the-Loop)
104+
105+
This is the collaborative brainstorming phase.
106+
107+
1. **You provide a research topic.**
108+
2. The agent generates a high-level research plan with several key goals (e.g., "Analyze the market impact," "Identify key competitors").
109+
3. The plan is presented to **you**. You can approve it, or chat with the agent to add, remove, or change goals until you're satisfied. Nothing happens without your explicit approval.
110+
111+
### Phase 2: Execute Autonomous Research
112+
113+
Once you approve the plan, the agent's `research_pipeline` takes over and works autonomously.
114+
115+
1. **Outlining:** It first converts the approved plan into a structured report outline (like a table of contents).
116+
2. **Iterative Research & Critique Loop:** For each section of the outline, it repeats a cycle:
117+
* **Search:** It performs web searches to gather information.
118+
* **Critique:** A "critic" model evaluates the findings for gaps or weaknesses.
119+
* **Refine:** If the critique finds weaknesses, the agent generates more specific follow-up questions and searches again. This loop continues until the research meets a high-quality bar.
120+
3. **Compose Final Report:** After the research loop is complete, a final agent takes all the verified findings and writes a polished report, automatically adding inline citations that link back to the original sources.
121+
122+
You can edit key parameters (Gemini models, research loop iterations) in the `ResearchConfiguration` dataclass within `app/config.py`.
123+
124+
## 🔄 Frontend-Backend Integration
125+
126+
The frontend UI integrates with the backend through specific agent names that:
127+
128+
1. **Process agent outputs** - Different outputs are handled in specific ways (research findings vs. final report)
129+
2. **Update the activity timeline** - Each agent's activity appears with appropriate titles and icons
130+
3. **Track research metrics** - Website counts and progress indicators are based on agent activities
131+
132+
Important agent names for frontend functionality:
133+
134+
- `section_researcher` & `enhanced_search_executor`: Track websites consulted
135+
- `report_composer_with_citations`: Processes final report with citations
136+
- `interactive_planner_agent`: Updates AI messages during planning
137+
- Other agents (`plan_generator`, `section_planner`, etc.): Used for timeline labels
138+
139+
If you modify agent names in `app/agent.py`, update the frontend code accordingly to maintain functionality.
140+
141+
## 🛠️ Technologies Used
142+
143+
### Backend
144+
* [**Agent Development Kit (ADK)**](https://github.com/google/adk-python): The core framework for building the stateful, multi-turn agent.
145+
* [**FastAPI**](https://fastapi.tiangolo.com/): High-performance web framework for the backend API.
146+
* [**Google Gemini**](https://cloud.google.com/vertex-ai/generative-ai/docs): Used for planning, reasoning, search query generation, and final synthesis.
147+
148+
### Frontend
149+
* [**React**](https://reactjs.org/) (with [Vite](https://vitejs.dev/)): For building the interactive user interface.
150+
* [**Tailwind CSS**](https://tailwindcss.com/): For utility-first styling.
151+
* [**Shadcn UI**](https://ui.shadcn.com/): A set of beautifully designed, accessible components.

0 commit comments

Comments
 (0)