Search Grounding
Copyright 2025 Google LLC.
Grounding using Search as a tool
In this notebook you will learn how to use the new Google Search tool available in the Gemini models, using both the unary API and the Multimodal Live API. Check out the docs to learn more about using Search as a tool.
Note that the previous version of this guide using Gemini models priori to 2.0 and the legacy SDK can still be found here.
Set up the SDK and the client
Install SDK
This guide uses the google-genai Python SDK to connect to the Gemini models.
You'll find more details about the SDK on the documentation or in the Getting started notebook.
Set up your API key
To run the following cell, your API key must be stored it in a Colab Secret named GOOGLE_API_KEY. If you don't already have an API key, or you're not sure how to create a Colab Secret, see the Authentication quickstart for an example.
Select model and initialize SDK client
The client will pick up your API key from the environment variable.
Now select the model you want to use in this guide, either by selecting one in the list or writing it down. Keep in mind that some models, like the 2.5 ones are thinking models and thus take slightly more time to respond (cf. thinking notebook for more details and in particular learn how to switch the thiking off).
Use Google Search
Search grounding is particularly useful for queries that require current information or external knowledge. Using Google Search, Gemini can access nearly real-time information and better responses.
Search Query: ['latest Indian Premier League match and winner', 'IPL 2025 final match and winner'] Search Pages: olympics.com, thehindu.com, economictimes.com, wikipedia.org, skysports.com, olympics.com, wikipedia.org
The information provided may be outdated, as it is based on a knowledge cutoff. For the most current and authoritative details, please refer to the official Model documentation, which includes the latest knowledge cutoff date.
You can see that running the same prompt without search grounding gives you outdated information:
Use search in chat
Start by defining a helper function that you will use to display each part of the returned response.
First try a query that needs realtime information, so you can see how the model performs without Google Search.
Now set up a new chat session that uses the google_search tool. The show_parts helper will display the text output as well as any Google Search queries used in the results.
As you are using a chat session, you can ask the model follow-up questions too.
Plot search results
In this example you can see how to use the Google Search tool with code generation in order to plot results.
First review the supplied code to make sure it does what you expect, then copy it here to try out the chart.
import matplotlib.pyplot as plt
import numpy as np
# Data for Denis Villeneuve's 10 most recent movies and their runtimes
movies = [
"Dune: Part Two (2024)",
"Dune (2021)",
"Blade Runner 2049 (2017)",
"Arrival (2016)",
"Sicario (2015)",
"Prisoners (2013)",
"Enemy (2013)",
"Incendies (2010)",
"Polytechnique (2009)",
"Maelström (2000)"
]
runtimes = [166, 155, 163, 116, 121, 153, 91, 131, 77, 87] # Runtimes in minutes
# Create the bar chart
fig, ax = plt.subplots(figsize=(12, 7)) # Adjust figure size for better readability
bars = ax.bar(movies, runtimes, color='skyblue')
# Add titles and labels
ax.set_xlabel("Movie Title (Release Year)", fontsize=12)
ax.set_ylabel("Runtime (Minutes)", fontsize=12)
ax.set_title("Runtimes of Denis Villeneuve's 10 Most Recent Movies", fontsize=14)
plt.xticks(rotation=45, ha='right') # Rotate x-axis labels for better readability
# Add the runtime values on top of the bars
for bar in bars:
yval = bar.get_height()
ax.text(bar.get_x() + bar.get_width()/2, yval + 2, round(yval), ha='center', va='bottom', fontsize=9)
# Improve layout and display the plot
plt.tight_layout()
plt.show()
One feature of using a chat conversation to do this is that you can now ask the model to make changes.
Again, always be sure to review code generated by the model before running it.
Use search in the Multimodal Live API
The Search tool can be used in a live streaming context to have the model formulate grounded responses during the conversation.
Define some helpers
To use the bi-directional streaming API in Colab, you will buffer the audio stream. Define a play_response helper function to do the buffering, and once the audio for the current turn has completed, display an IPython audio widget.
As each of the following examples only use a single prompt, also define a run helper to wrap the setup and prompt execution steps into a single function call. This helper takes a config argument that will be added to the generation_config, so that you can toggle the Search tool between examples.
Stream with the Search tool
First, execute a query without the Search tool to observe the model's response to a time-sensitive query.
Note that the Multimodal Live API is a 2-way streaming API, but to simplify running in a notebook, each audio response is buffered and played once it has been fully streamed, so you will need to wait a few seconds before the response starts to play.
/tmp/ipython-input-1749242392.py:79: DeprecationWarning: The `session.send` method is deprecated and will be removed in a future version (not before Q3 2025). Please use one of the more specific methods: `send_client_content`, `send_realtime_input`, or `send_tool_response` instead. await strm.send(input=query, end_of_turn=True)
Buffering......................................................................................................................................................................................................................................................................................
Now re-run with the Search tool enabled.
/tmp/ipython-input-1749242392.py:79: DeprecationWarning: The `session.send` method is deprecated and will be removed in a future version (not before Q3 2025). Please use one of the more specific methods: `send_client_content`, `send_realtime_input`, or `send_tool_response` instead. await strm.send(input=query, end_of_turn=True)
Buffering
WARNING:google_genai.types:Warning: there are non-data parts in the response: ['executable_code'], returning concatenated data result from data parts, check out the non data parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['code_execution_result'], returning concatenated data result from data parts, check out the non data parts for full response from model.
..
WARNING:google_genai.types:Warning: there are non-data parts in the response: ['executable_code'], returning concatenated data result from data parts, check out the non data parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['code_execution_result'], returning concatenated data result from data parts, check out the non data parts for full response from model.
..
WARNING:google_genai.types:Warning: there are non-data parts in the response: ['executable_code'], returning concatenated data result from data parts, check out the non data parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['code_execution_result'], returning concatenated data result from data parts, check out the non data parts for full response from model.
..
WARNING:google_genai.types:Warning: there are non-data parts in the response: ['executable_code'], returning concatenated data result from data parts, check out the non data parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['code_execution_result'], returning concatenated data result from data parts, check out the non data parts for full response from model.
..
WARNING:google_genai.types:Warning: there are non-data parts in the response: ['executable_code'], returning concatenated data result from data parts, check out the non data parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['code_execution_result'], returning concatenated data result from data parts, check out the non data parts for full response from model.
..............................................................................................................................................................................................................................................................................................................................................................................................
If you wish to see the full output that was returned, you can enable show_output here and run this cell. It includes the complete audio binary data, so it is off by default.
Search with custom tools
In the Multimodal Live API, the Search tool can be used in conjunction with other tools, including function calls that you provide to the model.
In this example, you define a function set_climate that takes 2 parameters, mode (hot, cold, etc) and strength (0-10), and ask the model to set the climate control based on the live weather in the location you specify.
/tmp/ipython-input-4150174230.py:81: DeprecationWarning: The `session.send` method is deprecated and will be removed in a future version (not before Q3 2025). Please use one of the more specific methods: `send_client_content`, `send_realtime_input`, or `send_tool_response` instead. await strm.send(input=query, end_of_turn=True)
Buffering
WARNING:google_genai.types:Warning: there are non-text parts in the response: ['executable_code'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['executable_code'], returning concatenated data result from data parts, check out the non data parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['code_execution_result'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['code_execution_result'], returning concatenated data result from data parts, check out the non data parts for full response from model.
..
WARNING:google_genai.types:Warning: there are non-text parts in the response: ['executable_code'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['executable_code'], returning concatenated data result from data parts, check out the non data parts for full response from model. /tmp/ipython-input-4150174230.py:55: DeprecationWarning: The `session.send` method is deprecated and will be removed in a future version (not before Q3 2025). Please use one of the more specific methods: `send_client_content`, `send_realtime_input`, or `send_tool_response` instead. await stream.send(input=tool_response) WARNING:google_genai.types:Warning: there are non-text parts in the response: ['code_execution_result'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-data parts in the response: ['code_execution_result'], returning concatenated data result from data parts, check out the non data parts for full response from model.
.Tool call..
WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model.
.......
WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model.
.......
WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model. WARNING:google_genai.types:Warning: there are non-text parts in the response: ['inline_data'], returning concatenated text result from text parts, check out the non text parts for full response from model.
.......
Now inspect the tool_call response(s) you received during the conversation.
set_climate(mode=cold, strength=7) # id=function-call-8243969279664206973
Next steps
Search grounding is not the only way to ground your requests, you can also use Youtube links and URL context. Check the Grounding guide for more info on those capabilities.
- For more demos showcasing multi-tool use in the Multimodal Live API, check out the Plotting and Mapping cookbook.
- To get started with the Live API with the Python SDK, check out the starter guide.
- To learn more about tool use in the Live API, check out the Live API Tool Use cookbook.
Also check the other Gemini advanced capabilities (like spatial understanding) that you can find in the Gemini Cookbook.