"""
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,                        # 天气查询工具
    ],
)