Google BigQuery

GoogleBigQueryTools enable an Agent to run SQL queries and analyze large-scale datasets in Google BigQuery.

Prerequisites

The following example requires the google-cloud-bigquery and openai libraries.

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

Set your Google Cloud project and location. Both are required, either as parameters or environment variables.

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

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

Set OpenAI Key

Set your OPENAI_API_KEY as an environment variable. You can get one from OpenAI.

export OPENAI_API_KEY=sk-***

Enable the BigQuery API in your project and configure Application Default Credentials. For local development with the Google Cloud CLI:

gcloud auth application-default login

Use a principal with access to the dataset and permission to run queries. Replace your_dataset_name with an existing dataset and sales in the prompt with an existing table. The location must match your dataset.

Example

The following agent can query and analyze BigQuery datasets:

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

agent = Agent(
    instructions=[
        "You are a data analyst assistant that helps with BigQuery operations",
        "Execute SQL queries to analyze large datasets",
        "Provide insights and summaries of query results",
        "Help with data exploration and table analysis",
    ],
    tools=[GoogleBigQueryTools(dataset="your_dataset_name")],
)

agent.print_response("List all tables in the dataset and describe the sales table", stream=True)

Toolkit Params

Parameter	Type	Default	Description
`dataset`	`str`	-	BigQuery dataset name (required).
`project`	`Optional[str]`	`None`	Google Cloud project ID. Falls back to GOOGLE_CLOUD_PROJECT. One of the two must be set.
`location`	`Optional[str]`	`None`	BigQuery location. Falls back to GOOGLE_CLOUD_LOCATION. One of the two must be set.
`credentials`	`Optional[Any]`	`None`	Google Cloud credentials object.
`list_tables`	`bool`	`True`	Enable table listing functionality.
`describe_table`	`bool`	`True`	Enable table description functionality.
`run_sql_query`	`bool`	`True`	Enable SQL query execution functionality.
`all`	`bool`	`False`	Enables all functionality when set to True.

Toolkit Functions

Function	Description
`list_tables`	List all tables in the specified BigQuery dataset.
`describe_table`	Get detailed schema information about a specific table.
`run_sql_query`	Execute SQL queries on BigQuery datasets.