1. Overview
Extracting insights from enterprise data often requires writing SQL and stitching together unstructured files, web research, and warehouse tables by hand. AI agents act as a natural-language interface over your data, translating business questions into grounded queries and summaries in seconds.
In this hands-on codelab (part of the Building AI Agents with ADK series), you build a Data Analyst Agent with the Agent Development Kit (ADK) that analyzes uploaded PDF documents, combines document findings with live Google Search results, and queries the public Medicare Utilization dataset in Google Cloud BigQuery through BigQueryToolset. You can also access this codelab at goo.gle/adk-data-analyst.
Prerequisites
- A foundational understanding of Generative AI concepts
- Basic proficiency in Python programming and comfort using the command line
- Familiarity with the concepts from the previous codelabs in this series: The Foundation and Empowering with Tools
What you'll learn
- How to build a functional Data Analyst Agent using the ADK framework
- Methods for enabling an agent to analyze data from uploaded documents
- How to connect your agent to a BigQuery database for enterprise-level data analysis
- Techniques for defining your agent's core logic, including its purpose and instructions
What you'll need
- A Google account (use a personal
@gmail.comaccount if claiming workshop credits) - A workshop credit link from your instructor (plus a phone camera to scan the QR code) or an active Cloud Billing account
- Google Chrome (an Incognito window is recommended to avoid mixing personal and work accounts)
2. Claim Google Cloud credits (Optional)
If you're completing this codelab on your own and are eligible, use the Google Developer Program credits banner on this page to claim credits without a credit card. If you're attending a workshop with an event credit link from your instructor, follow the event credit steps in this section.
Claim your event credit
You claim workshop event credits through Google Builders Hub (part of the Google Developer Program).
To claim your event credit, follow these steps:
- Open the workshop credit link in an Incognito window and sign in with your personal
@gmail.comaccount. - On the Claim Your Benefit card, click Claim Credit.

- Optional: If you see a prompt to create a Google Developer Program profile, complete the form.
- When the Scan to Verify You're Human dialog appears, scan the QR code with your phone and complete verification. If the QR code doesn't appear, refresh the page and click Claim Credit again.
- Confirm that the Successfully claimed your event credit! message appears, and then click Open Billing Account.

🔍 Check your work
Billing account provisioning can take up to five minutes. To confirm that your credit is active, complete the following steps:
- If the Billing account management page isn't already open, open Google Cloud Billing (or copy the URL into your Incognito window):
https://console.cloud.google.com/billing
- Click the Your billing accounts tab and refresh the page until an account containing GDP Credit shows Active in the Status column.

3. Create a Google Cloud project (Optional)
Create a dedicated Google Cloud project to keep all resources from this codelab isolated so you can remove them cleanly when you finish.
To create a Google Cloud project, follow these steps:
- Open Create a project (or copy the URL into your Incognito window):
https://console.cloud.google.com/projectcreate
- Enter your project details:
- Project name: Enter a descriptive name, such as
google-cloud-workshop. - Billing account (if shown): Select your GDP Credit account (or your active billing account).
- Parent resource: Leave No organization selected (or select your organization if required).
- Project name: Enter a descriptive name, such as
- Note the generated Project ID, and then click Create.

🔍 Check your work
After project creation finishes, open Notifications on the Google Cloud console toolbar, and then click Select Project.

4. Set up your environment
Configure Google Cloud Shell, enable the Agent Platform and BigQuery APIs, and create an isolated Python 3.12 virtual environment with uv.
Launch Cloud Shell
- Open Google Cloud Shell (or copy the URL into your Incognito window):
https://shell.cloud.google.com/?show=ide,terminal
- If a popup asks for authorization, click Authorize:

Set your Project ID
Select your active Google Cloud Project ID from the numbered menu in the Cloud Shell terminal:
unset CLOUDSDK_CORE_PROJECT
PS3="Select your project (e.g. 1): "
select PROJECT_ID in $(gcloud projects list --format="value(projectId)"); do
[ -n "$PROJECT_ID" ] && gcloud config set project "$PROJECT_ID" && break
done
Verify that your selected Project ID is highlighted in yellow in the Cloud Shell terminal prompt:

Enable required APIs
Run the following command in the Cloud Shell terminal to enable the Agent Platform and BigQuery APIs:
gcloud services enable \
aiplatform.googleapis.com \
bigquery.googleapis.com
When the operation finishes, Operation/... finished successfully is printed in your terminal.
Create a Python virtual environment and install ADK
- Create the project directory and navigate into it:
mkdir -p ~/ai-agents-adk && cd ~/ai-agents-adk
- Create and activate a Python 3.12 virtual environment:
uv venv --python 3.12
source .venv/bin/activate
Confirm (ai-agents-adk) prefixes your terminal prompt, indicating the virtual environment is active:

- Clear any stale package cache and install
google-adk:
rm -rf ~/.cache
uv pip install google-adk --no-cache
- Open the folder as your Cloud Shell workspace:
cd ~ && cloudshell workspace ai-agents-adk
5. Create a starter agent
With your environment ready, create your AI agent using the ADK CLI.
Create an agent
In your terminal (re-activate source ~/ai-agents-adk/.venv/bin/activate if Cloud Shell reloaded), run the following command:
adk create data_analyst_agent
Configure your agent
You will be prompted to configure your agent (if prompted with Enable telemetry? [Y/n]: on first run, press Enter or type n and press Enter). Make the following selections:
- Choose a model for the root agent: Type
2to selectgemini-3.8-flashand press Enter. - Choose a backend: Type
2to select Agent Platform (displayed in the CLI menu asVertex AI) and press Enter. - Enter Google Cloud project ID: Press Enter to confirm your detected Project ID.
- Enter Google Cloud region: Type
global(required to servegemini-3.8-flash) and press Enter.
Start the development web server
Once the agent is created, start the development web server by running the following command:
adk web --allow_origins "regex:https://.*\.cloudshell\.dev"
You can either Ctrl + Click or Cmd + Click on the link (i.e., http://localhost:8000) in the terminal or you can:
- Click the Web Preview button
- Select Change Port
- Enter the port number (e.g., 8000)
- Click Change and Preview
You'll then see the chat application-like UI appear in your browser.
Chat with your agent
Go ahead and chat with your agent through this interface! Say something like "hello, what can you do?".
6. Analyse Data From a Document
In this section, you will upload a document to the agent and ask questions about its content.
Summarize the document
Follow these steps to get a summary of the document:
- Download the file about Google's Health Care Strategy.
- Click the upload file button in your agent's UI and select the file you just downloaded.
- In the chat interface, ask the agent to summarize the file: "Give me a summary of this file"
- Press enter.
You should receive a concise summary of the document's contents.

Ask more detailed questions
Now, try asking more detailed questions to dig deeper into the document:
- What are the primary diseases Google is currently targeting with its AI and data initiatives?
- How is Google planning to improve healthcare data interoperability and break down data silos?
- How is Google Cloud being utilized to support healthcare businesses and researchers?
- What new disease areas is Google potentially exploring next (e.g., COPD, cancer, mental health)?
Ask follow up questions
You can also ask follow up questions like finding out the page reference number for further investigation:
- Where did you see information about diabetic related information?
- Direct me to the relevant pages about diseases.
- Where are the interesting charts that I should take a look at?
Challenge: Find a document of your own that you want the agent to analyze and upload it. Ask the agent questions about its content.
7. Combine documents with live web search
The agent is now an expert on the document, but a powerful analyst also needs access to current, external information. Let's give our agent the ability to search the web.
- In the Cloud Shell terminal, press Ctrl+C to stop the web server.
- Open the
data_analyst_agent/agent.pyfile in the Cloud Shell Editor by executing this command:
cloudshell edit data_analyst_agent/agent.py
- Modify the file to import and add the
google_searchtool:
from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
root_agent = Agent(
model='gemini-3.8-flash',
name='root_agent',
description='A helpful assistant for user questions.',
instruction="""
First, check the uploaded files for an answer.
If the information is not in the files, use your tools to search the web.
Answer user questions to the best of your ability.
""",
tools=[
google_search
]
)
- Save the file and restart the web server in your terminal by typing the following command in the terminal:
adk web --allow_origins "regex:https://.*\.cloudshell\.dev"
- In the agent UI, re-upload the
GoogleHealthStrategy.pdffile. - Now, ask a question that requires both the document's context and external information:
The document discusses Google's strategy in healthcare. What are three other major tech companies that are also investing heavily in healthcare AI, and what are their primary focus areas?
The agent will now synthesize information from both the document and a live Google search to give you a comprehensive answer. You can try asking a few questions:
- The document mentions using AI for diabetic retinopathy. What are some of the latest FDA-approved technologies in this area that have been announced in the last year?
- The file mentions partnerships. Can you find any recent news articles or press releases about Google's latest collaborations in the healthcare sector?
Challenge: Try asking similar questions to a document of your own. Something that makes use of a local document and the results from the internet.
8. Analyze healthcare data with BigQuery
Uploading individual documents isn't scalable. In a real-world scenario, data resides in enterprise systems like Google Cloud BigQuery.
Currently, developers building agentic applications often have to build and maintain their own custom tools. This manual process is slow, risky, and creates significant overhead. It forces the developers to handle everything from authentication to error handling instead of focusing on innovation.
The Agent Development Kit (ADK) includes first-party tools for BigQuery interaction. For this particular analysis, you will use the publicly available Medicare Utilization dataset provided by the Centers for Medicare & Medicaid Services (CMS).
First, let's connect our agent to a massive public healthcare dataset.
- In the Cloud Shell terminal, press Ctrl+C to stop the web server.
- Open the
data_analyst_agent/agent.pyfile in the Cloud Shell Editor by executing this command in the terminal:
cloudshell edit data_analyst_agent/agent.py
- Replace the entire content of the file with the following code to configure
BigQueryToolset:
import google.auth
from google.adk.agents.llm_agent import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool
from google.adk.tools.bigquery import (
BigQueryToolset,
BigQueryCredentialsConfig
)
from google.adk.tools.bigquery.config import (
BigQueryToolConfig,
WriteMode
)
# Automatically get credentials from the gcloud environment
application_default_credentials, _ = google.auth.default()
credentials_config = BigQueryCredentialsConfig(
credentials=application_default_credentials
)
# Configure the BigQuery tool
tool_config = BigQueryToolConfig(
write_mode=WriteMode.ALLOWED,
application_name='data_analyst_agent'
)
# Create the toolset with the specified configurations
bigquery_toolset = BigQueryToolset(
credentials_config=credentials_config, bigquery_tool_config=tool_config
)
# Create an agent with google search tool as a search specialist
google_search_agent = Agent(
model='gemini-3.8-flash',
name='google_search_agent',
description='A search agent that uses google search to get latest information about current events, weather, or business hours.',
instruction='Use google search to answer user questions about real-time, logistical information.',
tools=[google_search],
)
# Define the final agent with its instructions and tools
root_agent = Agent(
model="gemini-3.8-flash",
name="bigquery_agent",
description=(
"Agent to answer questions about BigQuery data and execute SQL queries."
),
instruction="""
You are an expert data analyst agent with access to BigQuery tools.
When a user asks about a dataset, first use your tools to understand its schema.
Then, use this knowledge to construct and execute SQL queries to answer the user's questions.
Always confirm with the user if their question is ambiguous (e.g., for which year?).
""",
tools=[
AgentTool(google_search_agent),
bigquery_toolset
],
)
- Save the file and restart the web server in your terminal by typing the following command in the terminal:
adk web --allow_origins "regex:https://.*\.cloudshell\.dev"
- Now, you can ask your agent to analyze the public Medicare dataset. Start by exploring the data:
Look into the cms_medicare dataset in the bigquery-public-data project. What can you tell me about it?
The agent will use its tools to inspect the dataset and provide a list of available tables. From there, you can drill down with specific analytical questions. The agent may ask clarifying questions to ensure its queries are accurate.

For some questions, you will need to provide the Project ID to the agent so that it can use it to create a query. For example:

Here are some example analytical prompts that you can try:
- Using the
inpatient_charges_2015table, what are the top 5 procedures (DRG definitions) by total number of discharges? - What is the average total payment for ‘MAJOR JOINT REPLACEMENT' in California (CA)?
- Which state has the highest average covered charges for that same procedure?
That concludes this codelab. You have only scratched the surface of what you can achieve with data agents powered by enterprise data systems. Please feel free to ask any questions you might have about the cms_medicare dataset to your agent.
Challenge: Find another public dataset in BigQuery and use your agent to explore it. You can also create your own dataset with your own data and analyze it privately.
9. Clean up (Optional)
To avoid incurring future charges, you can delete the resources used in this codelab.
Stop the agent
In the Cloud Shell terminal, press Ctrl+C to stop the adk web process.
Delete project files
To remove the agent code from your Cloud Shell environment, run the following command in the terminal:
cd ~ && rm -rf ~/ai-agents-adk
Disable APIs
To disable the APIs you enabled earlier, run the following command in the terminal:
gcloud services disable \
aiplatform.googleapis.com \
bigquery.googleapis.com
Shut down the project
If you created a dedicated Google Cloud project solely for this codelab, follow the shutting down projects guide (or run gcloud projects delete "$(gcloud config get-value project)" --quiet).
10. Congratulations
Congratulations! You've built a Data Analyst Agent using the Agent Development Kit (ADK) framework capable of analyzing uploaded documents, searching the web, and querying enterprise BigQuery datasets.
To continue your learning journey, explore these resources:
- Read the official blog post: Announcing the BigQuery Toolset for AI Agents
- Explore the documentation: Visit the official Agent Development Kit (ADK) documentation for new features and advanced guides.
- Browse the code: Check out the ADK GitHub repository.
- Discover more data: Explore the Google Cloud Public Datasets catalog.