chore: import upstream snapshot with attribution

contributing/samples/tools/function_tools/README.md

@@ -0,0 +1,52 @@
+# ADK Agent Function Tools Sample
+
+## Overview
+
+This sample demonstrates how to create an agent equipped with built-in Python function tools using the **ADK** framework.
+
+It defines an `Agent` wrapped around two utility functions: `generate_random_number` and `is_even`. The LLM can automatically invoke these underlying Python functions based on user prompts. This sample shows how simple it is to turn raw python methods into actionable capabilities for your agents.
+
+## Sample Inputs
+
+- `Give me a random number.`
+
+- `Give me a random number up to 50, and tell me if it's even.`
+
+- `Give me a random number and is 44 even?`
+
+  *This will cause parallel tools being called in a single step*
+
+## Graph
+
+```mermaid
+graph TD
+    Agent[Agent: function_tools] --> Tool1[Tool: generate_random_number]
+    Agent --> Tool2[Tool: is_even]
+```
+
+## How To
+
+1. Define standard Python functions with type hints and precise docstrings:
+
+   ```python
+   import random
+
+   def generate_random_number(max_value: int = 100) -> int:
+       """Generates a random integer between 0 and max_value (inclusive). ..."""
+       return random.randint(0, max_value)
+
+   def is_even(number: int) -> bool:
+       """Checks if a given number is even. ..."""
+       return number % 2 == 0
+   ```
+
+1. Register the functions directly to the agent's `tools` list during instantiation:
+
+   ```python
+   from google.adk.agents import Agent
+
+   root_agent = Agent(
+       name="function_tools",
+       tools=[generate_random_number, is_even],
+   )
+   ```

contributing/samples/tools/function_tools/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2026 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.
+
+from . import agent

contributing/samples/tools/function_tools/agent.py

@@ -0,0 +1,58 @@
+# Copyright 2026 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.
+
+from __future__ import annotations
+
+import os
+import random
+
+from google.adk.agents import Agent
+
+_counter = 0
+
+
+def generate_random_number(max_value: int = 100) -> int:
+  """Generates a random integer between 0 and max_value (inclusive).
+
+  Args:
+      max_value: The upper limit for the random number.
+
+  Returns:
+      A random integer between 0 and max_value.
+  """
+  # Return a growing value in tests to ensure determinism while allowing
+  # multiple calls.
+  if "PYTEST_CURRENT_TEST" in os.environ:
+    global _counter
+    _counter += 1
+    return _counter
+  return random.randint(0, max_value)
+
+
+def is_even(number: int) -> bool:
+  """Checks if a given number is even.
+
+  Args:
+      number: The number to check.
+
+  Returns:
+      True if the number is even, False otherwise.
+  """
+  return number % 2 == 0
+
+
+root_agent = Agent(
+    name="function_tools",
+    tools=[generate_random_number, is_even],
+)

contributing/samples/tools/function_tools/tests/a_random_number.json

@@ -0,0 +1,81 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "a random number"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {},
+              "id": "fc-1",
+              "name": "generate_random_number"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "generate_random_number",
+              "response": {
+                "result": 1
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "text": "Here is a random number: 1\n"
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    }
+  ]
+}

contributing/samples/tools/function_tools/tests/a_random_number_and_check_even.json

@@ -0,0 +1,127 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "a random number and check even"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {},
+              "id": "fc-1",
+              "name": "generate_random_number"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "generate_random_number",
+              "response": {
+                "result": 1
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "number": 1
+              },
+              "id": "fc-2",
+              "name": "is_even"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-2",
+              "name": "is_even",
+              "response": {
+                "result": false
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "text": "The random number is 1. It is not an even number."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    }
+  ]
+}

contributing/samples/tools/function_tools/tests/random_number_and_is_5_even.json

@@ -0,0 +1,99 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "random number and is 5 even?"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {},
+              "id": "fc-1",
+              "name": "generate_random_number"
+            }
+          },
+          {
+            "functionCall": {
+              "args": {
+                "number": 5
+              },
+              "id": "fc-2",
+              "name": "is_even"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "generate_random_number",
+              "response": {
+                "result": 1
+              }
+            }
+          },
+          {
+            "functionResponse": {
+              "id": "fc-2",
+              "name": "is_even",
+              "response": {
+                "result": false
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    },
+    {
+      "author": "function_tools",
+      "content": {
+        "parts": [
+          {
+            "text": "A random number is 1, and no, 5 is not an even number."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "function_tools@1"
+      }
+    }
+  ]
+}