chore: import upstream snapshot with attribution

contributing/samples/core/quickstart/README.md

@@ -0,0 +1,81 @@
+# Weather & Time Quickstart Agent
+
+## Overview
+
+This sample demonstrates a fundamental standalone ADK `Agent` configured with multiple tools. It illustrates how an agent can autonomously select and execute Python functions (`get_weather` and `get_current_time`) to gather real-world information and answer user inquiries.
+
+## Sample Inputs
+
+- `What is the weather in New York?`
+
+  *The agent will invoke the `get_weather` tool with `city="New York"` and return the current weather report.*
+
+- `What time is it in New York?`
+
+  *The agent will invoke the `get_current_time` tool with `city="New York"` and return the current timestamp.*
+
+- `Can you tell me the weather in Tokyo?`
+
+  *The agent will attempt to invoke `get_weather`, which returns an error status for cities other than New York, and gracefully explain that the information is unavailable.*
+
+## Graph
+
+```mermaid
+graph TD
+    User[User Input] --> RootAgent[root_agent: weather_time_agent]
+    RootAgent -.->|Tool Call: get_weather| WeatherTool[get_weather]
+    WeatherTool -.->|Tool Result| RootAgent
+    RootAgent -.->|Tool Call: get_current_time| TimeTool[get_current_time]
+    TimeTool -.->|Tool Result| RootAgent
+    RootAgent --> Response[User Response]
+```
+
+## How To
+
+### 1. Defining Tools
+
+In ADK, standard Python functions with type hints and docstrings can be used directly as tools. The docstring and parameter type hints inform the language model when and how to invoke the function:
+
+```python
+def get_weather(city: str) -> dict:
+  """Retrieves the current weather report for a specified city.
+
+  Args:
+      city (str): The name of the city for which to retrieve the weather report.
+
+  Returns:
+      dict: status and result or error msg.
+  """
+  if city.lower() == "new york":
+    return {
+        "status": "success",
+        "report": (
+            "The weather in New York is sunny with a temperature of 25 degrees"
+            " Celsius (77 degrees Fahrenheit)."
+        ),
+    }
+  else:
+    return {
+        "status": "error",
+        "error_message": f"Weather information for '{city}' is not available.",
+    }
+```
+
+### 2. Configuring the Agent
+
+To equip an agent with tools, instantiate an `Agent` and pass the functions in the `tools` parameter list, along with clear instructions and description:
+
+```python
+from google.adk.agents.llm_agent import Agent
+
+root_agent = Agent(
+    name="weather_time_agent",
+    description=(
+        "Agent to answer questions about the time and weather in a city."
+    ),
+    instruction=(
+        "I can answer your questions about the time and weather in a city."
+    ),
+    tools=[get_weather, get_current_time],
+)
+```

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

@@ -0,0 +1,90 @@
+# 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 google.adk.agents.llm_agent import Agent
+
+
+def get_weather(city: str) -> dict:
+  """Retrieves the current weather report for a specified city.
+
+  Args:
+      city (str): The name of the city for which to retrieve the weather report.
+
+  Returns:
+      dict: status and result or error msg.
+  """
+  if city.lower() == "new york":
+    return {
+        "status": "success",
+        "report": (
+            "The weather in New York is sunny with a temperature of 25 degrees"
+            " Celsius (77 degrees Fahrenheit)."
+        ),
+    }
+  else:
+    return {
+        "status": "error",
+        "error_message": f"Weather information for '{city}' is not available.",
+    }
+
+
+def get_current_time(city: str) -> dict:
+  """Returns the current time in a specified city.
+
+  Args:
+      city (str): The name of the city for which to retrieve the current time.
+
+  Returns:
+      dict: status and result or error msg.
+  """
+  import datetime
+  import os
+  from zoneinfo import ZoneInfo
+
+  if "PYTEST_CURRENT_TEST" in os.environ:
+    return {
+        "status": "success",
+        "report": (
+            "The current time in New York is 2026-05-15 12:00:00 EDT-0400"
+        ),
+    }
+
+  if city.lower() == "new york":
+    tz_identifier = "America/New_York"
+  else:
+    return {
+        "status": "error",
+        "error_message": (
+            f"Sorry, I don't have timezone information for {city}."
+        ),
+    }
+
+  tz = ZoneInfo(tz_identifier)
+  now = datetime.datetime.now(tz)
+  report = (
+      f'The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}'
+  )
+  return {"status": "success", "report": report}
+
+
+root_agent = Agent(
+    name="weather_time_agent",
+    description=(
+        "Agent to answer questions about the time and weather in a city."
+    ),
+    instruction=(
+        "I can answer your questions about the time and weather in a city."
+    ),
+    tools=[get_weather, get_current_time],
+)

contributing/samples/core/quickstart/tests/time_ny.json

@@ -0,0 +1,84 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "What time is it in New York?"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "city": "New York"
+              },
+              "id": "fc-1",
+              "name": "get_current_time"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "get_current_time",
+              "response": {
+                "report": "The current time in New York is 2026-05-15 12:00:00 EDT-0400",
+                "status": "success"
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "The current time in New York is 2026-05-15 12:00:00 EDT-0400."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    }
+  ]
+}

contributing/samples/core/quickstart/tests/weather_ny.json

@@ -0,0 +1,84 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "What is the weather in New York?"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "city": "New York"
+              },
+              "id": "fc-1",
+              "name": "get_weather"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "get_weather",
+              "response": {
+                "report": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).",
+                "status": "success"
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit)."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    }
+  ]
+}

contributing/samples/core/quickstart/tests/weather_time_ny.json

@@ -0,0 +1,103 @@
+{
+  "events": [
+    {
+      "author": "user",
+      "content": {
+        "parts": [
+          {
+            "text": "What is the weather and time in New York?"
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-1",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": ""
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "functionCall": {
+              "args": {
+                "city": "New York"
+              },
+              "id": "fc-1",
+              "name": "get_weather"
+            }
+          },
+          {
+            "functionCall": {
+              "args": {
+                "city": "New York"
+              },
+              "id": "fc-2",
+              "name": "get_current_time"
+            }
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-2",
+      "invocationId": "i-1",
+      "longRunningToolIds": [],
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "functionResponse": {
+              "id": "fc-1",
+              "name": "get_weather",
+              "response": {
+                "report": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).",
+                "status": "success"
+              }
+            }
+          },
+          {
+            "functionResponse": {
+              "id": "fc-2",
+              "name": "get_current_time",
+              "response": {
+                "report": "The current time in New York is 2026-05-15 12:00:00 EDT-0400",
+                "status": "success"
+              }
+            }
+          }
+        ],
+        "role": "user"
+      },
+      "id": "e-3",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    },
+    {
+      "author": "weather_time_agent",
+      "content": {
+        "parts": [
+          {
+            "text": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit). The current time in New York is 2026-05-15 12:00:00 EDT-0400."
+          }
+        ],
+        "role": "model"
+      },
+      "finishReason": "STOP",
+      "id": "e-4",
+      "invocationId": "i-1",
+      "nodeInfo": {
+        "path": "weather_time_agent@1"
+      }
+    }
+  ]
+}