Gemini · Grounding with Google search and live features
Ask Gemini "Who won the men's singles title at the most recent Australian Open?" with grounding off, and you may get a confident answer about a tournament that finished before the model's training cut. Turn grounding on, and Gemini issues a real Google Search, reads fresh results, and hands you the current answer with links you can click to verify. This lesson shows you how that works, and how to enable it in the Gemini APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.View full definition → and AI Studio.
The problem grounding solves
A base model answers from its parameters. That knowledge is frozen at training time and has no concept of "today." For anything time-sensitive (prices, scores, news, leadership changes, product versions) the model is either stale or guessing.
Grounding connects the model to an external source of truth at inferenceinferenceThe moment a trained AI model is put to work: it takes a new input and produces an answer, prediction or generated output.View full definition → time and makes it base its response on what it retrieves. With grounding with Google Search, that source is live Google Search. Gemini decides when a query needs fresh facts, runs the search, and conditions its answer on the results.
The payoff is two things you cannot get from a raw model: freshness and citations. The API returns the supporting search results and the text spans they back up, so you can show users where each claim came from.
Ungrounded vs grounded, side by side
Prompt: *"What is the latest stable version of the Gemini API SDK for Python, and when was it released?"*
Ungrounded answer: plausible-sounding version number, possibly wrong, no source, no date you can trust.
Grounded answer: the version reported by current search results, plus groundingChunks pointing at the official docs and release notes. If the answer is wrong, you can see *why* by inspecting the sources rather than re-promptingpromptingPrompt engineering is the practice of designing and refining text inputs to guide large language models toward accurate, relevant, and reliable outputs.View full definition → blindly.
This is the core mental shift: **with grounding, a wrong answer becomes a *debuggable* answer**.
Enabling grounding in the Gemini API
Grounding is a tool you attach to a request. You do not change the prompt. You give the model the Google Search tool and let it decide when to call it.
from google import genai
from google.genai import types
client = genai.Client() # reads GEMINI_API_KEY from the environment
response = client.models.generate_content(
model="gemini-3-flash-preview", # check the models page for the current Flash ID
contents="Who won the most recent F1 Grand Prix, and what was the date?",
config=types.GenerateContentConfig(
tools=[types.Tool(google_search=types.GoogleSearch())]
),
)
print(response.text)
# Inspect what the model actually grounded on
metadata = response.candidates[0].grounding_metadata
for chunk in metadata.grounding_chunks:
print(chunk.web.title, "->", chunk.web.uri)A few things to notice:
- You pass
google_searchas a tool, alongside any function-calling tools you already use. The model chooses whether to invoke it per request. - The response carries a
grounding_metadatablock. That is where citations live, not in the prose. - Flash from the current Gemini 3 family is a sensible default. Grounding queries are common and high-volume, and Flash keeps latency and cost down. ReachReachThe number of unique people exposed to your message in a given period. Unlike impressions, reach counts each person once, no matter how often they see it.View full definition → for Pro when the reasoning *over* the retrieved facts is hard. Older 2.5 models still work for now, but new projects should start on the current generation.
- Model IDs change as previews become stable releases. Pin the exact ID from the models page instead of copying one from a tutorial.
- Grounding is billed separately from tokenstokensA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.View full definition →. On newer models it is charged per search query the model runs, so one prompt can count as several searches. Check the pricing page before you scale.
Get a key and try this in minutes at aistudio.google.com. The full tool reference is in the Google Search grounding docs.
Reading grounding metadata properly
grounding_metadata gives you three useful structures:
grounding_chunks: the sources (title + URI). These are your citations.grounding_supports: maps spans of the answer text to the chunks that support them. This is how you build per-sentence footnotes.web_search_queries: the actual queries Gemini sent to Search. Useful for debugging when an answer looks off, because you can see what it searched for.
If you display grounded answers to users, Google's terms require you to show the search suggestions returned in the response (searchEntryPoint). Render it. It is not optional decoration.
entry = response.candidates[0].grounding_metadata.search_entry_point
if entry and entry.rendered_content:
html_to_show_in_ui = entry.rendered_contentGrounding in AI Studio (no code)
In AI Studio, open a chat prompt and toggle Grounding with Google Search in the right-hand tools panel. Send your time-sensitive question and watch the response come back with a sources strip underneath.
This is the fastest way to *compare* behavior. Run the same prompt with the toggle off, then on. The contrast makes the value obvious, and the "Get code" button exports the exact request (including the tool config above) so you can lift it straight into your app.
Grounding vs RAGRAGA method that lets an AI model answer using your own documents, retrieving relevant passages before generating a response instead of relying only on training data.View full definition →: when to use which
You already know RAG conceptually. Grounding with Search does not replace it. Choose by where the truth lives:
- Your truth is private (internal docs, a product catalog, a knowledge base): build RAG over your own dataown dataData collected directly from your own customers and prospects through your own channels: your most reliable and privacy-compliant source.View full definition →, or use the grounding-on-your-data options in Vertex AI.
- Your truth is public and current (news, weather, scores, market data, "what's the latest version of X"): grounding with Google Search.
Many production assistants use both: RAG for company knowledge, Search grounding for the open web. They compose cleanly because both are just tools the model can call.
Live features: real-time, multimodalmultimodalAI that works across several input and output types at once: text, images, audio, video and data, instead of one format only.View full definition → interaction
Grounding makes answers *fresh*. The Live API makes interaction *real-time*. These are different capabilities and people often confuse them, so be precise.
The Live API opens a persistent, low-latency, bidirectional stream between your app and Gemini. Instead of "send prompt, wait for full response," you stream audio (and optionally video frames) *in* and receive audio and text *out* as it is generated. The user can interrupt mid-sentence, and the model handles it. This is what powers natural voice conversations, live screen-sharing help, and real-time tutoring.
Key properties:
- Streaming both ways over a WebSocket-style session, not request/response.
- Native audio in and out, so you are not bolting on separate speech-to-text and text-to-speech. The model hears and speaks directly.
- Interruptions and turn-taking are handled by the session.
- Tools still work inside a live session, including function calling and Search grounding. A voice assistant can ground a spoken answer in live Search results.
A minimal Live session
import asyncio
from google import genai
client = genai.Client()
# Native-audio model IDs are versioned previews that rotate every few months.
# Copy the current one from the Live API docs.
MODEL = "<current-native-audio-model-id>"
async def main():
config = {"response_modalities": ["AUDIO"]}
async with client.aio.live.connect(model=MODEL, config=config) as session:
await session.send_client_content(
turns={"parts": [{"text": "In one sentence, what's the weather typically like in Lisbon in May?"}]}
)
async for message in session.receive():
if message.data:
play_audio_chunk(message.data) # your audio sink
asyncio.run(main())Live and native-audio models ship as dated previews and get retired on a schedule, so a model ID hardcoded last year will likely fail today. Check the Live API docs for the current model before you build. The shape of the code (connect, send, async-iterate over streamed messages) is stable.
When live matters
Use the Live API when the *interaction* is the product:
- Voice agents and phone-style assistants.
- "Show me what you see" support, where the user streams their camera or screen and Gemini reacts in real time.
- Live coaching, language practice, or accessibility tools where latency kills the experience.
If you only need a fast text answer, you do not need the Live API. Plain generate_content (with streaming output if you want tokens as they arrive) is simpler and cheaper.
Knowledge check
1. What core problem does grounding with Google Search solve for a language model?
2. The lesson describes a 'core mental shift' when using grounding. What is it?
3. According to the lesson, how do you enable grounding in a Gemini API request?
4. Select ALL benefits that grounding with Google Search provides which a raw, ungrounded model cannot.
Select all the correct answers.
5. Select ALL situations where enabling grounding is clearly preferable to relying on the base model alone.
Select all the correct answers.
Putting it together: a grounded voice assistant
The two features combine into something useful: a real-time assistant that speaks, listens, and answers from live facts. You open a Live session, enable the Search tool in the session config, and the model grounds spoken answers automatically.
config = {
"response_modalities": ["AUDIO"],
"tools": [{"google_search": {}}],
}
# Inside the live session, a spoken question like
# "What did the markets do today?" now triggers a real Search,
# and the spoken answer is grounded in live results.That single tools line is the difference between an assistant that confidently makes up today's market move and one that actually checks. Same pattern as the non-live API: grounding is a tool, and the model decides when to use it.
Production guardrails
A few things separate a demo from something you ship:
- Always render citations. If you hide the sources, you have rebuilt the hallucination problem with extra steps. Surface
grounding_chunksin the UI. - Display the search suggestions (
searchEntryPoint) when required by Google's grounding terms. - Do not assume grounding fired. The model may answer from parameters if it judges no search is needed. Check whether
grounding_metadatais present before claiming "this is verified." - Pick the tier deliberately. Use Flash for high-volume grounded lookups and Pro when reasoning over retrieved facts is the hard part. Watch the per-search charges, which grow with how many queries the model decides to run.
- Pin model IDs in config, not scattered through code, so a preview retirement is a one-line fix.
- For private plus public truth, plan to run RAG and Search grounding together rather than forcing one tool to do both jobs.
Where this scales
For enterprise deployments, the same grounding concept lives in Vertex AI, **with grounding on Google Search *and* grounding on your own enterprise data, plus the governance, logging, and IAM controls a regulated org needs**. If your assistant graduates from prototype to a production system inside Google Cloud, that is the path: see cloud.google.com/vertex-ai. The API surface is close enough that prototypes built in AI Studio port over without a rewrite of your core logic.
Key Takeaways
- Grounding is a tool, not a prompt trick. Attach
google_searchto your request. The model decides when to search and returns citations ingrounding_metadata. Read and display those sources. - Use grounding for the public, current web and RAG for your private data. Production assistants commonly run both.
- Start new projects on the current Gemini 3 models and pin IDs from the models page. Grounding is billed per search on newer models, so budget for it.
- The Live API is about real-time interaction, not freshness. Stream audio and video in and out over a persistent session for voice agents and live help. Tools, including Search grounding, work inside it, but always look up the current native-audio model.
- Prototype in AI Studio, then export. Toggle grounding on and off to see the contrast, hit "Get code," and lift the exact tool config into your app.
- Always surface citations and search suggestions. Hiding sources undoes the point of grounding and may violate the usage terms.
Frequently asked questions
What does grounding with Google Search actually do in the Gemini API?
It connects Gemini to live Google Search at inference time, so the model retrieves current results and bases its answer on them instead of on frozen training data. You attach `google_search` as a tool to the request, and the model decides per request whether to search. The response comes back with `grounding_metadata` containing the sources behind each claim.
What is the difference between grounding with Google Search and RAG?
The difference is where the truth lives. RAG retrieves from your private data such as internal documents, a product catalog or a knowledge base; grounding with Google Search retrieves from the public, current web like news, scores, prices or the latest version of a product. Many production assistants run both, since each is just a tool the model can call.
How do I enable grounding in Google AI Studio without writing code?
Open a chat prompt in AI Studio and toggle Grounding with Google Search in the tools panel on the right, then send your time-sensitive question. The answer comes back with a sources strip underneath. Running the same prompt with the toggle off and then on is the fastest way to see the difference, and the "Get code" button exports the exact request with the tool config included.
How do I show citations for a grounded Gemini answer?
Citations live in `grounding_metadata`, not in the prose. `grounding_chunks` gives you the sources with title and URI, `grounding_supports` maps spans of the answer to the chunks that back them so you can build per-sentence footnotes, and `web_search_queries` shows what Gemini actually searched for when an answer looks off. Google's terms also require you to render the search suggestions returned in `searchEntryPoint`.
When should I use the Gemini Live API instead of a standard generate_content call?
Use the Live API when the interaction itself is the product: voice agents, "show me what you see" support with a streamed camera or screen, live coaching or accessibility tools where latency ruins the experience. It opens a persistent bidirectional session with native audio in and out and handles interruptions and turn-taking. If you only need a fast text answer, plain `generate_content` with streaming output is simpler and cheaper.
Can a Gemini voice assistant use Google Search grounding inside a live session?
Yes. Tools work inside a Live session, so adding `"tools": [{"google_search": {}}]` to the session config lets a spoken question like "What did the markets do today?" trigger a real search and ground the spoken answer in live results. The pattern is the same as the non-live API: grounding is a tool and the model decides when to call it. Note that Live and native-audio models ship as dated previews that get retired, so look up the current model ID in the Live API docs before building.
What to do, from this lesson
These actions are compiled in the role's Playbook.
- Use @-mention extensions for app data, search grounding for public web facts
- Prototype visually in AI Studio, then Get code with an env-var key