Repository navigation
[P0][T31] 增加 ToolCall 执行前 JSON Schema 与参数资源限制校验 #134
Description
目标与优先级
Schema 声明是模型提示和绑定依据，不等于执行边界已经强制校验。需要可选的统一参数门禁。
- 优先级：P0；责任仓库：
agentic-ai-java/argi；补充任务：T31。 - 总览：https://github.com/agentic-ai-java/argi/issues/117。
当前证据与判断边界
- AgentToolNode 解析 callback 后把 arguments 字符串直接交给 sync/async callback； inspected 路径没有统一 Schema validator。
- 工具自身可做 Jackson 反序列化/业务校验，不能据此证明所有自定义/MCP callback 都执行相同参数校验。
以上是源码观察；能力补充结论是基于这些路径的推断，不等同生产故障或漏洞已经复现。框架已有ReAct/Hook、摘要、Todo、Schema声明、工具拦截及可选Sandbox，本任务是在其基础上补齐边界。
范围与落地方案
- 在最终 ToolCallback resolve 后、真实 dispatch 前校验实际 arguments 与实际 ToolDefinition.inputSchema。覆盖 sync/async/parallel/dynamic/MCP/AgentTool。
- 明确 JSON parse、required/type/enum/range/additionalProperties 及 null 规则，限制字节数、嵌套深度与集合大小；声明支持的 Schema draft/关键字，不支持时严格路径报错。
- 不自动放宽 Schema或静默 coercion；若提供 normalization，重新绑定验证并使授权、审批、argument hash 与最终参数一致。interceptor 改写后的参数必须重验。
- 复用项目已管理的 JSON/Schema API；需要新增模块依赖时单独评估。默认旧工具调用不变。
前置依赖
- 无前置Task，可独立交付基础契约和reference tests。
已有任务与去重边界
- [P0][T03] 在工具执行边界强制校验授权与风险策略 #120 (T03)
- [P1A][T07] 增加版本固定的运行定义解析与恢复能力校验 #123 (T07)
- [P1C][T14] 持久化模型调用结果与稳定工具执行计划 #125 (T14)
这些是关联/集成位置，不是额外硬阻塞。仅前置依赖要求先交付；持久化和跨实例能力继续由原任务承担。
验收条件
- 非法 JSON、缺必填、类型/枚举/范围违规、unknown field（当 Schema 禁止）在 callback 前拒绝，调用次数为零。
- 超大/超深参数、畸形 Schema和不支持的关键字按显式策略失败，校验器不能无限递归或远程加载任意 $ref。
- 拦截器改写 arguments 或动态 resolver 换 Schema 后校验的是最终执行版本；同步与异步结果一致。
- 验证错误带安全的字段路径/错误码，不泄漏敏感参数；旧 callback/API 回归通过。
非目标
- 不重建 [P0][T03] 在工具执行边界强制校验授权与风险策略 #120 的鉴权，不实现 [P1C][T14] 持久化模型调用结果与稳定工具执行计划 #125 的模型 journal；本任务只负责输入契约和执行前资源门禁。
- 不把 Schema 校验当业务授权、路径/URL安全或工具副作用幂等保障。
兼容与验证
- Java 17，新增路径opt-in；保留现有公开API、默认行为与历史state/checkpoint格式。不引入MQ或节点级分片。
- Core不导入Redis/Extensions；优先复用已有API、reducer和组件，不直接添加新依赖。
- 先模型无关单测，再按本任务范围运行模块测试/API与格式fixture；跨adapter路径用stub contract tests，真实Docker测试注明环境要求。
- 当前main的兼容文档/CI曾调整，新任务不引用已删除文档或自行恢复CI；遵循实施时实际有效门禁，保留兼容回归目标。
源码依据（固定版本）
分析基线：Core f3bcbef24aa79e1e265a7d0d2011274982ac2978、Extensions 1ba3048f16d48c9f41dab171eed9a91148b45758。只读compare确认相对上次分析没有生产Java变更，主要是release/build/docs更新；本Issue不表示能力已实现。
Activity
konlue commentedon Oct 9, 2026
您好，我想要认领 T31。先同步我目前的核实（基线
f3bcbef）：AgentToolNode.executeToolCallWithInterceptors的 baseHandler：resolve(...)拿到ToolCallback 后直接进
executeToolByType→executeSyncTool/executeAsyncTool，最终
callback.call(request.getArguments(), context)把原始 arguments 字符串交给callback——resolve 与 dispatch 之间没有统一参数门禁（只有工具名 unresolved 的错误路径），
与 issue 描述一致。
（
AgentTool.create的wrapSchemaInInputParameter），没有执行前校验。ToolCallResponse.error（status=error + metadata），与未解析工具名的处理路径同构。
方案拆两个 PR：
resolve之后、executeToolByType之前插入统一校验点——三条路径（sync / async / wrapSyncToolsAsAsync）都经过这一处，天然全覆盖：JSON parse →
required/type/enum/range/additionalProperties/null 规则；失败返回
ToolCallResponse.error（metadata 带 errorCode + 安全的字段路径，不回显参数值），callback 调用次数为零；opt-in 开关、默认关闭保持旧行为；同步/异步契约测试 + 非法
JSON、缺必填、类型/枚举/范围违规的回归。
校验器不无限递归）；interceptor 链改写 arguments 后对最终执行版本重验；本地 $ref
展开、拒绝远程 $ref；错误信息脱敏与旧 API 回归。
时间表：PR1 本周内，PR2 下周内。
还有两个设计问题想先确认：
com.networknt:json-schema-validator3.0.1（argi-studio在用）——agent-framework 运行时直接引这个已管理依赖，还是手写零依赖的轻量校验器？
我倾向前者（不新增版本管理，Draft 2020-12 / $ref 处理成熟），但 agent-framework 会
多一个运行时依赖，想听你们的意见。
ToolCallResponse.error+ metadata（errorCode /fieldPath）与现有错误路径保持一致，把错误协议的统一留给 T38（ToolOutcome）单独做；
还是这里就要定义结构化错误字段？
Aias00 commentedon Oct 9, 2026