[BigQuery Data Agents](/about/bigquery-data-agents) November 3, 2026 # BigQuery agents in your code: the API, ADK, and MCP Create and query BigQuery data agents from Python with the Conversational Analytics API, give an ADK agent BigQuery tools, and connect assistants over MCP. ![](/images/65d75b0ae8d69ef95785a5d6_david-pombar.webp) **[David Pombar](/authors-guides/david-pombar)** Swiss army knife at Trackingplan 7 min read · 1518 words So far every agent in this series lived in the BigQuery console. Your users don’t. They live in Slack, in a product, in Claude or ChatGPT, in a notebook. This guide covers the three ways to take BigQuery agents there: the Conversational Analytics API, for your own code; the Agent Development Kit (ADK), for agents you build; and MCP, for assistants you already use. They are not interchangeable, and the difference is the same one this series keeps coming back to: how much of your context travels with the connection. ![A round multi-pin connector socket mounted on a metal panel with screws around it](/images/bigquery-agents-api-adk-mcp-plugs.jpg) A connector carries whatever is behind it, and nothing more. Image: Syced, Wikimedia Commons, CC0 **Goal of this guide:** call your data agent from Python, give an ADK agent BigQuery tools, and connect an assistant over MCP, knowing what each one carries. ** You need:** the agent from guides [5](/guides/create-a-bigquery-data-agent) to [8](/guides/evaluate-a-bigquery-data-agent), Python, and the Google Cloud CLI. ## Three ways in, compared ![Diagram comparing three ways to reach BigQuery from outside the console: the Conversational Analytics API calls your data agent with all its context, an ADK agent uses BigQuery tools with its own instructions, and an MCP client gets tables and SQL without your agent’s context.](/images/bigquery-agents-api-adk-mcp-three-ways.webp) The further right, the less of your agent’s context comes along. | | Conversational Analytics API | ADK with BigQuery tools | MCP | | --- | --- | --- | --- | | What you get | Your data agent, with its context | Tools for an agent you write | Tables and SQL for any MCP client | | Your instructions, glossary, verified queries | Yes | Only what you put in the ADK agent | No | | Best for | Answers inside your product or workflow | Custom multi-step agents | Exploration from Claude, ChatGPT, Gemini | ## The Conversational Analytics API The [Conversational Analytics API](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/overview) (`geminidataanalytics.googleapis.com`) is what the BigQuery Agents page uses underneath. It works with BigQuery, Looker, Data Studio, and several databases, and Google provides a Python client and a Node.js client. The flow has two clients: one to manage agents, one to chat. This sketch follows Google’s [SDK page](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-sdk), which links a complete notebook; check it for the current version, since the Python client is still `v1beta`. ```python from google.cloud import geminidataanalytics PROJECT = "your-project" PARENT = f"projects/{PROJECT}/locations/global" agents = geminidataanalytics.DataAgentServiceClient() chat = geminidataanalytics.DataChatServiceClient() # 1. The sources and context of the agent tables = [] for table_id in ["sessions", "purchases", "purchase_items", "page_views"]: ref = geminidataanalytics.BigQueryTableReference() ref.project_id, ref.dataset_id, ref.table_id = PROJECT, "agent_layer", table_id tables.append(ref) context = geminidataanalytics.Context() context.system_instruction = open("instructions.yaml").read() context.datasource_references.bq.table_references = tables agent = geminidataanalytics.DataAgent() agent.data_analytics_agent.published_context = context agents.create_data_agent_sync(request=geminidataanalytics.CreateDataAgentRequest( parent=PARENT, data_agent_id="ga4-store", data_agent=agent)) ``` Then open a conversation and stream an answer: ```python conversation = geminidataanalytics.Conversation() conversation.agents = [f"{PARENT}/dataAgents/ga4-store"] conversation = chat.create_conversation(request=geminidataanalytics.CreateConversationRequest( parent=PARENT, conversation_id="weekly-review", conversation=conversation)) message = geminidataanalytics.Message() message.user_message.text = "Revenue by channel in January 2021" request = geminidataanalytics.ChatRequest(parent=PARENT, messages=[message]) request.conversation_reference.conversation = conversation.name request.conversation_reference.data_agent_context.data_agent = f"{PARENT}/dataAgents/ga4-store" for chunk in chat.chat(request=request, timeout=300): print(chunk) ``` Three things to know before you build on it: - **Stateful or stateless.** A conversation keeps history and context between questions, and Google recommends it. A stateless call sends the context with each request and keeps no history; it suits single questions. - **Context as code.** The `system_instruction` is a YAML string where you can write tables, relationships, glossary terms, and descriptions. Keep it in version control and rerun your tests from [guide 8](/guides/evaluate-a-bigquery-data-agent) on every change, ideally in CI. - **Limits.** The chat method has its own quota, lower than the rest of the API; check the [quotas page](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/quotas) before you put it behind a busy product. You can cap bytes per query with `big_query_max_billed_bytes`. ## The ADK: BigQuery tools for your own agent The [Agent Development Kit](https://adk.dev/integrations/bigquery/) is Google’s framework for building agents in Python. Its BigQuery integration gives an agent a toolset: list datasets and tables, read their metadata, run SQL, forecast, analyze contributions, detect anomalies, search the catalog, and `ask_data_insights`, which answers a question in natural language over tables. ```python import google.auth from google.adk.agents import Agent from google.adk.integrations.bigquery import BigQueryToolset, BigQueryCredentialsConfig from google.adk.integrations.bigquery.config import BigQueryToolConfig, WriteMode credentials, _ = google.auth.default() bigquery = BigQueryToolset( credentials_config=BigQueryCredentialsConfig(credentials=credentials), bigquery_tool_config=BigQueryToolConfig(write_mode=WriteMode.BLOCKED), ) analyst = Agent( name="ga4_analyst", model=MODEL, # a current Gemini model instruction=open("instructions.md").read(), tools=[bigquery], ) ``` `WriteMode.BLOCKED` keeps the agent from writing anything. Note what this agent has: the tools, and the instructions you gave it in code. It doesn’t have your data agent’s glossary or verified queries unless you write them into the instruction, or call your data agent as a tool through the API, which is what the ADK tools for Conversational Analytics are for. ## MCP: BigQuery in Claude, ChatGPT, and Gemini The Model Context Protocol lets an assistant you already use call tools on a server. BigQuery has two MCP servers. **The remote server, run by Google.** The endpoint is `https://bigquery.googleapis.com/mcp`, over Streamable HTTP, with OAuth 2.0 and IAM ([setup](https://docs.cloud.google.com/bigquery/docs/use-bigquery-mcp)). In your client, add a remote MCP server with that URL and sign in with Google. Its tools list datasets and tables, read their metadata, and run SQL. The identity needs MCP Tool User (`roles/mcp.toolUser`), BigQuery Job User, and BigQuery Data Viewer. Results are capped at 3,000 rows, and queries time out after three minutes by default. **MCP Toolbox for Databases, run by you.** An [open-source server](https://github.com/googleapis/genai-toolbox) with prebuilt BigQuery tools, which Google documents as the local option ([setup](https://docs.cloud.google.com/bigquery/docs/pre-built-tools-with-mcp-toolbox)). Set `BIGQUERY_PROJECT` and run it over stdio: ```json { "mcpServers": { "bigquery": { "command": "./PATH/TO/toolbox", "args": ["--prebuilt", "bigquery", "--stdio"], "env": { "BIGQUERY_PROJECT": "your-project" } } } } ``` Its tools add forecasting, contribution analysis, catalog search, and `ask_data_insights` to the basics, and Google lists conversational analytics tools among those it wraps. **Make it read-only.** Use a separate identity for the assistant, as Google recommends, with read roles only. Prefer the `execute_sql_readonly` tool, which rejects DML and DDL, and block `execute_sql` with an IAM deny policy if you don’t need it. > **How a production agent does it.** MCP is a channel, not an agent. Connect a general-purpose assistant to analytics data through an MCP server and it sees the numbers, with none of the context that makes them right. Trackingplan ships an MCP too, but behind its Ask Trackingplan tool in Claude, ChatGPT, or Cursor is the whole agent: its data, its context, and its standard of evidence ([how it works](/blog/same-models-different-answers)). The same design works for BigQuery: expose your tested data agent as the tool, rather than raw SQL access, and the assistant inherits everything you built in guides 4 to 8. ## Which one to use - **A question answered inside your product, Slack bot, or workflow:** the Conversational Analytics API, calling your published data agent. - **An agent that does more than answer, such as a weekly report that queries, checks, and writes a summary:** the ADK, with your instructions and, ideally, your data agent as one of its tools. - **Exploration by an analyst in their own assistant:** MCP, read-only, knowing it skips your agent’s context. ## Exercise Create your agent through the API from a YAML file in a repository, ask it the five questions from guide 5, and compare the answers with the console agent. Then connect an MCP client to BigQuery with a read-only identity, ask the same five questions, and write down which ones it got wrong that your agent got right. ## How to know you got it right - Your agent’s context lives in a file under version control. - You can open a conversation and stream an answer from Python. - Your MCP connection can’t write, and you have checked that it can’t. - You can say what context each of the three ways carries. ## Resources - [Conversational Analytics API overview](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/overview) and [build an agent with the Python SDK](https://docs.cloud.google.com/gemini/data-agents/conversational-analytics-api/build-agent-sdk), Google Cloud docs. - [Introduction to the Conversational Analytics API](https://codelabs.developers.google.com/ca-api-bigquery), Google Codelabs: the API end to end with the Python SDK, including streamed answers with charts. - [Chat With Your Data using BigQuery Agents & Antigravity IDE](https://codelabs.developers.google.com/data-agents-in-agy-and-bq), Google Codelabs: data agents from an IDE. - [BigQuery in the ADK](https://adk.dev/integrations/bigquery/), ADK docs, and [Using GCP Conversational Analytics from ADK tools](https://medium.com/@kolban1/using-gcp-conversational-analytics-bigquery-from-adk-tools-afad3b2e2da5), Neil Kolban: calling a data agent as a tool. - [Use the BigQuery MCP server](https://docs.cloud.google.com/bigquery/docs/use-bigquery-mcp) and [MCP Toolbox for Databases](https://github.com/googleapis/genai-toolbox). ## FAQ **What is the Conversational Analytics API?** Google Cloud’s API for building data agents and chatting with them from your own code. It covers BigQuery, Looker, Data Studio, and several databases. With it you create an agent with its sources and context, open conversations, and stream answers into your own application. **Is there an MCP server for BigQuery?** Yes, two. Google runs a remote BigQuery MCP server at [https://bigquery.googleapis.com/mcp](https://bigquery.googleapis.com/mcp), with OAuth and IAM, and tools to list datasets and tables and run SQL. MCP Toolbox for Databases is an open-source server you run locally, with prebuilt BigQuery tools that include forecasting and conversational analytics. **Should I connect Claude or ChatGPT to BigQuery over MCP, or build a data agent?** MCP gives an assistant access to the tables, not the context you built: descriptions it reads, but not your instructions, glossary, verified queries, or tests. For one-off exploration, MCP is enough. For answers a team relies on, call your data agent, from the API or through a tool that wraps it. **How do I make an MCP connection to BigQuery read-only?** Give the identity only BigQuery Data Viewer and Job User, and use the execute\_sql\_readonly tool, which rejects DML and DDL. You can also block the write-capable execute\_sql tool with an IAM deny policy. Google recommends a separate identity for agents. **Next:** [Run it in production: cost, access, and data you can trust](/guides/bigquery-data-agents-in-production). Part of[BigQuery data agents: a guide series from zero to expert](/guides/bigquery-data-agents) On this page 1. [*01*Three ways in, compared](#three-ways-in-compared) 2. [*02*The Conversational Analytics API](#the-conversational-analytics-api) 3. [*03*The ADK: BigQuery tools for your own agent](#the-adk-bigquery-tools-for-your-own-agent) 4. [*04*MCP: BigQuery in Claude, ChatGPT, and Gemini](#mcp-bigquery-in-claude-chatgpt-and-gemini) 5. [*05*Which one to use](#which-one-to-use) 6. [*06*Exercise](#exercise) 7. [*07*How to know you got it right](#how-to-know-you-got-it-right) 8. [*08*Resources](#resources) 9. [*09*FAQ](#faq) **Stop babysitting tags** Trackingplan audits your real user data around the clock and flags issues before they cost you. [Start free trial →](https://app.trackingplan.com/signup) ![](/images/65d75b0ae8d69ef95785a5d6_david-pombar.webp) **David Pombar** Swiss army knife at Trackingplan Read more from David, a Senior Product Strategist with 18+ years in digital product development and an atypical error detection knack. Share Copy link [LinkedIn](https://www.linkedin.com/sharing/share-offsite/?url=https%3A%2F%2Fwww.trackingplan.com%2Fguides%2Fbigquery-agents-api-adk-mcp) [X](https://twitter.com/intent/tweet?url=https%3A%2F%2Fwww.trackingplan.com%2Fguides%2Fbigquery-agents-api-adk-mcp&text=BigQuery%20agents%20in%20your%20code%3A%20the%20API%2C%20ADK%2C%20and%20MCP) Read next [All Guides →](/guides) - [ 8 minBigQuery Data AgentsNovember 3, 2026 ### BigQuery data agents in production: cost, access, trust Run BigQuery data agents in production: cap cost with quotas and byte limits, control access with IAM and row-level security, monitor usage, check inputs. by **David Pombar**](/guides/bigquery-data-agents-in-production) - [ 6 minBigQuery Data AgentsNovember 3, 2026 ### BigQuery Data Science Agent: analysis in a notebook Use the Data Science Agent in BigQuery Studio notebooks to explore GA4 data, forecast revenue, and segment sessions, with a plan you approve step by step. by **David Pombar**](/guides/bigquery-data-science-agent) - [ 13 minAgentic AnalyticsSeptember 28, 2026 ### Same models, different answers. Inside the new agentic Trackingplan: how it works, and why it isn’t comparable to an LLM with an MCP. by **Alexandros Andre Chaaraoui**](/blog/same-models-different-answers) Trackingplan ## See everything. Miss nothing. Your implementations audited around the clock with real-time, real-user data. Real-time alerts about errors or changes in your data, campaigns, pixels, privacy and consent. Let AI flag issues before they cost you. [Start free trial →](https://app.trackingplan.com/signup) [Book a demo](/demo)