Building AI Agents with ADK: Data Analyst Agent

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.com account 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:

  1. Open the workshop credit link in an Incognito window and sign in with your personal @gmail.com account.
  2. On the Claim Your Benefit card, click Claim Credit.

Google Builders Hub Claim Your Benefit card showing the Claim Credit button.

  1. Optional: If you see a prompt to create a Google Developer Program profile, complete the form.
  2. 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.
  3. Confirm that the Successfully claimed your event credit! message appears, and then click Open Billing Account.

Google Builders Hub confirmation card showing Successfully claimed your event credit and the Open Billing Account button.

🔍 Check your work

Billing account provisioning can take up to five minutes. To confirm that your credit is active, complete the following steps:

  1. 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
  1. Click the Your billing accounts tab and refresh the page until an account containing GDP Credit shows Active in the Status column.

Google Cloud Billing account management page showing an active GDP Credit billing account.

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:

  1. Open Create a project (or copy the URL into your Incognito window):
https://console.cloud.google.com/projectcreate
  1. 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).
  2. Note the generated Project ID, and then click Create.

Create a Google Cloud Project form showing Project name, generated Project ID, Parent resource, and the Create button.

🔍 Check your work

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

Google Cloud console Notifications menu showing Create Project and the Select Project link.

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

  1. Open Google Cloud Shell (or copy the URL into your Incognito window):
https://shell.cloud.google.com/?show=ide,terminal
  1. If a popup asks for authorization, click Authorize:

Authorize Cloud Shell dialog

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:

Cloud Shell terminal showing selected Project ID highlighted in yellow

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

  1. Create the project directory and navigate into it:
mkdir -p ~/ai-agents-adk && cd ~/ai-agents-adk
  1. 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:

Cloud Shell terminal showing the active virtual environment prefix

  1. Clear any stale package cache and install google-adk:
rm -rf ~/.cache
uv pip install google-adk --no-cache
  1. 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 2 to select gemini-3.8-flash and press Enter.
  • Choose a backend: Type 2 to select Agent Platform (displayed in the CLI menu as Vertex 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 serve gemini-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:

  1. Download the file about Google's Health Care Strategy.
  2. Click the upload file button in your agent's UI and select the file you just downloaded.
  3. In the chat interface, ask the agent to summarize the file: "Give me a summary of this file"
  4. Press enter.

You should receive a concise summary of the document's contents.

ADK Web UI displaying a summary of the uploaded healthcare PDF document

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.

  1. In the Cloud Shell terminal, press Ctrl+C to stop the web server.
  2. Open the data_analyst_agent/agent.py file in the Cloud Shell Editor by executing this command:
cloudshell edit data_analyst_agent/agent.py
  1. Modify the file to import and add the google_search tool:
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
    ]
)
  1. 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"
  1. In the agent UI, re-upload the GoogleHealthStrategy.pdf file.
  2. 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.

  1. In the Cloud Shell terminal, press Ctrl+C to stop the web server.
  2. Open the data_analyst_agent/agent.py file in the Cloud Shell Editor by executing this command in the terminal:
cloudshell edit data_analyst_agent/agent.py
  1. 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
    ],
)
  1. 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"
  1. 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.

ADK Web UI listing tables inside the cms_medicare BigQuery dataset

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:

ADK Web UI running an analytical query with the user Project ID

Here are some example analytical prompts that you can try:

  • Using the inpatient_charges_2015 table, 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: