话说回来，

第 章：工具调用：让模型只提需求，服务端执行确定性工具

本章最终效果

上一章我们完成了 Today 和 Coach Chat 的行动闭环：前端或调用方发来使用者消息。Spring 后端补齐可信使用者上下文，再把请求交给 Python Agent Service。

这一章我们将进一步完善 Agent Service。引入 Tool Registry，让模型仅仅提出需求，而真正的计算和决策由后端安全、可测试的工具完成。

学完本章后你会得到以下成果：

• services/agent-service/app/tools.py 中定义了两个可被 Agent 调用的工具：
  • calculate_macro_target: 热量和三大营养素。
  • generate_training_plan: 根据目标、训练频率、器械与伤病标记生成训练结构。
• 所有工具参数先经过 Pydantic 校验，异常参数不会导致服务崩溃。
• 模型只能申请调用工具，由服务端白名单中的execute_tool 决定到底执行哪一个函数。
• tests/test_tools.py 锁住两条关键行为：
  • 减脂热量不应设计成极端节食。
  • 膝盖风险会触发低冲击训练降级。
• AgentService.chat 的工具调用链路更加清晰：
  • 第一次模型调用判断是否需要工具。
  • 服务端解析参数、白名单执行并记录 trace。
  • 第二次模型调用基于工具结果生成最终回答。

使用者痛点：

• 精准度与安全性冲突：- 模型直接给出的热量建议往往不准确或过度极端；使用者担心因错误建议导致健康风险或预算浪费。- 服务端才会被执行，- 使用者可以看到明确的安全提示。如“热量调整不超过估算维持热量的 %，避免极端节食”。可测试性缺失：- 没有单元测试时难以保证每一次计算都符合业务规则；一旦公式更改可能无声无息破坏程序。- 本章锁定主要原因，让功能变得可回归、可验证。话说回来，- 开发者可以快速定位问题源头，而不是在生产环境里排查错误。 lili>功能边界模糊：- 模型能自由写函数名，一旦暴露到后端可能出现未授权函数被执行风险。- 白名单机制确保只有预定义且审核过的函数才会被允许运行，从而降低攻击面和误操作概率。

复制规则 & 执行目录约定

本章节继续沿用前几章复制标记：

• : 在终端复制运行。其实，: 把完整代码复制到指定文件。: 用于理解错误写法或最小版本，不要写进项目中。

  提示： 如果你是从空目录跟着课程做，把上面绝对方法替换成自己的项目方法即可。

  阶段的观点是，先理解为什么需要 Tool Registry

  1️⃣ 模型直接给出数值存在误差与极限风险 2️⃣ 无法在单元测试中锁定业务逻辑 3️⃣ 难以实现可复用、安全可审计的接口
  
  

  没有工具时 Coach Agent 的回答示例

  User: 我 175cm 80kg 想减脂但不想掉力量。一周练             

  AIGC Reply: 你每天吃  .

  这段代码暴露的问题

  • Pydantic 参数校验缺失： 没有检查体重范围是否合理；未限制训练天数，未判断目标类型。

• 开放式动态调用： 如果直接使用 globals 或 eval 调用。则任何恶意输入都可能导致任意代码执行，从而破坏程序安全边界。
• OpenAI-compatible 工具声明缺失： 模型无法知道哪些函数可以被调用。也无法传递正确格式化参数 JSON，所以无法正常触发工具链路。
• 统一入口缺失： 因为业务增长。每个新功能都需手动集成到现有流程中，维护成本剧增且易出错。说起来，

完整 Tool Registry 链路图

1. TOOL_SCHEMAS 将所有可调用工具及其参数结构以 JSON Schema 发布给 LLM。让它了解能做什么还有需要哪些信息。
• model 接收到 toolcalls 后解析 name 与 args，接下来交给 executetool 执行。
• execute_tool 对 args 使用 Pydantic 校验边界，并返回结构化结果或者错误码。
• 将 tool result 包装为 role=tool 消息插回对话队列，让 LLM 在下一轮得到可靠上下文。

实际命令验证脚本

cd services/agent-service

PYTHONPATH=. pytest tests/test_tools.py

使用者痛点

痛点	为什么关键	本章节方法
精确度与安全	错误建议可能导致健康损害或资金浪费	使用 Pydantic 校验 + 预设 safetyNote
不可测性	难以验证逻辑正确性	单元测试锁定关键业务规则
功能边界模糊	任意函数被执行带来安全隐患	白名单 execute_tool + 限制动态加载

---

阶段 ：从普通函数长出 tools.py

再看第一步先，定义 Pydantic 参数边界

python class MacroTargetArgs: height_cm: float = Field weight_kg: float = Field 从goal来看，str training_days: int = Field activity_level : str = "moderate"

注解 - gt / lt 等限定字段防止无效输入 - 默认值提供健壮性

说到接下来，为 LLM 声明 OpenAI-compatible 工具 Schema

python TOOL_SCHEMAS : list] =

注解 - 给 LLM 明确说明可以请求哪些功能 - 不含业务细节，仅描述形状

：实现确定性计算逻辑

python def calculate_macro_target -> dict: parsed = MacroTargetArgs.model_validate multiplier = ... # based on activity_level maintenance = int deficit_factor = -0.15 if 'fat' in parsed.goal.lower else 0. calories = int) protein_g = int fat_g = int carbs_g = max / ...)) return {"calories": calories。"proteinG": protein_g,"carbsG": carbs_g,"fatG": fat_g,"safetyNote":"热量调整不超过估算维持热量的 %，避免极端节食"}

从第四步来看，统一白名单入口 execute_tool

python def execute_tool -> dict: 再看try，if name=="calculate_macro_target": return calculate_macro_target if name=="generate_training_plan": return generate_training_plan except ValidationError as exc: return {"error":"tool_validation_failed","details":exc.errors} return {"error":"unknown_tool","tool":name}

注解 - 防止任意函数被触发 - 捕获校验错误并返回结构化信息

---

阶段 ：用单元测试锁住关键行为

python from app.tools import calculatemacrotarget,generatetrainingplan

def testmacrotargetlimitsdeficit: result = calculatemacrotarget({ "heightcm":170,"weightkg":80,"goal":"减脂但不掉力量","trainingdays":5}) assert result == expectedcaloriesvalue assert result == expectedprotein_value assert "极端节食" in result

def testtrainingplandowngradeskneerisk: result = generatetrainingplan({ 说到"goal"，"减脂","trainingdays":5,"injury_flags":}) assert any assert "疼痛" in result

为什么这样做？ - 确保主要公式始终如初 - 验证伤病降级机制正确触发

---

阶段 ：理解 AgentService 如何接入 Tool Registry

python first = await self.client.chat

if first.tool_calls: messages.append

for call in first.toolcalls: function=dict or {}) name=function.get or "" rawargs=function.get or "{}" args=json.loads if isinstance else raw_args

 result=execute_tool
messages.append({
从"role"来看。"tool",...
})

关键步骤 1. 第一轮 chat 给 LLM 工具列表。2. 若有 tool_calls 则解析并通过 execute_tool 执行。3. 将结果作为 消息追加回对话，以便第二轮 chat 使用。不过，

---

常见报错与修复

• ModuleNotFoundError: app not found. 通常是因为没进入 services/agent-service 或忘记设置 PYTHONPATH。 cd services/agent-service && PYTHONPATH=. pytest tests/test_tools.py。
• ValidationError: 参数非法. 直接调用 tool 函数时会抛异常，但=""> service.py<\/pre> i18k\u2028style="color:black"\u2028width="100%\"\u2028border="0\"\u2028cellspacing="0"\u2028cellpadding="\u2029\t\r \r\u2029\t\t\r\u2029\t\t\r\u2029 \u201c \t\t \r \t“ \t \t\t\r “ xd;c\xA，\t\t\r \r xd;c\xA，不过，\

  任务项<\/th>	预期结果<\/th>
  $ PYTHONPATH=. pytest tests/testtools.py<\/pre>	所有断言通过没有异常<\/td>
  $ PYTHONPATH=. pytest tests/test
  AgentService 主分支正常。无网络依赖<\/td>
  手动模拟案例 normal macro invalid weight unknown tool	分别输出对应错误码与成功结果<\/td>

  \r\r \r\r \r\r

  }