Generative AI Google Brain

agents-gemini-data-analytics-intro-gemini-data-analytics-http

4 min read

Intro to Gemini Data Analytics

Source notebook

Repo path: agents/gemini_data_analytics/intro_gemini_data_analytics_http.ipynb · Open on GitHub · intermediate

Shows REST-based Gemini Data Analytics agents over BigQuery, Looker, or Looker Studio data.

Summary

This notebook teaches how to authenticate in Colab, configure a billing project and datasource references, then call the Gemini Data Analytics REST API with bearer-token HTTP requests. It demonstrates creating, reading, listing, updating, sharing, and deleting data agents, then creating conversations and asking analytical questions. It also shows stateful, stateless, and multi-turn chat flows with streamed text, schema, data, SQL, and chart handling.

Key code patterns

Colab ADC bearer headers

auth.authenticate_user()
access_token = !gcloud auth application-default print-access-token
headers = {
    "Authorization": f"Bearer {access_token[0]}",
    "Content-Type": "application/json",
}

Authenticates the notebook user and prepares REST headers for Gemini Data Analytics API calls.

BigQuery datasource references

bigquery_data_sources = {"bq": {"tableReferences": [
    {"projectId": "bigquery-public-data", "datasetId": "faa", "tableId": "us_airports"},
    {"projectId": "bigquery-public-data", "datasetId": "san_francisco", "tableId": "street_trees"},
]}}
datasource_references = datasource_map[selected_datasource]

Defines the data tables the conversational analytics agent can query.

Create data agent

data_agent_url = f"{base_url}/{api_version}/projects/{billing_project}/locations/{location}/dataAgents"
data_agent_payload = {
    "name": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}",
    "data_analytics_agent": {"published_context": {
        "datasource_references": datasource_references,
        "system_instruction": system_instruction,
    }},
}
requests.post(data_agent_url, params={"data_agent_id": data_agent_id}, json=data_agent_payload, headers=headers)

Publishes datasource context and system instruction into a reusable data agent.

Context enrichment

ctx = data_agent_payload["data_analytics_agent"]["published_context"]
if bq_selected and use_example_queries:
    ctx["example_queries"] = example_queries
if bq_selected and use_glossary_terms:
    ctx["glossary_terms"] = glossary_terms
elif looker_selected and use_looker_golden_queries:
    ctx["looker_golden_queries"] = looker_golden_queries

Adds example queries, glossary terms, or Looker golden queries to improve agent context.

Stateful chat with conversation

chat_payload = {
    "parent": f"projects/{billing_project}/locations/global",
    "messages": [{"userMessage": {"text": question}}],
    "conversation_reference": {
        "conversation": f"projects/{billing_project}/locations/{location}/conversations/{conversation_id}",
        "data_agent_context": {"data_agent": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"},
    },
}
get_stream(chat_url, chat_payload)

Uses a saved conversation plus data agent context for stateful analytical chat.

Stateless inline context chat

chat_payload = {
    "parent": f"projects/{billing_project}/locations/global",
    "messages": [{"userMessage": {"text": question}}],
    "inline_context": {
        "datasource_references": datasource_references,
        "options": {"analysis": {"python": {"enabled": False}}},
    },
}
get_stream(chat_url, chat_payload)

Calls chat without a pre-created data agent by sending datasource context inline.

Streaming response dispatch

with requests.Session().post(url, json=payload, headers=headers, stream=True) as resp:
    for line in resp.iter_lines():
        data_json = json.loads(acc)
        if "text" in data_json["systemMessage"]:
            handle_text_response(data_json["systemMessage"]["text"])
        elif "schema" in data_json["systemMessage"]:
            handle_schema_response(data_json["systemMessage"]["schema"])
        elif "data" in data_json["systemMessage"]:
            handle_data_response(data_json["systemMessage"]["data"])
        elif "chart" in data_json["systemMessage"]:
            handle_chart_response(data_json["systemMessage"]["chart"])

Parses streamed chat chunks and routes text, schema, data, and chart messages to display helpers.

Multi-turn message history

conversation_messages = []
def multi_turn_conversation(msg):
    conversation_messages.append({"userMessage": {"text": msg}})
    chat_payload = {
        "parent": f"projects/{billing_project}/locations/global",
        "messages": conversation_messages,
        "data_agent_context": {"data_agent": f"projects/{billing_project}/locations/{location}/dataAgents/{data_agent_id}"},
    }
    get_stream_multi_turn(chat_url, chat_payload, conversation_messages)

Maintains prior user and system messages so follow-up questions can use earlier context.

Models & APIs used

  • APIs / services: Conversational Analytics API, Gemini Data Analytics API, cloudaicompanion API, BigQuery API, Dataform API, Agent Platform API, Looker, Looker Studio
  • SDKs / libraries: requests, google.colab, pandas, altair, IPython, pygments

When to use this

Use this pattern when building a REST-based conversational analytics agent over BigQuery, Looker, or Looker Studio data.

Gotchas & caveats

  • The billing project must enable cloudaicompanion, Gemini Data Analytics, BigQuery, Dataform, and Agent Platform APIs.
  • BigQuery tables must be in projects, datasets, and tables where the user has read permissions.
  • The notebook uses Colab auth and gcloud application-default credentials to obtain the bearer token.
  • Looker client_id and client_secret are stated as supported only with PUBLIC instances.
  • Looker access_token is stated as supported with both PUBLIC and PRIVATE instances.
  • Looker datasource comments limit explore references to up to 5 total.
  • Parameterized example queries require a name, description, and valid BigQuery dataType for each parameter.
  • Set IAM Policy overrides existing permission for the data agent unless the existing policy is fetched and preserved.
  • The base URL changes between prod, staging, and autopush environments, while location is set to global.

Best practices

  • Provide critical context for the agent through system_instruction.
  • Attach example_queries and glossary_terms when using BigQuery datasources.
  • Attach looker_golden_queries only when Looker is selected and the flag is enabled.
  • Use updateMask when patching data agent fields.
  • Route streamed system messages by type: text, schema, data, chart, and error.
  • Use conversation_reference or data_agent_context for stateful chat and inline_context for stateless chat.
  • Fetch and preserve the existing IAM policy before calling Set IAM Policy.
  • Include Looker credentials only when the Looker datasource is selected.

Graph View

Backlinks