Agent 工程实践 / 08 · 共 12 篇

Agent 工程实践 · 08

可靠工具执行:参数校验、权限与回执

工具执行 / 定义、参数、权限与回执

格式合法的 JSON 只是起点。工具定义、参数校验、执行权限和结果回填,都需要分别确认。

把发现、校验、执行和回填分开,才能定位调用停在哪一层。模型提出意图,宿主持有权限、执行状态和实际回执。

查看交互演示 ↓

机制分析

从“应该查天气”,到一次真实调用

场景是先查询杭州天气,再给出建议。流程说明进入上下文,只告诉模型先查再答;工具目录和具体定义再说明 get_weather 接受什么参数。读取这些内容不会自动调用服务,模型仍需生成工具请求,宿主再验证并执行。

本页模拟工具客户端与服务器,将城市字段改为数字,或附加不允许的参数,可以观察 schema 校验的阻断。切到发送通知的例子,则可能出现参数合法、当前主体没有写入权限的情况。两道闸门独立存在:符合接口形状,不等于有权操作。

需要区分的对象它提供的约束
流程说明任务步骤与使用建议,本身不执行工具
工具定义名称、用途与参数形状,不自动授予权限
参数校验检查请求是否符合本例 schema 子集
权限检查判断当前操作是否被宿主允许
服务器回执说明实际执行返回什么,成功或失败都需接收

服务器成功,也不等于模型已经知道

结果先在服务器产生,客户端再收到回执,最后组装成工具反馈进入下一轮输入。调用编号负责关联这次请求与回执。若只完成服务器执行,却遗漏回填,模型就没有新增证据;若服务返回失败,也应保留失败事实,不能把它包装成正常数据。

本例用固定规则区分类型错误、额外字段、权限拒绝和服务器失败。它们发生在不同位置,处理方式也不同:重试网络失败可能有用,盲目重试一个没有权限的请求则没有解决根因。

工程取舍

接口清晰之后,仍需决定执行策略

一次加载全部定义,还是按需发现?

全部定义有利于直接选择,但工具多时会增加输入长度与选择干扰。先发现目录,再加载少量完整定义,可以缩小本轮范围,代价是多一次选择和加载过程。本页按需加载是宿主策略,不是协议强制;实际采用哪种方式,应考虑工具数量、描述质量与查找成本。

静默修正参数,还是明确返回错误?

自动把数字转成字符串、删掉额外字段,可能让调用继续,也可能改变用户意图。本例保留原始 arguments,让失败原因可见。若生产系统允许自动纠正,应明确哪些转换可接受,并记录原值与执行值;涉及副作用时,更不能把猜测的目标当成已经确认。

在哪里授权,在哪里重试?

模型可以解释拒绝原因,但授权事实应由可信执行边界核对。实际服务也需要验证自身接收到的身份和操作范围,不能只依赖客户端界面。对于有副作用的工具,超时后应先确认结果是否已发生,再结合幂等约定决定重试;相同的“失败”提示可能对应完全不同的外部状态。

落到实现

让错误指向明确的处理层

保存工具名、定义版本、原始参数、校验结果、执行回执和关联编号,可以让后续处理知道应修改请求、申请授权、重试服务还是补回输入。展示给用户时应解释可采取的下一步,不必把全部内部字段暴露为操作负担。

本页只实现部分 JSON Schema 规则,权限采用本地允许列表,省略真实 MCP 握手与完整报文。天气、服务器结果和模型答复是固定样例,没有外部请求或真实通知发送。协议接口与应用层权限也不能视为同一个机制。

会生成调用,只是执行链的起点。可控的工具系统还需要明确谁授权、谁执行、谁确认结果,以及谁把结果交回模型。

交互演示 · 工具发现与执行台

比较参数错误、权限拒绝与服务器失败
00:00 / 00:00
工具发现与执行台金色:说明与目录 · 紫色:调度与检查 · 蓝色:模型
模型工具参数权限
旁白字幕

调用实验与执行记录

亲手比较调用条件

不会自动修正类型或删去额外参数。应用条件后,下游调用与回执清空;用装置上方的执行按钮逐步检查。正常讲解使用默认杭州样例。

目录元信息

定义、原始调用与两项检查

当前加载的 inputSchema

本次调用(教学简化记录)

本例仅实现 JSON Schema 中 object、string、required、additionalProperties 的相关子集;允许列表独立于 schema。权限通过也不保证服务器一定返回成功。

执行、接收和回填分别观察

01 · 服务器产生结果

02 · 客户端接收回执

03 · 组装输入与模型接收

教学预设回答

仅演示本地状态变化,天气为固定样例。没有外部请求、真实模型调用或消息发送。调用编号用于关联回执,省略 MCP 握手与完整 JSON-RPC 报文。

工具发现与执行台 · 模拟 MCP 客户端和服务器 / 无真实网络调用 · 教学模拟,动作与状态由同一时间轴驱动。自动讲解使用默认条件;改变下方条件可独立实验。

登录后收藏评论 0

登录后发表评论

暂无评论。