过境笔记

主题

Function Calling Schema：让模型别只“想调用”，还要按契约调用 ​

今天先记住 ​

Function Calling schema 不是给模型看的“说明书装饰”，而是 Agent 和工具之间的调用契约。它要把一句模糊意图，压成工具能执行、系统能校验、失败后能定位的问题。

它在大地图里的位置 ​

还是这条链路：

txt
用户目标
  -> 上下文 / 记忆
  -> 规划 / 决策
  -> 工具调用 / 外部系统
  -> 执行 / 观察结果
  -> 评估 / 修正
  -> 最终输出

前面讲 MCP 时说的是“外部系统如何暴露能力”。今天的 schema 更贴近一次具体工具调用：Agent 决定要调用哪个工具后，必须把参数按固定形状交出去。否则模型说“查一下今天的文章”，工具却不知道是查哪个目录、哪一天、是否允许写文件。

它到底是什么 ​

Function Calling schema 通常是一段结构化定义：工具名、用途说明、参数字段、字段类型、必填项、可选枚举、默认边界。比如 publish_lesson 需要 date、title、dryRun，其中 date 必须是 YYYY-MM-DD，dryRun 必须是布尔值。

它的重点不是让输出“长得像 JSON”，而是让调用能被程序检查。模型可以负责理解意图，schema 负责把意图卡进可执行的窄门。

为什么 Agent 里会用到它 ​

Agent 一旦能动手，就会遇到两类错误：一类是选错工具，另一类是选对工具但参数错。schema 主要管第二类。

比如用户说“把明天的提醒挪到晚上”。如果工具参数里只有一个自由文本 content，模型可能把“晚上”写成一段自然语言，调度系统无法判断具体时间。如果 schema 要求 runAt 是 ISO 时间，timezone 是枚举，系统就能在执行前拦下缺字段、错格式和歧义时间。

这不是抽象的“更可靠”，而是把失败提前：从“工具已经乱执行了”提前到“参数校验没过，回到 Agent 让它补问或修正”。

怎么判断它有没有用 ​

如果工具会改变外部状态，比如发消息、写文件、提交代码、创建日程，schema 必须尽量窄，不能只给一个万能字符串。

如果参数会影响权限边界，比如 path、branch、recipient、amount，要用枚举、格式限制或上层白名单缩小范围。

如果工具只是只读查询，而且输入天然简单，schema 可以轻一些；过度复杂会让模型更容易填错。

如果你发现 Agent 经常“差一点就调对了”，先看 schema：字段名是否像人话，必填项是否清楚，描述里有没有写出禁止事项和边界。

最近冒出来的词 ​

今天不追新词，先把主线概念讲稳。

一个小例子 ​

txt
Input:
用户说：“生成 2026-07-24 的 AI Agent Daily，构建通过后推送。”

Schema:
tool: create_daily_lesson
required:
  date: string, format YYYY-MM-DD
  series: enum ["ai-agent"]
  publish: boolean

Process:
1. 模型从用户目标里抽取 date=2026-07-24、series=ai-agent、publish=true。
2. 系统校验 date 格式和 series 枚举。
3. 工具只在 docs/ai-agent 目录下写入对应日期文件。

Output:
生成 docs/ai-agent/2026-07-24.md；
如果 date 写成“今天”，校验失败，Agent 必须先换成明确日期再执行。

这个例子可以拿去判断真实系统：好 schema 会让“能不能执行”在执行前变清楚；坏 schema 会把歧义拖到工具内部，最后只剩一条难查的失败日志。

常见误区 ​

  1. 以为有 JSON 就等于有 schema。JSON 只是格式，schema 才是契约。
  2. 以为字段越多越专业。字段越多，模型越容易漏填、乱填，除非每个字段都对应真实决策。
  3. 以为 schema 能替代权限。schema 能限制形状，不能决定用户是否有权执行。
  4. 以为描述可以随便写。工具描述含糊时，模型会按自己的语感猜，猜错就是系统问题。

今天自测 ​

  1. Function Calling schema 主要防的是“选错工具”，还是“参数错了也执行”？
  2. 为什么会写文件的工具不适合只收一个 instruction 字符串？
  3. 你会怎样给“创建提醒”这个工具设计最少但够用的字段？