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 时间戳秒,达到过期时刻即无效。时间由执行方读取。

应用层可以尽早拒绝非法调用。正式的写入还要在服务端事务内再次验证可能变化的权限、余额和资源归属,避免校验后、提交前发生变化。接口对外返回稳定的错误类别。例如对不存在和跨租户的账户使用相同错误,避免通过结果枚举其他租户资源。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

校验工具参数

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通