Skip to content

修复 HTTP 工具参数校验缺失问题 - #273

Open
CW5201 wants to merge 1 commit into
OpenBMB:mainfrom
CW5201:fix/http-tool-schema-validation
Open

CW5201 wants to merge 1 commit into
OpenBMB:mainfrom
CW5201:fix/http-tool-schema-validation

Conversation

@CW5201

@CW5201 CW5201 commented Sep 19, 2026

Copy link
Copy Markdown

解决的问题

HTTP Tool 执行链存在一个参数校验缺失的问题。
此前,ToolExecutor 在将模型生成的 arguments 发送到下游 HTTP 服务之前,没有根据工具自身的 input_schema 进行校验。
当模型出现以下情况时:

  • 漏传 required 必填字段
  • 参数类型错误
  • 嵌套参数不符合 schema
    这些错误参数会直接发送到下游服务,可能导致远端返回 4xx 或工具执行失败,Agent 获取到的错误信息不够明确,不利于后续自动纠正。

实现方式

在 ToolExecutor.execute() 的 HTTP Tool 执行路径中增加执行前的 JSON Schema 参数校验。
具体行为:

  • input_schema 为 None 或 {}:保持原有行为
  • input_schema 不是字典:记录 warning 并跳过校验
  • input_schema 本身非法:记录 warning 并跳过校验,避免影响历史工具
  • 参数不符合合法 schema:返回 SCHEMA_INVALID
  • 校验失败时不发送 HTTP 请求
  • 最多保留前 5 条校验错误
  • 错误信息包含缺失字段、类型错误和嵌套字段路径
    本次使用项目已有的 jsonschema 依赖,没有增加新的依赖,也没有修改 ToolError 的数据结构。

影响范围

本次修改仅涉及 HTTP Tool 的执行前参数校验。
未修改:

  • MCP
  • A2A
  • Harness
  • detached worker 独立执行逻辑
  • 前端
  • 数据库
  • API 路由
  • migration
  • 依赖

测试

新增测试覆盖:

  • required 字段缺失
  • 参数类型错误
  • 嵌套字段校验
  • 合法参数正常执行
  • 空 input_schema
  • null input_schema
  • 非法 schema
  • MCP Tool 路径不受影响
    测试结果:
  • test_tool_executor.py:28/28 通过
  • 相关工具测试:34/34 通过
  • 改动前后全量失败集合一致,无新增回归
  • Ruff 无新增错误
  • git diff --check 通过

UI 验证

Route:/workspace/tools
Role:admin
通过工具管理页面“测试工具”按钮对应的 REST API:
POST /api/enterprise/tools/{id}/test
使用 order.query 进行了验证:

  • 缺少 order_id → 返回 SCHEMA_INVALID
  • order_id 类型错误 → 返回 SCHEMA_INVALID
  • 合法 order_id → 正常执行
  • 非法参数不会发起远端 HTTP 请求
    由于当前验证环境没有 GUI 浏览器,因此这里采用的是页面对应 REST API 的 fallback 验证,并非浏览器点击级验证。

兼容性

为了避免影响历史工具:

  • 空 schema 不进行校验
  • null schema 不进行校验
  • 格式异常的 schema 记录 warning 后跳过校验
    合法的 HTTP Tool 调用保持原有执行流程。

范围说明

这是一次 HTTP Tool 执行链的可靠性修复,重点解决模型生成无效参数时无法在请求发送前发现的问题。
本 PR 不涉及 MCP/A2A 的参数校验,也不改变现有 ToolError 结构。

…dispatch

When a model-generated tool call omits a required field or passes a
wrong-typed/nested argument, the executor previously forwarded the raw
arguments straight to the downstream HTTP service, which failed with an
opaque 4xx instead of a structured error the agent loop could use to
self-correct.

- ToolExecutor.execute() now validates arguments against the tool's
  input_schema before the HTTP dispatch (sync and detached-submit paths)
- Returns a new SCHEMA_INVALID ToolError listing up to 5 validation
  issues (missing required fields, type mismatches, dotted JSON paths)
  without issuing the HTTP request
- None / empty / non-dict / malformed schemas are logged and skipped,
  preserving existing behaviour for legacy tools
- MCP and A2A paths are intentionally untouched: their schemas belong to
  the provider, which is contractually responsible for validation
- No new dependencies (jsonschema is already a backend dep), no DB, API,
  or ToolError structure changes

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant