Google BigQuery Tools

google_bigquery_tools.py

"""
You can set the following environment variables for your Google Cloud project:

export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="your-location"

Or you can set the following parameters in the BQTools class:

BQTools(
    project="<your-project-id>",
    location="<your-location>",
    dataset="<your-dataset>",
)

NOTE: Instruct the agent to prepend the table name with the project name and dataset name
Describe the table schemas in instructions and use thinking tools for better responses.
"""

from agno.agent import Agent
from agno.models.google import Gemini
from agno.tools.google.bigquery import GoogleBigQueryTools

# ---------------------------------------------------------------------------
# Create Agent
# ---------------------------------------------------------------------------


agent = Agent(
    instructions=[
        "You are an expert Big query Writer",
        "Always prepend the table name with your_project_id.your_dataset_name when run_sql tool is invoked",
    ],
    tools=[GoogleBigQueryTools(dataset="test_dataset")],
    model=Gemini(id="gemini-3.5-flash", vertexai=True),
)

# ---------------------------------------------------------------------------
# Run Agent
# ---------------------------------------------------------------------------
if __name__ == "__main__":
    agent.print_response(
        "List the tables in the dataset. Tell me about contents of one of the tables",
        markdown=True,
    )

Replace test_dataset and the placeholder project/dataset in the instructions with an existing dataset you can query. The actual class is GoogleBigQueryTools, and the SQL tool is run_sql_query; the BQTools and run_sql names in the source comments are stale.

Enable BigQuery and Vertex AI in your project and provide Application Default Credentials with access to both the dataset and model. run_sql_query is enabled by default and executes the submitted SQL; use run_sql_query=False if you only need table names and column metadata. describe_table returns column names and a description, not full column types.

Run the Example

Set up your virtual environment

uv venv --python 3.12
source .venv/bin/activate

Install dependencies

uv pip install -U agno google-cloud-bigquery google-genai

Export environment variables

export GOOGLE_CLOUD_LOCATION="your_google_cloud_location_here"
export GOOGLE_CLOUD_PROJECT="your_google_cloud_project_here"

Authenticate with Google Cloud

gcloud auth application-default login

Run the example

Save the code above as google_bigquery_tools.py, then run:

python google_bigquery_tools.py

Full source: cookbook/91_tools/google_bigquery_tools.py