Generative AI Google Brain

agents-gemini-data-analytics-intro-gemini-data-analytics-sdk

4 min read

Intro to Gemini Data Analytics

Source notebook

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

Shows how to create Gemini Data Analytics agents over BigQuery, Looker, or Looker Studio and chat with them.

Summary

This notebook introduces the Gemini Data Analytics SDK and the Conversational Analytics API. It walks through authentication, datasource setup, context and system instruction configuration, Data Agent creation, conversation creation, stateful and stateless chat, multi-turn chat, agent lifecycle operations, conversation lifecycle operations, and IAM sharing. The main workflow is to define datasource references, publish or inline context, create a data agent, send analytics questions, and render text, schema, SQL, data, or chart responses.

Key code patterns

Create clients

from google.cloud import geminidataanalytics_v1 as geminidataanalytics
 
data_agent_client = geminidataanalytics.DataAgentServiceClient()
data_chat_client = geminidataanalytics.DataChatServiceClient()

Separates agent management calls from chat and conversation calls.

Define BigQuery sources

bq_ref = geminidataanalytics.BigQueryTableReference(
    project_id="bigquery-public-data",
    dataset_id="faa",
    table_id="us_airports",
)
bq = geminidataanalytics.BigQueryTableReferences(
    table_references=[bq_ref]
)

Builds structured datasource references instead of embedding table names only in prompts.

Add examples and glossary

example_queries = [geminidataanalytics.ExampleQuery(
    natural_language_question="How many airports are there?",
    sql_query="SELECT COUNT(*) FROM `bigquery-public-data.faa.us_airports`",
)]
glossary_terms = [geminidataanalytics.GlossaryTerm(
    display_name="Airport Code",
    description="A unique identifier for an airport...",
)]

Provides grounded SQL examples and business terminology to improve analytics answers.

Create data agent

data_agent = geminidataanalytics.DataAgent(
    data_analytics_agent=geminidataanalytics.DataAnalyticsAgent(
        published_context=published_context
    )
)
request = geminidataanalytics.CreateDataAgentRequest(
    parent=f"projects/{billing_project}/locations/{location}",
    data_agent_id="data_agent_1",
    data_agent=data_agent,
)

Publishes reusable context as a Data Agent resource.

Stateful chat with agent

messages = [geminidataanalytics.Message(
    user_message=geminidataanalytics.UserMessage(text=question)
)]
request = geminidataanalytics.ChatRequest(
    parent=f"projects/{billing_project}/locations/{location}",
    messages=messages,
    data_agent_context=data_agent_context,
)
stream = data_chat_client.chat(request=request)

Uses a saved Data Agent context for repeated analytical questions.

Stateless inline chat

request = geminidataanalytics.ChatRequest(
    inline_context=inline_context,
    parent=f"projects/{billing_project}/locations/{location}",
    messages=messages,
)
stream = data_chat_client.chat(request=request)

Lets callers send datasource context directly without first creating an agent.

Multi-turn context

conversation_messages.append(message)
request = geminidataanalytics.ChatRequest(
    parent=f"projects/{billing_project}/locations/{location}",
    messages=conversation_messages,
    inline_context=inline_context,
)
stream = data_chat_client.chat(request=request)

Maintains prior user and system messages to support follow-up requests such as changing a chart type.

Models & APIs used

  • APIs / services: Conversational Analytics API, Gemini Data Analytics API, BigQuery API, Dataform API, Agent Platform API, Cloud AI Companion API, Google Cloud IAM, Looker, Looker Studio
  • SDKs / libraries: google-cloud-geminidataanalytics, google.cloud.geminidataanalytics_v1, google.colab, google.iam.v1, google.protobuf, pandas, altair, PyYAML, IPython

When to use this

Use this pattern to build a conversational analytics assistant over BigQuery, Looker, or Looker Studio data with reusable or inline context.

Gotchas & caveats

  • A billing project is required and must have Cloud AI Companion, Gemini Data Analytics, BigQuery, Dataform, and Agent Platform APIs enabled.
  • The notebook uses location “global” for requests and IAM resource names.
  • BigQuery tables can be used only if the caller has read permissions.
  • Looker public instances can use client_id and client_secret, while public and private instances can use access_token.
  • Looker datasource setup supports up to 5 Looker datasources according to the notebook text.
  • Setting IAM policy overrides existing permissions unless the current policy is fetched and merged first.
  • Create and update Data Agent calls are long-running operations and are polled until done.
  • Python advanced analysis is disabled by default with AnalysisOptions.Python(enabled=False).

Best practices

  • Provide business and data context in system_instruction to improve answer quality.
  • Use structured datasource references for BigQuery, Looker, or Looker Studio.
  • Add BigQuery example queries and glossary terms when available.
  • Use validated Looker golden queries when using Looker context.
  • Preserve existing IAM policy by getting it before setting updated permissions.
  • Use update_mask when updating Data Agent fields.
  • Handle streamed chat responses by branching on text, schema, data, and chart message types.
  • Validate YAML system instructions before extracting field insights.

Graph View

Backlinks