init

ADKLearning/google-adk-tutorial/code/hello_world.py

@@ -0,0 +1,137 @@
+"""
+Google ADK Hello World 示例
+一个带有自定义工具的完整 Agent 示例
+
+对应教程：第02章 - 快速开始：Hello World
+运行方式：adk run hello_world（将此文件放在 hello_world/agent.py 中）
+"""
+
+# 导入 ADK 的 Agent 类
+from google.adk.agents import Agent          # Agent 是 LlmAgent 的别名
+
+# 导入标准库：日期时间处理
+import datetime                            # 用于获取当前时间
+from zoneinfo import ZoneInfo              # 用于处理时区信息
+
+
+# ========================================
+# 定义自定义工具函数
+# ========================================
+
+def get_current_time(city: str) -> dict:
+    """
+    获取指定城市的当前时间
+
+    这个函数会被 ADK 自动转换为工具（FunctionTool），
+    Agent 可以在对话中调用这个工具来获取时间信息。
+
+    Args:
+        city (str): 需要查询时间的城市名称，例如"北京"、"东京"、"纽约"
+
+    Returns:
+        dict: 包含状态和结果的字典
+            - status: "success" 或 "error"
+            - report: 时间信息或错误消息
+    """
+    # 定义城市到时区的映射字典
+    city_timezone_map = {                    # 常见城市对应的时区
+        "北京": "Asia/Shanghai",             # 北京使用上海时区
+        "上海": "Asia/Shanghai",             # 上海使用上海时区
+        "广州": "Asia/Shanghai",             # 广州使用上海时区
+        "深圳": "Asia/Shanghai",             # 深圳使用上海时区
+        "东京": "Asia/Tokyo",               # 东京时区
+        "首尔": "Asia/Seoul",               # 首尔时区
+        "纽约": "America/New_York",         # 纽约时区
+        "伦敦": "Europe/London",            # 伦敦时区
+        "巴黎": "Europe/Paris",             # 巴黎时区
+        "洛杉矶": "America/Los_Angeles",    # 洛杉矶时区
+    }
+
+    # 查找城市对应的时区标识符
+    tz_identifier = city_timezone_map.get(city)  # 从字典中获取时区
+
+    # 如果找不到该城市的时区信息
+    if not tz_identifier:                    # 检查是否找到
+        return {                            # 返回错误信息
+            "status": "error",              # 状态标记为错误
+            "error_message": f"未找到'{city}'的时区信息，请尝试其他城市。"  # 错误描述
+        }
+
+    # 根据时区标识符创建时区对象
+    tz = ZoneInfo(tz_identifier)            # 创建 ZoneInfo 时区对象
+
+    # 获取该时区的当前时间
+    now = datetime.datetime.now(tz)         # 获取指定时区的当前时间
+
+    # 格式化时间字符串
+    time_str = now.strftime(                # 将时间格式化为字符串
+        "%Y-%m-%d %H:%M:%S %Z%z"           # 格式：年-月-日 时:分:秒 时区
+    )
+
+    # 返回成功结果
+    return {                                # 返回包含时间信息的字典
+        "status": "success",                # 状态标记为成功
+        "city": city,                       # 城市名称
+        "time": time_str                    # 格式化后的时间字符串
+    }
+
+
+def get_weather(city: str) -> dict:
+    """
+    获取指定城市的天气信息（模拟数据）
+
+    Args:
+        city (str): 城市名称
+
+    Returns:
+        dict: 包含天气信息的字典
+    """
+    # 模拟天气数据（实际应用中应调用真实天气 API）
+    weather_data = {                        # 模拟天气数据库
+        "北京": {"temp": "25°C", "condition": "晴天", "humidity": "45%"},  # 北京
+        "上海": {"temp": "28°C", "condition": "多云", "humidity": "65%"},  # 上海
+        "广州": {"temp": "32°C", "condition": "雷阵雨", "humidity": "80%"}, # 广州
+    }
+
+    # 查找城市天气数据
+    data = weather_data.get(city)           # 从字典中获取天气数据
+
+    # 如果找不到该城市的天气
+    if not data:                            # 检查数据是否存在
+        return {                            # 返回错误信息
+            "status": "error",              # 状态：错误
+            "error_message": f"未找到'{city}'的天气信息"  # 错误描述
+        }
+
+    # 返回成功结果
+    return {                                # 返回天气信息
+        "status": "success",                # 状态：成功
+        "city": city,                       # 城市名称
+        "temperature": data["temp"],        # 温度
+        "condition": data["condition"],     # 天气状况
+        "humidity": data["humidity"],       # 湿度
+    }
+
+
+# ========================================
+# 定义 Agent（ADK 入口点）
+# ========================================
+
+# root_agent 是 ADK 自动识别的入口变量
+# 变量名必须是 root_agent，不能修改
+root_agent = Agent(
+    name="hello_agent",                     # Agent 的唯一标识名称
+    model="gemini-2.0-flash",               # 使用 Gemini 2.0 Flash 模型
+    description="一个能查询城市时间和天气的友好助手。",  # Agent 的描述
+    instruction=(                           # 系统指令（多行字符串）
+        "你是一个友好的助手，可以帮助用户查询世界各城市的当前时间和天气。\n"
+        "当用户询问某个城市的时间时，使用 get_current_time 工具来获取。\n"
+        "当用户询问某个城市的天气时，使用 get_weather 工具来获取。\n"
+        "如果工具返回错误，请友好地告知用户并建议尝试其他城市。\n"
+        "回复时请使用中文，语气亲切友好。"
+    ),
+    tools=[                                 # 将自定义函数注册为 Agent 的工具
+        get_current_time,                   # 时间查询工具
+        get_weather,                        # 天气查询工具
+    ],
+)