AI Agent for BigQuery: Let It Query, Not Change

An AI agent for BigQuery in Insulin is an organization agent that reaches your warehouse through a Google Cloud service account, with tools to list datasets and tables, read a table’s schema and run a standard SQL query. Because the query tool runs the SQL the agent writes, what keeps the agent from changing data is the service account’s IAM roles, not its prompt.

---

A data lead wants to ask the warehouse a question in plain English and get the number back. The Google Cloud admin who issues the credentials wants a narrower promise: whatever the agent is asked, it reads and never changes a table.

You can have both, and neither depends on the agent behaving well, because Google checks the service account’s permissions on every query. Here is the setup, from which agents can use the integration to how you take the access away.

What can an AI agent do in BigQuery?

It gets four tools, all running on one service account: list datasets, list tables, read a table’s schema, and run a standard SQL query. Fours’ docs list them, and each is covered by a specific grant in Google Cloud:

Tool	What it does	What covers it in Google Cloud
List datasets (googlebigquery_list_datasets)	Lists the BigQuery datasets in the configured GCP project	BigQuery Data Viewer on each dataset; Google lists only the datasets the caller can access
List tables (googlebigquery_list_tables)	Lists the tables in a dataset	BigQuery Data Viewer on that dataset
Get table schema (googlebigquery_get_table_schema)	Returns a table’s column names, types, descriptions and metadata	BigQuery Data Viewer on that dataset
Run query (googlebigquery_run_query)	Runs a standard SQL query and returns the results	BigQuery Job User on the project, plus BigQuery Data Viewer on every table the query reads

The fourth tool is the one to plan around. It runs the SQL the agent writes, and nothing in its documentation limits it to SELECT. In BigQuery, standard SQL is GoogleSQL, which Google says covers queries but also statements that create and modify datasets and tables, statements that “update, insert, and delete data from your BigQuery tables”, and statements that control access. Fours describes the integration itself as a way to “query and manage data in Google BigQuery.”

So the question is not whether someone will ask the agent to change something, but whether its account is allowed to. A system prompt that says only run SELECT statements is an instruction the model may or may not follow; a permission the service account lacks is a statement BigQuery refuses. Scoping an agent to its integrations decides which systems it can reach at all. Inside BigQuery, the boundary is IAM.

Which Insulin agents can use the BigQuery integration?

Only organization agents. BigQuery is an org-level integration only, and Fours’ docs mark the user-level option “Not applicable”. An agent’s ownership decides which integrations it can use:

Agent	Integrations it uses	Can it query BigQuery?
Organization agent	Organization-level integrations selected for it	Yes, once BigQuery is on its allowlist
Personal agent	User-level integrations selected for it	No: BigQuery has no user-level form
Built-in Insulin assistant	Allowed user-scope integrations for the current user	No

An organization agent is an agent owned by the organization rather than by one person, and only org admins can create one. So the warehouse agent is an admin’s object end to end: an org admin connects the integration, creates or installs the agent and decides who uses it, and only an org admin can edit an organization agent’s integrations.

Two consequences are easy to miss. The built-in assistant can’t answer from BigQuery at all. And installing the catalog’s BigQuery Analyst agent from the Marketplace’s Personal store doesn’t help: that creates a private copy in your own workspace, which uses user-level integrations. The org admin installs it from the Organization store instead.

Which IAM roles keep a BigQuery agent read-only?

BigQuery Data Viewer on each dataset the agent may read, plus BigQuery Job User on the project. Google lists that pair as the roles needed to run a query job, and neither carries a permission to update table data, create or delete a table, create a dataset or change who has access. How it compares with the other roles, in Google’s descriptions:

Role	What Google says it allows	For a query-only agent
BigQuery Data Viewer (roles/bigquery.dataViewer)	On a dataset: list its tables, views and models, read their metadata, query, export and replicate table data, and create snapshots. Google maps it to the dataset’s READER basic role	Grant, on each dataset the agent may read
BigQuery Job User (roles/bigquery.jobUser)	Run jobs, including queries, within the project. It can only be granted on a project, folder or organization	Grant, on the project
BigQuery User (roles/bigquery.user)	On a project: run jobs including queries, enumerate datasets, and create new datasets, with BigQuery Data Owner on each one it creates	Works, but can create datasets; prefer Job User
BigQuery Data Editor (roles/bigquery.dataEditor)	On a dataset: create, update and delete tables and views, and query, export, replicate and update table data	Don’t grant
BigQuery Admin (roles/bigquery.admin)	Manage all resources and all data within the project, and cancel other users’ jobs	Don’t grant

Three details decide whether the setup holds:

• Data Viewer alone can browse but not query. Running a query needs bigquery.jobs.create on the project, which Data Viewer doesn’t include, so an account with only Data Viewer lists and describes tables, then fails its first query with Google’s “does not have bigquery.jobs.create permission” error. Job User supplies it.
• BigQuery User is the alternative Fours’ setup lists. It runs queries too, but Google says it also “allows the creation of new datasets within the project”, and the creator becomes BigQuery Data Owner of each one. An agent that should only answer does not need to create anything.
• Grant Data Viewer on datasets, not on the project. A role granted on the project is inherited by every dataset in it: Data Viewer on the project reads every dataset, while Data Viewer on analytics reads analytics. Inheritance also runs down from the folder and the organization, so one broader role up there reaches every dataset below it.

Data Viewer’s list includes creating snapshots, but a snapshot also needs create and update-data permissions on the dataset that will hold it, which neither role in the pair grants. Fours’ suggested roles include BigQuery Admin too; that suits an integration meant to manage the warehouse, not an agent meant to answer from it.

How do you set up a query-only warehouse agent?

Two admins, eight steps: the GCP admin scopes the service account, then an org admin connects it and builds the agent.

In Google Cloud, the GCP admin:

1. Creates a service account in the GCP project the agent will query.
2. Grants it BigQuery Job User on that project and BigQuery Data Viewer on each dataset the agent may read.
3. Checks that it holds nothing else on the project, its folder or the organization.
4. Creates a JSON key for it and downloads the file.

In Insulin, an org admin:

5. Connects BigQuery as an organization integration under Settings → Organization → Integrations, entering the service account’s email and uploading the JSON key.
6. Creates an agent with Ownership: Organization, or installs BigQuery Analyst from the Marketplace’s Organization store.
7. Puts BigQuery on the agent’s integration allowlist, and nothing the agent doesn’t need.
8. Opens Share and gives the people who need answers the USER role.

Sharing the agent shares the service account’s reach. BigQuery tools use the org-level service account credentials, so everyone who uses the agent queries as that account and can ask about anything it can read. Pick the datasets for the whole audience, and share with named people unless the whole organization may see that data. USER lets them chat with the agent but not change its configuration.

How do you schedule a recurring warehouse report?

Ask for a cron job, and name the warehouse agent in the request. There is no create form: you ask the built-in Insulin assistant in chat, or call the REST API, and the job runs under the agent you name, with that agent’s integrations. A job that names no agent runs under the built-in Insulin agent, which can’t reach BigQuery.

A Monday summary for Acme’s finance team is a cron job on 0 9 * * 1 that asks the warehouse agent for last week’s revenue by region. There is no timezone field, so 09:00 is on the service’s clock; the job’s Next timestamp shows when it lands for you. Scheduling a recurring AI agent job covers the rest of the decisions.

Each run is recorded on the job’s page: Output holds what it produced, and Steps lists every tool call with its arguments and result. For a warehouse report, that is the SQL the agent actually ran, the first place to look when a number seems wrong.

The job and its output are private to whoever creates it. Only a job’s owner can see it, run it, edit it or delete it, organization administrators included, so if a team depends on the report, choose its owner on purpose.

Will an approval card stop a bad query?

Don’t count on it. Insulin pauses some tool calls with a Tool Approval Required card, but the card is offered only in an interactive solo chat in the web workspace, on the main thread. In a channel, a Slack or Microsoft Teams DM or a sub-thread, it isn’t offered and the action isn’t held back, and a cron job is an automated run, not a chat. Where the approval gate is armed maps every surface. A missing permission holds on all of them, because BigQuery checks the service account’s roles wherever the query came from.

How do you remove the agent’s access?

In two places: delete the integration in Insulin, then remove the service account’s permissions in Google Cloud. Deleting the integration revokes access with no recovery window, but Fours’ docs are explicit that you must also remove the service account’s permissions in the GCP console. Do both, so the account has nothing to read even if a copy of its key survives.

If a role won’t come off a dataset, Google notes that the account may hold it from higher in the resource hierarchy, so check the project, its folder and the organization. And because the integration can’t be edited, changing the service account or its key means deleting the integration and creating it again.

Frequently asked questions

Can an AI agent query BigQuery in Insulin?

Yes, if it is an organization agent. BigQuery is an org-level integration on a Google Cloud service account, with four tools: list datasets, list tables, get a table’s schema and run a standard SQL query. Personal agents and the built-in assistant can’t use it.

Which IAM roles does a read-only BigQuery agent need?

BigQuery Data Viewer on each dataset it may read, and BigQuery Job User on the project. Google lists that pair as the roles needed to run a query job. Avoid BigQuery Data Editor and BigQuery Admin, which can change data.

Can’t I just tell the agent to run only SELECT statements?

You can, but that is an instruction, not a permission. The query tool runs the SQL the agent writes, and BigQuery’s SQL includes statements that insert, update and delete data. The service account’s IAM roles decide whether such a statement succeeds.

Why does the agent fail with a bigquery.jobs.create error?

Its service account can read data but not run queries. Running a query needs the bigquery.jobs.create permission on the project, which BigQuery Data Viewer doesn’t include. Grant the account BigQuery Job User on that project.

Who can see a scheduled BigQuery report?

Only the person who created the job. A job is private to its owner, organization administrators included: only the owner can see it, run it, edit it or delete it. Its runs and their output sit on the job’s page.

Who pays for the queries the agent runs?

Your Google Cloud billing account. Each query is a BigQuery job, and Google bills a project’s BigQuery jobs to the billing account attached to it. Under on-demand pricing, you pay for the bytes each query processes.

Takeaways

• BigQuery is an org-level integration only, so the warehouse agent must be an organization agent; personal agents and the built-in assistant can’t use it.
• The query tool runs the SQL the agent writes, so the guard is the service account’s IAM roles, not the prompt.
• Grant BigQuery Data Viewer on the datasets and BigQuery Job User on the project. BigQuery User can also create datasets, and Data Editor and Admin can change data.
• Everyone you share the agent with queries as the service account: choose the datasets for that audience and share as USER.
• A recurring report is a cron job that names the agent, private to whoever creates it, and the approval card is not its guard.
• Removing access takes two steps: delete the integration, then remove the service account’s permissions in Google Cloud.

A warehouse agent is one of many specialists a team can build, scope and schedule. See how Insulin agents for business workflows fit together, or read the BigQuery integration docs before you create the service account.