feat(genai): Add Tool examples (#13128)

* feat(genai): Add Tool examples

* Code execution example
* Function Calling example
* Grounding with Google Search example

* fix(genai): Linter suggestion

* feat(genai): Add region tags

* fix(genai): add image file.

* fix(genai): Fix for CICD issues - update Pillow pkg

* fix(genai): Fix for CICD issues - update Pillow pkg

* fix(genai): Fix for CICD issues - update Pillow pkg

Author: msampathkumar

genai/tools/noxfile_config.py

@@ -0,0 +1,42 @@
+# Copyright 2021 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Default TEST_CONFIG_OVERRIDE for python repos.
+
+# You can copy this file into your directory, then it will be imported from
+# the noxfile.py.
+
+# The source of truth:
+# https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/noxfile_config.py
+
+TEST_CONFIG_OVERRIDE = {
+    # You can opt out from the test for specific Python versions.
+    "ignored_versions": ["2.7", "3.7", "3.8", "3.10", "3.11", "3.12"],
+    # Old samples are opted out of enforcing Python type hints
+    # All new samples should feature them
+    "enforce_type_hints": True,
+    # An envvar key for determining the project id to use. Change it
+    # to 'BUILD_SPECIFIC_GCLOUD_PROJECT' if you want to opt in using a
+    # build specific Cloud project. You can also use your own string
+    # to use your own Cloud project.
+    "gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
+    # 'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',
+    # If you need to use a specific version of pip,
+    # change pip_version_override to the string representation
+    # of the version number, for example, "20.2.4"
+    "pip_version_override": None,
+    # A dictionary you want to inject into your test. Don't put any
+    # secrets here. These values will override predefined values.
+    "envs": {},
+}

genai/tools/requirements-test.txt

@@ -0,0 +1,4 @@
+backoff==2.2.1
+google-api-core==2.19.0
+pytest==8.2.0
+pytest-asyncio==0.23.6

genai/tools/requirements.txt

@@ -0,0 +1,3 @@
+google-genai==0.8.0
+# PIl is required for tools_code_execution_with_txt_img.py
+pillow==11.1.0

genai/tools/test_data/640px-Monty_open_door.svg.png

@@ -0,0 +1,51 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+
+import tools_code_exec_with_txt
+import tools_code_exec_with_txt_local_img
+import tools_func_def_with_txt
+import tools_func_desc_with_txt
+import tools_google_search_with_txt
+
+os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "True"
+os.environ["GOOGLE_CLOUD_LOCATION"] = "us-central1"
+# The project name is included in the CICD pipeline
+# os.environ['GOOGLE_CLOUD_PROJECT'] = "add-your-project-name"
+
+
+def test_tools_code_exec_with_txt() -> None:
+    response = tools_code_exec_with_txt.generate_content()
+    assert response
+
+
+def test_tools_code_exec_with_txt_local_img() -> None:
+    response = tools_code_exec_with_txt_local_img.generate_content()
+    assert response
+
+
+def test_tools_func_def_with_txt() -> None:
+    response = tools_func_def_with_txt.generate_content()
+    assert response
+
+
+def test_tools_func_desc_with_txt() -> None:
+    response = tools_func_desc_with_txt.generate_content()
+    assert response
+
+
+def test_tools_google_search_with_txt() -> None:
+    response = tools_google_search_with_txt.generate_content()
+    assert response

genai/tools/test_tools.py

@@ -0,0 +1,49 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def generate_content() -> str:
+    # [START googlegenaisdk_tools_code_exec_with_txt]
+    from google import genai
+    from google.genai.types import Tool, ToolCodeExecution, GenerateContentConfig
+
+    client = genai.Client()
+    model_id = "gemini-2.0-flash-exp"
+
+    code_execution_tool = Tool(code_execution=ToolCodeExecution())
+    response = client.models.generate_content(
+        model=model_id,
+        contents="Calculate 20th fibonacci number. Then find the nearest palindrome to it.",
+        config=GenerateContentConfig(
+            tools=[code_execution_tool],
+            temperature=0,
+        ),
+    )
+    for part in response.candidates[0].content.parts:
+        if part.executable_code:
+            print(part.executable_code)
+        if part.code_execution_result:
+            print(part.code_execution_result)
+    # Example response:
+    # code='...' language='PYTHON'
+    # outcome='OUTCOME_OK' output='The 20th Fibonacci number is: 6765\n'
+    # code='...' language='PYTHON'
+    # outcome='OUTCOME_OK' output='Lower Palindrome: 6666\nHigher Palindrome: 6776\nNearest Palindrome to 6765: 6776\n'
+
+    # [END googlegenaisdk_tools_code_exec_with_txt]
+    return str(response.candidates[0].content.parts)
+
+
+if __name__ == "__main__":
+    generate_content()

genai/tools/tools_code_exec_with_txt.py

@@ -0,0 +1,75 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from google.genai.types import GenerateContentResponse
+
+
+def generate_content() -> GenerateContentResponse:
+    # [START googlegenaisdk_tools_code_exec_with_txt_local_img]
+    from PIL import Image
+    from google import genai
+    from google.genai.types import Tool, ToolCodeExecution, GenerateContentConfig
+
+    client = genai.Client()
+    code_execution_tool = Tool(code_execution=ToolCodeExecution())
+
+    prompt = """
+    Run a simulation of the Monty Hall Problem with 1,000 trials.
+    Here's how this works as a reminder. In the Monty Hall Problem, you're on a game
+    show with three doors. Behind one is a car, and behind the others are goats. You
+    pick a door. The host, who knows what's behind the doors, opens a different door
+    to reveal a goat. Should you switch to the remaining unopened door?
+    The answer has always been a little difficult for me to understand when people
+    solve it with math - so please run a simulation with Python to show me what the
+    best strategy is.
+    Thank you!
+    """
+
+    # Image source: https://upload.wikimedia.org/wikipedia/commons/thumb/3/3f/Monty_open_door.svg/640px-Monty_open_door.svg.png
+    image_data = Image.open(open("test_data/640px-Monty_open_door.svg.png", "rb"))
+
+    response = client.models.generate_content(
+        model="gemini-2.0-flash-exp",
+        contents=[image_data, prompt],
+        config=GenerateContentConfig(
+            tools=[code_execution_tool],
+            temperature=0,
+        ),
+    )
+
+    print("# Code:")
+    for part in response.candidates[0].content.parts:
+        if part.executable_code:
+            print(part.executable_code)
+
+    print("# Outcome:")
+    for part in response.candidates[0].content.parts:
+        if part.code_execution_result:
+            print(part.code_execution_result)
+
+    # Example response:
+    # # Code:
+    # code='\nimport random\n\ndef monty_hall_simulation(num_trials):\n
+    # """Simulates the Monty Hall problem and returns the win rates for switching and not switching."""\n\n
+    # wins_switching = 0\n    wins_not_switching = 0\n\n    for _ in range(num_trials):\n        # 1. Set up the game:\n
+    #   - Randomly place the car behind one of the three doors.\n        car_door = random.randint(0, 2)\n
+    # ...
+    # # Outcome:
+    # outcome=<Outcome.OUTCOME_OK: 'OUTCOME_OK'> output='Win percentage when switching: 65.90%\nWin percentage when not switching: 34.10%\n'
+    # [END googlegenaisdk_tools_code_exec_with_txt_local_img]
+    return response
+
+
+if __name__ == "__main__":
+    generate_content()

genai/tools/tools_code_exec_with_txt_local_img.py

@@ -0,0 +1,51 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def generate_content() -> str:
+    # [START googlegenaisdk_tools_func_def_with_txt]
+    from google import genai
+    from google.genai.types import GenerateContentConfig
+
+    def get_current_weather(location: str) -> str:
+        """Example method. Returns the current weather.
+
+        Args:
+          location: The city and state, e.g. San Francisco, CA
+        """
+        import random
+
+        return random.choice(["sunny", "raining", "snowing", "fog"])
+
+    client = genai.Client()
+    model_id = "gemini-2.0-flash-exp"
+
+    response = client.models.generate_content(
+        model=model_id,
+        contents="What is the weather like in Boston?",
+        config=GenerateContentConfig(
+            tools=[get_current_weather],
+            temperature=0,
+        ),
+    )
+
+    print(response.text)
+    # Example response:
+    # The weather in Boston is sunny.
+    # [END googlegenaisdk_tools_func_def_with_txt]
+    return response.text
+
+
+if __name__ == "__main__":
+    generate_content()

genai/tools/tools_func_def_with_txt.py

@@ -0,0 +1,91 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#    https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def generate_content() -> str:
+    # [START googlegenaisdk_tools_func_desc_with_txt]
+    from google import genai
+    from google.genai.types import FunctionDeclaration, Tool, GenerateContentConfig
+
+    client = genai.Client()
+    model_id = "gemini-2.0-flash-exp"
+
+    get_album_sales = FunctionDeclaration(
+        name="get_album_sales",
+        description="Gets the number of albums sold",
+        # Function parameters are specified in JSON schema format
+        parameters={
+            "type": "OBJECT",
+            "properties": {
+                "albums": {
+                    "type": "ARRAY",
+                    "description": "List of albums",
+                    "items": {
+                        "description": "Album and its sales",
+                        "type": "OBJECT",
+                        "properties": {
+                            "album_name": {
+                                "type": "STRING",
+                                "description": "Name of the music album",
+                            },
+                            "copies_sold": {
+                                "type": "INTEGER",
+                                "description": "Number of copies sold",
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    )
+
+    sales_tool = Tool(
+        function_declarations=[get_album_sales],
+    )
+
+    response = client.models.generate_content(
+        model=model_id,
+        contents='At Stellar Sounds, a music label, 2024 was a rollercoaster. "Echoes of the Night," a debut synth-pop album, '
+        'surprisingly sold 350,000 copies, while veteran rock band "Crimson Tide\'s" latest, "Reckless Hearts," '
+        'lagged at 120,000. Their up-and-coming indie artist, "Luna Bloom\'s" EP, "Whispers of Dawn," '
+        'secured 75,000 sales. The biggest disappointment was the highly-anticipated rap album "Street Symphony" '
+        "only reaching 100,000 units. Overall, Stellar Sounds moved over 645,000 units this year, revealing unexpected "
+        "trends in music consumption.",
+        config=GenerateContentConfig(
+            tools=[sales_tool],
+            temperature=0,
+        ),
+    )
+
+    print(response.candidates[0].content.parts[0].function_call)
+    # Example response:
+    # [FunctionCall(
+    #     id=None,
+    #     name="get_album_sales",
+    #     args={
+    #         "albums": [
+    #             {"album_name": "Echoes of the Night", "copies_sold": 350000},
+    #             {"copies_sold": 120000, "album_name": "Reckless Hearts"},
+    #             {"copies_sold": 75000, "album_name": "Whispers of Dawn"},
+    #             {"copies_sold": 100000, "album_name": "Street Symphony"},
+    #         ]
+    #     },
+    # )]
+
+    # [END googlegenaisdk_tools_func_desc_with_txt]
+    return str(response.candidates[0].content.parts[0].function_call)
+
+
+if __name__ == "__main__":
+    generate_content()