chore: import upstream snapshot with attribution

contributing/samples/core/hello_world/README.md

@@ -0,0 +1,91 @@
+# Hello World Assistant
+
+## Overview
+
+This sample demonstrates a foundational ADK standalone agent that interacts with a user, manages session state via `ToolContext`, and uses multiple tools. Specifically, it features a `hello_world_agent` that can roll an N-sided die (storing roll history in the session state) and check whether numbers in a list are prime.
+
+## Sample Inputs
+
+- `Hi`
+
+  *General greeting that does not trigger tool calls.*
+
+- `Roll a dice with 100 sides`
+
+  *The agent invokes the `roll_die` tool with `sides=100`. The rolled result is appended to the session's `ToolContext` state under the `'rolls'` key.*
+
+- `Roll a dice again with 100 sides.`
+
+  *The agent invokes `roll_die` again, appending a second roll to the session state.*
+
+- `What numbers did I got?`
+
+  *The agent references the conversation history and previous tool outcomes to summarize the rolled numbers.*
+
+- `Roll a die with 8 sides and check if the result is prime.`
+
+  *Demonstrates multi-step tool orchestration. The agent first calls `roll_die(sides=8)`, waits for the response, and then calls `check_prime(nums=[...])` with the rolled result before formulating its final response.*
+
+## Graph
+
+```mermaid
+graph TD
+    Agent[Agent: hello_world_agent] --> Tool1[Tool: roll_die]
+    Agent --> Tool2[Tool: check_prime]
+```
+
+## How To
+
+### 1. Defining Tools with ToolContext
+
+Demonstrates how tools can access and modify persistent session state by including `tool_context: ToolContext` as a parameter.
+
+```python
+def roll_die(sides: int, tool_context: ToolContext) -> int:
+  result = random.randint(1, sides)
+  if not 'rolls' in tool_context.state:
+    tool_context.state['rolls'] = []
+  tool_context.state['rolls'] = tool_context.state['rolls'] + [result]
+  return result
+```
+
+### 2. Configuring Safety Settings
+
+Demonstrates adjusting `GenerateContentConfig` safety settings to prevent false alarms (e.g., avoiding harm category triggers when discussing rolling dice).
+
+```python
+root_agent = Agent(
+    model='gemini-3-flash-preview',
+    name='hello_world_agent',
+    ...
+    generate_content_config=types.GenerateContentConfig(
+        safety_settings=[
+            types.SafetySetting(
+                category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+                threshold=types.HarmBlockThreshold.OFF,
+            ),
+        ]
+    ),
+)
+```
+
+### 3. Running and Inspecting the Agent Programmatically
+
+You can execute the agent and inspect its session state programmatically by initializing an `InMemoryRunner`, creating a session, and executing prompts asynchronously:
+
+```python
+runner = InMemoryRunner(agent=agent.root_agent, app_name='my_app')
+session = await runner.session_service.create_session('my_app', 'user1')
+
+async for event in runner.run_async(
+    user_id='user1',
+    session_id=session.id,
+    new_message=types.Content(...),
+):
+  # Process execution events
+  pass
+
+# Inspect modified session state
+session = await runner.session_service.get_session('my_app', 'user1', session.id)
+print(session.state['rolls'])
+```

contributing/samples/core/hello_world/__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/core/hello_world/agent.py

@@ -0,0 +1,107 @@
+# 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.
+
+import random
+
+from google.adk import Agent
+from google.adk.tools.tool_context import ToolContext
+from google.genai import types
+
+
+def roll_die(sides: int, tool_context: ToolContext) -> int:
+  """Roll a die and return the rolled result.
+
+  Args:
+    sides: The integer number of sides the die has.
+
+  Returns:
+    An integer of the result of rolling the die.
+  """
+  result = random.randint(1, sides)
+  if not 'rolls' in tool_context.state:
+    tool_context.state['rolls'] = []
+
+  tool_context.state['rolls'] = tool_context.state['rolls'] + [result]
+  return result
+
+
+async def check_prime(nums: list[int]) -> str:
+  """Check if a given list of numbers are prime.
+
+  Args:
+    nums: The list of numbers to check.
+
+  Returns:
+    A str indicating which number is prime.
+  """
+  primes = set()
+  for number in nums:
+    number = int(number)
+    if number <= 1:
+      continue
+    is_prime = True
+    for i in range(2, int(number**0.5) + 1):
+      if number % i == 0:
+        is_prime = False
+        break
+    if is_prime:
+      primes.add(number)
+  return (
+      'No prime numbers found.'
+      if not primes
+      else f"{', '.join(str(num) for num in primes)} are prime numbers."
+  )
+
+
+root_agent = Agent(
+    name='hello_world_agent',
+    description=(
+        'hello world agent that can roll a dice of 8 sides and check prime'
+        ' numbers.'
+    ),
+    instruction="""
+      You roll dice and answer questions about the outcome of the dice rolls.
+      You can roll dice of different sizes.
+      You can use multiple tools in parallel by calling functions in parallel(in one request and in one round).
+      It is ok to discuss previous dice roles, and comment on the dice rolls.
+      When you are asked to roll a die, you must call the roll_die tool with the number of sides. Be sure to pass in an integer. Do not pass in a string.
+      You should never roll a die on your own.
+      When checking prime numbers, call the check_prime tool with a list of integers. Be sure to pass in a list of integers. You should never pass in a string.
+      You should not check prime numbers before calling the tool.
+      When you are asked to roll a die and check prime numbers, you should always make the following two function calls:
+      1. You should first call the roll_die tool to get a roll. Wait for the function response before calling the check_prime tool.
+      2. After you get the function response from roll_die tool, you should call the check_prime tool with the roll_die result.
+        2.1 If user asks you to check primes based on previous rolls, make sure you include the previous rolls in the list.
+      3. When you respond, you must include the roll_die result from step 1.
+      You should always perform the previous 3 steps when asking for a roll and checking prime numbers.
+      You should not rely on the previous history on prime results.
+    """,
+    tools=[
+        roll_die,
+        check_prime,
+    ],
+    # planner=BuiltInPlanner(
+    #     thinking_config=types.ThinkingConfig(
+    #         include_thoughts=True,
+    #     ),
+    # ),
+    generate_content_config=types.GenerateContentConfig(
+        safety_settings=[
+            types.SafetySetting(  # avoid false alarm about rolling dice.
+                category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
+                threshold=types.HarmBlockThreshold.OFF,
+            ),
+        ]
+    ),
+)

contributing/samples/core/hello_world/tests/check_prime.json

@@ -0,0 +1,86 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "Check if 7 and 10 are prime numbers"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "nums": [
+                  7,
+                  10
+                ]
+              },
+              "id": "fc-1",
+              "name": "check_prime"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "check_prime",
+              "response": {
+                "result": "7 are prime numbers."
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "7 are prime numbers."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    }
+  ]
+}

contributing/samples/core/hello_world/tests/roll_and_check.json

@@ -0,0 +1,138 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "Roll a 10-sided die and check if the result is prime"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "sides": 10
+              },
+              "id": "fc-1",
+              "name": "roll_die"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "rolls": [
+            2
+          ]
+        }
+      },
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "roll_die",
+              "response": {
+                "result": 2
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "nums": [
+                  2
+                ]
+              },
+              "id": "fc-2",
+              "name": "check_prime"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-2",
+              "name": "check_prime",
+              "response": {
+                "result": "2 are prime numbers."
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-5",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "I rolled a 10-sided die and got a 2.\n2 are prime numbers."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-6",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    }
+  ]
+}

contributing/samples/core/hello_world/tests/roll_die.json

@@ -0,0 +1,95 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "Roll a 6-sided die"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "sides": 6
+              },
+              "id": "fc-1",
+              "name": "roll_die"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    },
+    {
+      "actions": {
+        "stateDelta": {
+          "rolls": [
+            6
+          ]
+        }
+      },
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "roll_die",
+              "response": {
+                "result": 6
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    },
+    {
+      "author": "hello_world_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "You rolled a 6-sided die and got a 6."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "hello_world_agent@1"
+      }
+    }
+  ],
+  "mocks": {
+    "random.randint": [
+      6
+    ]
+  }
+}