📚 首页 / 04-tool-use/labs / lab.md

模块 4 动手实验 — 工具使用

Lab 4.1–4.4 无需 key；Lab 4.5 可选需 key。预计 75–100 分钟。

Lab 4.1 — 回路模拟器改造（必做，无 key）

任务：运行并改造 examples/tool_loop.py：

  1. 跑通三条路径（正常 / 错误回传改道 / 人审拒绝），对照 README §2 的时序图逐步标注消息列表的变化。
  2. 新增工具 get_weather_forecast 的缺参调用剧情：Claude 传了空 location，应用校验 schema 后回传 is_error: true（"Missing required 'location' parameter"），观察 Claude 补参重试（参考官方"若调用无效，Claude 会重试 2–3 次自我修正"，来源: https://platform.claude.com/docs/en/agents-and-tools/tool-use/handle-tool-calls（访问于 2026-08-30））。
  3. 故意制造一个"格式违规"请求：在 tool_result 之前放 text block——写注释解释会发生什么（对照官方 400 文案："tool_use ids were found without tool_result blocks immediately after"）。

验收：能白板画出消息数组从第 0 步到结束的完整演进。

Lab 4.2 — 工具定义评审（必做，纸面）

任务：给下面这个"坏工具"写改版（依据 README §3 官方最佳实践）：

{"name": "db", "description": "Runs a database query.",
 "input_schema": {"type": "object", "properties": {"sql": {"type": "string"}}, "required": ["sql"]}}

要求改版包含：命名空间化命名、3–4 句 description（何时用/何时不用/返回什么/限制）、把裸 SQL 换成语义化参数、返回高信号结果（而不是全表行）。再回答：这个工具暴露给 auto 模式有什么安全风险？（提示：LLM 指令 ≠ 应用强制；模块 11）

Lab 4.3 — tool_choice 决策表（必做，纸面）

任务：填完下表并给每行一个业务例子：

需求tool_choice副作用要处理什么
客服自由决定查不查订单auto可能不调工具直接答（知识截止风险）
强制每个回答先检索知识库？无自然语言解释；messages 缓存作废
流水线第 2 步必须抽取实体？prefill assistant；无解释
用户闲聊回合禁止工具？——
并行调用导致订单重复创建？？

（依据: https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools（访问于 2026-08-30））

Lab 4.4 — 人审门设计（必做，纸面）

任务：为下列工具标注权限策略（直接执行 / 执行+审计 / 人审）并说明理由：

get_order update_order_address send_customer_email issue_refund bulk_reimport web_search

判据（README §6）：不可逆？高代价？低可解释性×高影响？合规？然后写人审 tool_result 的错误文案（要"有指导性"，让 Claude 能向用户解释被拒原因与替代路径）。

Lab 4.5 — 真实回路验证（可选，需 key）

任务：把 tool_loop.py 的 fake_claude 换成真实 Messages API 调用（SDK 或 urllib，key 从环境注入）：

  1. 用官方 get_weather 示例的 tools 定义发送请求，确认收到 stop_reason: "tool_use"。
  2. 执行后回传 tool_result，拿到最终回答。
  3. 试验 tool_choice: {"type": "any"}：观察响应是否直接是 tool_use 而没有解释文本。
  4. 连发两轮同样的 tools+system，第二轮观察 cache_read_input_tokens（tools 前缀被缓存）。

完成检查表

📚 目录