以下数字为教学示例,不构成对任何真实系统或供应商的承诺。
“模型说要重启服务"和"模型把重启服务这个调用构造对"之间隔着一段很容易出错的路径:意图里的槽位要落到参数上,参数要过类型和取值校验,缺的和错的要分门别类地报出来。这段路径做不好,Agent 会用"半成品调用"打到真实系统上——参数缺一半、类型错一个、值超范围,系统照单执行。
这一节把参数构造拆成四道关:未知参数、必填缺失、类型转换、取值约束。实验对一组固定输入做分类,统计错误发生在哪一关,并演示"失败时返回空参数,不带病调用”。
从意图到调用的四道关
| 关 | 检查什么 | 典型错误 |
|---|---|---|
| 未知参数 | 参数名在不在 schema 里 | 模型编了个 force |
| 必填缺失 | 必需的参数给没给 | 重启没说服务名 |
| 类型转换 | 值能不能无损变成声明类型 | 把 30 当整数、"yes" 当布尔 |
| 取值约束 | 值在不在枚举/范围里 | 环境不是 staging/prod,延时超上限 |
四道关是串联的:前一道不过,后一道没有意义。未知参数说明模型编了字段,后面三关查的是"已有的字段对不对"。分类的价值在于归因:缺参数多半是意图提取问题,类型错多半是槽位映射问题,取值越界多半是约束没注入提示。
必填缺失 vs 缺省
“没给"分两种情况,必须分开:
- 必填缺失:schema 声明了
required,没给就是错误,不能猜; - 可选缺省:schema 有默认值,没给就用默认,这是设计好的行为。
区分两者靠 schema,不靠模型。模型不该负责"这个参数要不要”——schema 说了算。默认值的使用要显式:实验里 reason 缺省 "unspecified"、dry_run 缺省 True,调用仍然成立,但每个缺省都写进了结果,可审计。
只做无损转换
类型转换的原则是"无损":字符串 "30" 能转成整数 30,字符串 "thirty" 不能;布尔 "true" 能转成 True,"yes" 不能。转换器只做确定性的、无损的映射,不做猜测。
“不做猜测"有实际含义:"thirty" → 30 需要语义理解,交给模型去填槽位可以,交给运行时转换器不行。转换器猜错了,错误会带着"看起来合法"的样子进入系统。无损转换把"模糊值"挡在调用之前,而不是靠运气消化它。
取值约束:枚举与范围
参数不只是"类型对”,还要"值合法"。枚举参数要在声明的选项里(环境只能是 staging/prod);数值参数要在范围内(延时 0–3600 秒)。约束检查在类型转换之后进行,因为只有转成正确的类型,范围比较才有意义。
约束错误有两类根源:模型不知道约束(提示里没写),或模型知道但生成错了。分类统计能区分这两种:如果越界错误集中在某几个参数,多半是提示缺约束;如果分散,多半是生成噪声。
最小实验:错误分类
下面的实验对一组固定输入做参数构造,restart_service 和 search_docs 两个工具各带声明好的参数。构造失败时返回空 args 与错误清单,而不是半成品调用。
# file: agp_lab/args_build.py | write
# tier: 3
# verify: python3 -m unittest tests.test_args_build
"""参数构造:槽位、类型、缺省与校验。
把自然语言意图里的槽位变成一次工具调用,中间要经过四道关:未知参数、
必填缺失、类型转换、取值约束。任何一关失败都不应产生“半成品调用”。
实验对一组固定输入做分类,统计错误发生在哪一关。
"""
from __future__ import annotations
from dataclasses import dataclass
@dataclass(frozen=True)
class Param:
name: str
kind: str
required: bool = True
default: object = None
minimum: int | None = None
maximum: int | None = None
choices: tuple[str, ...] = ()
@dataclass(frozen=True)
class Tool:
name: str
params: tuple[Param, ...]
@dataclass(frozen=True)
class BuildError:
kind: str
field: str
detail: str
@dataclass(frozen=True)
class BuildResult:
ok: bool
args: dict[str, object]
errors: tuple[BuildError, ...]
RESTART = Tool(
"restart_service",
(
Param("service", "str"),
Param("environment", "enum", choices=("staging", "prod")),
Param("reason", "str", required=False, default="unspecified"),
Param("delay_seconds", "int", required=False, default=0, minimum=0, maximum=3600),
Param("dry_run", "bool", required=False, default=True),
),
)
SEARCH = Tool(
"search_docs",
(
Param("query", "str"),
Param("top_k", "int", required=False, default=3, minimum=1, maximum=20),
Param("include_archived", "bool", required=False, default=False),
),
)
def coerce(value: object, param: Param) -> object:
"""把槽位值转成声明类型;只做无损转换,不做猜测。"""
if param.kind == "str":
if not isinstance(value, str):
raise ValueError(f"需要 str,收到 {type(value).__name__}")
return value
if param.kind == "int":
if isinstance(value, bool) or not isinstance(value, (int, str)):
raise ValueError(f"需要 int,收到 {type(value).__name__}")
try:
return int(value.strip()) if isinstance(value, str) else value
except ValueError as exc:
raise ValueError(f"{value!r} 不是整数") from exc
if param.kind == "bool":
if isinstance(value, bool):
return value
if isinstance(value, str) and value.strip().lower() in ("true", "false"):
return value.strip().lower() == "true"
raise ValueError(f"{value!r} 不是布尔值")
if param.kind == "enum":
if not isinstance(value, str):
raise ValueError(f"需要字符串枚举,收到 {type(value).__name__}")
return value
raise ValueError(f"未知参数类型: {param.kind}")
def build(tool: Tool, raw: dict[str, object]) -> BuildResult:
"""构造并校验参数;失败时返回空 args,避免带病调用。"""
errors: list[BuildError] = []
args: dict[str, object] = {}
declared = {param.name: param for param in tool.params}
for name in raw:
if name not in declared:
errors.append(BuildError("unknown_argument", name, "未在工具 schema 中声明"))
for param in tool.params:
if param.name not in raw:
if param.required:
errors.append(BuildError("missing_required", param.name, "缺少必填参数"))
else:
args[param.name] = param.default
continue
try:
value = coerce(raw[param.name], param)
except ValueError as exc:
errors.append(BuildError("type_error", param.name, str(exc)))
continue
if param.kind == "enum" and value not in param.choices:
errors.append(
BuildError("invalid_choice", param.name, f"{value!r} 不在 {param.choices}")
)
continue
if param.kind == "int":
if param.minimum is not None and value < param.minimum:
errors.append(
BuildError("out_of_range", param.name, f"{value} < {param.minimum}")
)
continue
if param.maximum is not None and value > param.maximum:
errors.append(
BuildError("out_of_range", param.name, f"{value} > {param.maximum}")
)
continue
args[param.name] = value
if errors:
return BuildResult(False, {}, tuple(errors))
return BuildResult(True, args, ())
CASES = (
(RESTART, {"service": "checkout", "environment": "prod", "delay_seconds": "30"}),
(RESTART, {"environment": "prod"}),
(RESTART, {"service": "checkout", "environment": "prod", "delay_seconds": "thirty"}),
(RESTART, {"service": "checkout", "environment": "production"}),
(RESTART, {"service": "checkout", "environment": "prod", "delay_seconds": "7200"}),
(RESTART, {"service": "checkout", "environment": "prod", "force": "true"}),
(RESTART, {"service": "checkout", "environment": "prod", "dry_run": "yes"}),
(SEARCH, {"query": "refund policy", "top_k": "5"}),
(SEARCH, {"query": 42}),
(SEARCH, {"top_k": "5"}),
(SEARCH, {"query": "refund policy", "top_k": "0"}),
(SEARCH, {"query": "refund policy", "include_archived": "true"}),
)
def summarize(results: list[BuildResult]) -> dict[str, int]:
counts = {"ok": 0}
for result in results:
if result.ok:
counts["ok"] += 1
continue
counts[result.errors[0].kind] = counts.get(result.errors[0].kind, 0) + 1
return counts
if __name__ == "__main__":
results = [build(tool, raw) for tool, raw in CASES]
for index, ((tool, _), result) in enumerate(zip(CASES, results), start=1):
status = "ok" if result.ok else result.errors[0].kind
print(f"{index:>2} {tool.name:<16}{status}")
print()
for kind, count in sorted(summarize(results).items()):
print(f"{kind:<18}{count}")
print()
print("built:", results[0].args)
运行:
cd private/labs/agp-lab
python3 -m agp_lab.args_build
输出:
1 restart_service ok
2 restart_service missing_required
3 restart_service type_error
4 restart_service invalid_choice
5 restart_service out_of_range
6 restart_service unknown_argument
7 restart_service type_error
8 search_docs ok
9 search_docs type_error
10 search_docs missing_required
11 search_docs out_of_range
12 search_docs ok
invalid_choice 1
missing_required 2
ok 3
type_error 3
out_of_range 2
unknown_argument 1
built: {'service': 'checkout', 'environment': 'prod', 'reason': 'unspecified', 'delay_seconds': 30, 'dry_run': True}
这张表有三个要点。
12 个输入里只有 3 个直接成功。 失败集中在前四类,每类都有真实样本:编造的 force(unknown_argument)、没给服务名(missing_required)、"thirty" 转不成整数(type_error)、"production" 不在枚举里(invalid_choice)、"7200" 超范围(out_of_range)。模型生成的调用默认是不干净的,参数构造的责任是把它过滤干净。
成功的那次是"缺省补齐 + 类型转换"的样板。 第 12 行的 built 结果:输入的 "30" 被转成整数 30;没给 reason、dry_run,分别补上 "unspecified" 和 True。注意 dry_run 默认是 True——这次"重启"默认是演练,不是真重启。这个设计让安全参数默认偏保守,是参数构造里的一个独立决策。
失败时不返回半成品。 所有失败构造都返回空 args,错误清单列出来。这意味着下游可以确定:ok=False 就一定没有调用发生。系统层面就少了一类"参数不全但执行了"的故障——这是"不带病调用"的架构收益。
错误分类怎么用
统计错误类别不是为了报告,而是为了归因修复:
| 错误类别 | 多数归因 | 修复方向 |
|---|---|---|
| unknown_argument | 模型编造字段 | 收窄输出格式、加约束 |
| missing_required | 槽位提取漏了 | 提示里强调必填、追问 |
| type_error | 槽位映射错误 | 转换器 + 让模型先转好格式 |
| out_of_range | 约束没注入 | 把枚举/范围写进提示 |
| invalid_choice | 约束没注入 | 同上 |
每类错误对应不同的修复点,混在一起看"参数错误率"就分不清该改哪。
架构含义
参数构造对架构有三个直接约束:
- schema 是唯一真相。 参数名、必填、类型、枚举、范围都声明在 schema 里,模型和运行时共用。
- 失败不带病调用。 任何一关失败都返回空参数,不产生半成品调用。
- 缺省要显式。 每个被使用的默认值写进结果,调用可审计、可回放。
第 1 条决定了其余:schema 不完整,模型就会编参数,运行时就会猜约束。schema 是参数构造的地基。
架构判据
| 判据 | 合格的样子 | 不合格的样子 |
|---|---|---|
| 四关齐全 | 未知/缺失/类型/取值都检查 | 只查类型 |
| 无损转换 | 只做确定性映射 | 语义猜测转类型 |
| 失败无调用 | 错误时返回空参数 | 半成品继续执行 |
| 缺省显式 | 默认值写入结果 | 默认值不可见 |
| 错误分类 | 按关统计可归因 | 只报"构造失败" |
“失败无调用"是底线判据。参数构造这道关存在的意义,就是保证系统只看到合法的调用;做不到这一点,后续的幂等、重试、审计全部建立在沙滩上。
小结
- 参数构造经过四道关:未知参数、必填缺失、类型转换、取值约束。
- 必填缺失与可选缺省分开:schema 决定要不要,模型不负责。
- 类型转换只做无损、确定性映射,不做语义猜测。
- 枚举与范围是取值约束,类型转换之后才比较。
- 模型生成的调用默认不干净,参数构造的责任是过滤干净。
- 任何一关失败都返回空参数:系统只看到合法调用。
阅读导航:上一节:10.1 工具选择:能力、成本与风险 · 下一节:10.3 放弃与澄清:什么时候不该调用 。
常见错误与边界
- 只查类型。 缺必填、编字段、越界全漏过,半成品照样执行。
- 转换器做猜测。
"thirty"→30交给运行时,错误会以合法形态进入系统。 - schema 不完整。 缺枚举和范围,模型必然编参数、约束必然失效。
- 失败继续执行。 参数不全还调用,下游无法判断调用是否真实发生。
- 缺省不可见。 默认值悄悄用掉,调用记录无法审计。
- 只报构造失败。 不按关分类,就无法归因到提示、转换器还是 schema。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。