Skip to main content

​
Overview

Google BigQuery is the primary data source supported by Interact. Once connected, your agents can query any BigQuery table in the datasets you choose to expose. What you’ll need:
  • A Google Cloud project with BigQuery enabled
  • A service account with the correct IAM roles (detailed below)
  • The service account’s JSON key file

​
Step 1: Create a service account

1

Open Google Cloud IAM

Go to console.cloud.google.com and navigate to IAM & Admin → Service Accounts.
2

Create a new service account

Click Create Service Account, give it a name (e.g. interact-reader), and click Create and Continue.
3

Assign the required roles

Add the following two roles:
RolePurpose
BigQuery Data ViewerAllows reading table data
BigQuery Job UserAllows running query jobs
Click Continue, then Done.
4

Create and download a JSON key

Click on your new service account, go to the Keys tab, click Add Key → Create new key, and choose JSON. Save the downloaded file — you’ll need it in the next step.
Treat this JSON file like a password. Don’t share it or commit it to version control.

​
Step 2: Connect BigQuery in Interact

1

Open Connectors

In Interact, go to Settings → Connectors and click Add connector.
2

Select Google BigQuery

Choose Google BigQuery from the list of available connectors.
3

Enter your project ID

Type in your Google Cloud Project ID (visible in the Google Cloud Console header).
4

Paste your service account credentials

Open the JSON key file you downloaded, copy the full contents, and paste it into the Service account credentials field.
5

Select datasets to expose

Interact will connect to BigQuery and list all available datasets in your project. Select the datasets you want your agents to be able to query.
You can also expand a dataset and select specific tables. This is useful if a dataset contains sensitive tables you don’t want agents to access.
6

Set a query cost limit (optional but recommended)

Enter a maximum cost per query in USD. Interact will estimate each query’s cost before running it and block any query that would exceed this limit, protecting you from unexpected BigQuery charges.
7

Save the connector

Click Save connector. Interact will verify the connection using your credentials.

​
Step 3: Attach the connector to an agent

Once the connector is saved, you can use it in any agent:
  1. Open an agent (or create a new one)
  2. In the Subagents section, add or edit a Database Query Agent
  3. Select your BigQuery connector from the dropdown
The agent can now query the datasets you’ve whitelisted.

​
Permissions reference

IAM RoleWhy it’s needed
roles/bigquery.dataViewerRead access to table data
roles/bigquery.jobUserPermission to create and run query jobs
You do not need bigquery.dataEditor, bigquery.admin, or any write-level permission. Interact is read-only.

​
Troubleshooting

Double-check that:
  • The Project ID is correct (no typos, no spaces)
  • The service account has both BigQuery Data Viewer and BigQuery Job User roles
  • The JSON key file is complete and unmodified
The table’s dataset may not be whitelisted. Go to Settings → Connectors, edit the connector, and check that the relevant dataset (or table) is selected.
The query the agent generated exceeded your configured cost limit. You can either:
  • Raise the cost limit in the connector settings
  • Ask the agent to query a smaller date range or fewer columns
Ensure the service account has been granted roles at the project level, or alternatively at the specific dataset level for each dataset you want to expose.