用 Google ADK 2.x 搭一个会调用工具的 Agent（Python 上手，含可视化调试）

# 建议用虚拟环境
python -m venv .venv
# Windows: .venv\Scripts\activate
source .venv/bin/activate

pip install google-adk

# 脚手架：生成一个名为 my_agent 的 Agent 项目
adk create my_agent

生成出来的目录大致是这样（不同小版本文件名可能略有差异，以实际输出为准）：

my_agent/
├── __init__.py     # 声明包
├── agent.py        # 你的 Agent 定义（核心）
└── .env            # 模型与密钥配置

ADK 最省事的一点：工具就是普通 Python 函数。它读函数名、类型注解和 docstring，自动生成模型能看懂的调用说明。打开 agent.py，写成下面这样：

# my_agent/agent.py
from google.adk.agents import Agent

def get_current_time(city: str) -> dict:
    """返回指定城市的当前时间。

    Args:
        city: 城市名，例如 "Beijing"。
    """
    # 教程里用占位数据；真实项目换成时区库或接口调用
    return {"status": "success", "city": city, "time": "10:30"}

def convert_currency(amount: float, rate: float) -> dict:
    """按给定汇率把金额换算成目标币种。"""
    return {"status": "success", "result": round(amount * rate, 2)}

# 必须叫 root_agent —— ADK 靠这个名字找到入口
root_agent = Agent(
    model="gemini-flash-latest",   # 模型名以官方文档为准
    name="root_agent",
    description="一个能查时间、算汇率的小助手。",
    instruction=(
        "你是一个务实的助手。"
        "查时间用 get_current_time，换算金额用 convert_currency。"
        "工具没返回结果时，如实说明，不要编造数据。"
    ),
    tools=[get_current_time, convert_currency],
)

在 my_agent/.env 里填上你的 Gemini Key（从 Google AI Studio 拿，免费额度够练手）：

# my_agent/.env
GOOGLE_API_KEY=你的_gemini_api_key

# 在「包含 my_agent 目录」的上级目录执行
adk run my_agent

# 出现输入提示后，直接问：
#   北京现在几点？
# 观察它是否会调用 get_current_time 工具

这是 ADK 最值得用的功能：一个本地 Web 界面，聊天框旁边直接展示完整的事件轨迹——模型调了哪个工具、传了什么参数、返回了什么、最终答案怎么拼出来的。

# 同样在上级目录执行
adk web --port 8000

# 浏览器打开 http://localhost:8000
# 左侧选择 my_agent，右侧对话
# 每条回复旁边可展开事件轨迹：工具调用 → 参数 → 返回值 → 组装答案

跑通之后，按这三步加固：

1. 在 instruction 里写红线：能做什么、绝对不能做什么、不确定时怎么办。约束写得越明确，Agent 越稳。
2. 一个工具只做一件事：把「查订单 + 改订单」拆成两个工具，权限和审计都更清晰；写操作单独命名，方便加人工确认。
3. 想清楚部署目标：ADK 支持托管运行时、Cloud Run、GKE 或任意容器平台。本地跑通后再决定部署方式，别过早纠结。