# 工具本体：三个普通函数（真实项目里换成调真 API；这里先用假数据跑通）
def get_weather(city: str) -> dict:
    return {"city": city, "weather": "小雨", "temp": 18}      # 假装查了天气

def check_stock(hotel: str, date: str) -> dict:
    return {"hotel": hotel, "date": date, "rooms_left": 3}    # 假装查了库存

def send_email(to: str, subject: str, body: str) -> dict:
    return {"status": "sent", "to": to}                       # 假装发了邮件

// 给每个工具配一张"说明便签"（schema），交给模型看
[
  {
    "name": "get_weather",
    "description": "查询某个城市当前天气，用户问天气/要不要带伞时调用",
    "parameters": {
      "type": "object",
      "properties": { "city": {"type": "string", "description": "城市名，如 北京"} },
      "required": ["city"]
    }
  },
  {
    "name": "send_email",
    "description": "发送一封邮件。属危险操作，执行前应先向用户确认",
    "parameters": {
      "type": "object",
      "properties": {
        "to":      {"type": "string", "description": "收件人邮箱"},
        "subject": {"type": "string"},
        "body":    {"type": "string", "description": "邮件正文"}
      },
      "required": ["to", "subject", "body"]
    }
  }
]

# 主循环骨架（伪代码级简化，看懂流程即可）
tools = {"get_weather": get_weather, "check_stock": check_stock, "send_email": send_email}
messages = [{"role": "user", "content": "我明天去上海出差，天气咋样？"}]

for _ in range(5):                               # 循环上限：最多转 5 圈，防死循环（Day32）
    resp = client.chat.completions.create(
        model="gpt-4o", messages=messages, tools=SCHEMAS)   # 把便签一起发过去
    call = resp.choices[0].message.tool_calls    # 模型是否要调工具？
    if not call:                                 # 不调了 → 说明它要给最终答案
        print(resp.choices[0].message.content); break
    name = call[0].function.name                 # 它想调哪个
    args = json.loads(call[0].function.arguments)# 它给的参数
    result = tools[name](**args)                 # ③你的代码真去执行
    messages.append({"role": "tool", "content": json.dumps(result)})  # ④回填结果

# 铁律1：工具内部 try/except，把错误"变成返回值"而不是崩溃（Day05 + Day30）
def check_stock(hotel: str, date: str) -> dict:
    try:
        # ... 真去调库存 API ...
        return {"ok": True, "rooms_left": 3}
    except Exception as e:
        return {"ok": False, "error": f"库存系统暂时打不通：{e}"}  # ← 结构化错误，不 raise
# 模型收到 {"ok": False, ...} 会知道"这步没成"，可改口"稍后重试"或换工具

# 铁律2：危险动作加"审批闸"——执行前先问用户（人在环，Day41/Day54）
def send_email(to, subject, body, confirmed=False):
    if not confirmed:
        return {"ok": False, "need_confirm": True,           # 先不发，把草稿退回请示
                "preview": f"将发给 {to}：{subject}"}
    # 只有 confirmed=True 才真的发
    return {"ok": True, "status": "sent"}

# 评测骨架：每条用例记录"该调的工具"和"该完成的事"
golden = [
  {"q": "上海明天天气？",        "expect_tool": "get_weather",  "expect_arg": "上海"},
  {"q": "把行程发给张总",        "expect_tool": "send_email",   "need_confirm": True},
  {"q": "外滩饭店后天还有房吗？", "expect_tool": "check_stock",  "expect_arg": "外滩饭店"},
]
right_tool = 0
for c in golden:
    tool_name, args = run_agent_first_call(c["q"])   # 跑一次，看它第一步选了啥工具
    ok = (tool_name == c["expect_tool"])             # 工具选对没
    right_tool += ok
    print(("✅" if ok else "❌"), c["q"], "→", tool_name)
print(f"工具选对率：{right_tool}/{len(golden)} = {right_tool/len(golden):.0%}")

# 可复用项目骨架
tool-agent/
├── tools/
│   ├── weather.py      # 查天气工具 + 它的错误处理
│   ├── stock.py        # 查库存工具
│   └── email.py        # 发邮件工具（含审批闸）
├── schemas.py          # 所有工具的"说明便签"（L02）
├── agent.py            # 主循环：选工具→执行→回填（L03）
├── app.py              # FastAPI 暴露 /chat 接口（Day09）
├── eval.py             # 评测：工具选对率 + 任务完成率（L05）
├── golden.json         # 评测用例
├── requirements.txt
├── Dockerfile          # 打包（Day57）
└── README.md           # 说明 + 效果数字 + demo（Day65）

✋ 动手 10 分钟：写两个假工具 + 一个"手动主循环"

不接真 API、不用大模型,先用手模拟一遍主循环,把流程刻进肌肉:

# 1) 两个假工具，其中"发邮件"带审批闸
def get_weather(city): return {"ok": True, "weather": "小雨", "temp": 18}
def send_email(to, body, confirmed=False):
    if not confirmed:
        return {"ok": False, "need_confirm": True, "preview": f"给{to}：{body}"}
    return {"ok": True, "status": "sent"}

# 2) 你来扮演"模型"，手动决定调哪个工具（体会主循环的每一步）
print(get_weather("上海"))                         # 第1圈：查天气
draft = send_email("张总", "行程见附件")            # 第2圈：想发邮件 → 被审批闸拦下
print(draft)                                       # need_confirm=True，先给你看草稿
print(send_email("张总", "行程见附件", confirmed=True))  # 你点头后才真发

能说清"每一步是模型在决策还是我的代码在执行、哪一步被审批闸拦住",今天就通关了。