AI Agent / 系统课时
校验工具参数
校验工具参数
工具参数来自模型生成结果,不能因为格式像 JSON 就直接信任。执行前应依次检查必填项、数据类型、取值范围和调用权限,只有全部通过才进入真实工具函数,从而把输入错误和越权请求挡在业务逻辑之外。
学习目标
- 为工具定义可执行前检查的参数规则
- 区分缺失、类型错误、范围错误和权限不足
- 让校验失败返回稳定错误,而不是触发工具副作用
把校验放在执行之前
参数校验的顺序应从便宜、确定的检查开始:先确认字段是否存在,再检查类型和范围,最后结合当前用户上下文判断权限。任意一步失败都立即停止,不能先执行工具再补做检查。

这种门禁结构还有一个重要收益:校验失败时不会触发外部 API、数据库写入、文件删除等副作用。对 Agent 来说,不执行错误调用比执行后再回滚更可靠。
定义规则并返回结构化错误
天气查询只读。涉及账户积分等写操作时,还要检查业务对象和审批。示例要求转移金额为 1 到 1000 的整数,双方属于同一租户。调用者需具备 credit:transfer,且服务端已有针对这次动作的有效审批。把代码保存为 credit_policy.py,下一课会在写入之前调用它。
python
from dataclasses import dataclass
class CreditError(ValueError):
pass
@dataclass(frozen=True)
class TransferContext:
tenant_id: str
actor_id: str
permissions: frozenset[str]
operation_key: str
@dataclass(frozen=True)
class Approval:
tenant_id: str
actor_id: str
operation_key: str
target_user_id: str
amount: int
expires_at: int
def validate_transfer(args, context, approval, account_tenants, now):
if not isinstance(args, dict) or args.keys() != {"target_user_id", "amount"}:
raise CreditError("INVALID_FIELDS")
target, amount = args["target_user_id"], args["amount"]
if not isinstance(target, str) or not 1 <= len(target) <= 80 or target != target.strip():
raise CreditError("INVALID_TARGET")
if type(amount) is not int or not 1 <= amount <= 1000:
raise CreditError("OUT_OF_RANGE")
if (
"credit:transfer" not in context.permissions
or account_tenants.get(context.actor_id) != context.tenant_id
or account_tenants.get(target) != context.tenant_id
or target == context.actor_id
):
raise CreditError("PERMISSION_DENIED")
approved_action = (context.tenant_id, context.actor_id, context.operation_key, target, amount)
if approval is None or now >= approval.expires_at or approved_action != (
approval.tenant_id, approval.actor_id, approval.operation_key,
approval.target_user_id, approval.amount,
):
raise CreditError("APPROVAL_REQUIRED")
return target, amount
if __name__ == "__main__":
context = TransferContext("team-a", "alice", frozenset({"credit:transfer"}), "op-1")
accounts = {"alice": "team-a", "bob": "team-a", "eve": "team-b"}
approval = Approval("team-a", "alice", "op-1", "bob", 50, 200)
for args in (
{"target_user_id": "bob", "amount": 1200},
{"target_user_id": "eve", "amount": 50},
{"target_user_id": "bob", "amount": 51},
{"target_user_id": "bob", "amount": 50},
):
try:
print(validate_transfer(args, context, approval, accounts, now=100))
except CreditError as error:
print(str(error))预期输出
text
OUT_OF_RANGE
PERMISSION_DENIED
APPROVAL_REQUIRED
('bob', 50)校验所依赖的信息来自哪里
上下文和审批由服务端根据认证身份与审批记录构造。模型只提供 target_user_id 和 amount。operation_key 由业务流程为同一次逻辑动作生成,绑定到已批准的具体参数,在重试时沿用。此例中的 now 和 expires_at 统一使用 Unix 时间戳秒,达到过期时刻即无效。时间由执行方读取。
应用层可以尽早拒绝非法调用。正式的写入还要在服务端事务内再次验证可能变化的权限、余额和资源归属,避免校验后、提交前发生变化。接口对外返回稳定的错误类别。例如对不存在和跨租户的账户使用相同错误,避免通过结果枚举其他租户资源。
按自己的节奏,确认真正理解。