第4章 请求参数规范：Query参数、Path参数、Body参数、必选与可选

在 Agent 工具调用接口中，请求参数的位置与约束直接决定了调用方如何构造请求、服务端如何提取与校验数据。本章围绕四种核心参数来源（Path、Query、Body）以及必选/可选约束，从原理、实现、调试到优化给出完整的技术实现指引。

4.1 参数位置原理与适用场景

工具接口的每个输入参数都需要声明其位置（location）和约束（constraint）。位置决定了参数在 HTTP 请求中的载体，约束决定了调用方是否必须提供该参数。三种参数位置的核心区别如下：

4.2 必选与可选约束语义

每个参数必须显式声明 required 属性。必选参数缺失时，调用引擎应直接拒绝请求并返回明确的错误信息；可选参数缺失时，引擎应使用默认值（若有）或跳过该参数。

4.3 参数解析与校验实现流程

Agent 调用引擎在处理工具请求时，按以下步骤完成参数提取与校验：

1. 路由匹配——根据请求路径模板提取 Path 参数原始值；
2. 查询解析——将 URL 查询字符串拆解为键值对列表；
3. Body 反序列化——按 Content-Type 将请求体解析为结构化对象；
4. 必选校验——遍历参数定义，检查必选参数是否全部存在；
5. 类型转换——将字符串形式的 Path/Query 值转换为目标类型（int / bool / enum）；
6. 参数合并——将三部分参数合并为统一的调用上下文，传递给工具执行函数。

4.4 代码示例：工具定义与参数提取

以下是一个典型的工具接口定义（使用 JSON Schema + OpenAPI 风格），声明了三种参数位置及必选/可选约束：

{
  "tool": "query_order",
  "description": "查询订单详情",
  "parameters": {
    "type": "object",
    "properties": {
      "orderId": {
        "type": "string",
        "description": "订单 ID",
        "in": "path",
        "required": true
      },
      "status": {
        "type": "string",
        "enum": ["pending", "shipped", "completed"],
        "description": "订单状态过滤",
        "in": "query",
        "required": false,
        "default": "pending"
      },
      "address": {
        "type": "object",
        "properties": {
          "province": { "type": "string" },
          "city": { "type": "string" }
        },
        "description": "配送地址",
        "in": "body",
        "required": true
      }
    },
    "required": ["orderId", "address"]
  }
}

Agent 调用引擎根据上述定义执行参数提取的核心逻辑（Python 伪代码）：

def extract_and_validate(params_def, request):
    # 1. 提取 path 参数（从 URL 路径模板匹配）
    path_params = extract_path_params(
        template="/orders/{orderId}",
        actual_path=request.path
    )
    # 2. 提取 query 参数（解析 ?key=val）
    query_params = parse_query_string(request.query_string)
    # 3. 提取 body 参数（反序列化 JSON）
    body_params = json.loads(request.body) if request.body else {}
    # 4. 合并原始参数
    raw = {
        "path": path_params,
        "query": query_params,
        "body": body_params
    }
    # 5. 按定义提取并校验必选
    result = {}
    for name, prop in params_def["properties"].items():
        loc = prop.get("in", "body")
        val = raw[loc].get(name)
        if val is None and prop.get("required", False):
            raise ValueError(f"必选参数缺失: {name} (位置: {loc})")
        if val is None and "default" in prop:
            val = prop["default"]
        if val is not None:
            result[name] = type_coerce(val, prop["type"])
    return result

4.5 调试方法

参数问题是最常见的工具调用失败原因。推荐使用以下手段进行调试：

• 参数日志注入——在参数提取与校验的关键节点打印 [PARAM] location=path key=orderId raw=ord_123 格式的结构化日志；
• 校验阻断测试——分别构造“必选参数缺失”“类型不匹配”“枚举值越界”三种请求，验证引擎是否返回符合规范的错误体；
• 参数快照 dump——在步骤 6（合并与类型转换）之前输出原始参数快照，对比定义与实际值的差异；
• curl 直测法——绕过 Agent 编排层，直接用 curl 请求工具端点，确认 HTTP 层的参数传递是否正确。

# 调试示例：使用 curl 验证 Path + Query + Body 参数
curl -X POST "http://localhost:8080/orders/ord_123?status=shipped" \
  -H "Content-Type: application/json" \
  -d '{"address": {"province": "广东", "city": "深圳"}}'

4.6 常见错误与解决方案

4.7 性能与稳定性优化

参数解析在高并发场景下可能成为瓶颈，以下优化策略可直接应用于生产环境：

• Schema 预编译——将工具定义的 JSON Schema 预编译为校验器对象（如使用 jsonschema.validators 或 pydantic），避免每次请求重复编译；
• 参数缓存——对于幂等的 Path 参数提取结果（同一模板+同一路径），可缓存映射关系，减少正则匹配开销；
• 懒解析——Body 参数只在需要时进行反序列化，对于仅使用 Path/Query 的工具跳过 Body 解析；
• 超时熔断——Body 解析设置最大 JSON 深度（默认 20 层）和大小阈值（默认 1 MB），防止畸形负载导致 CPU 飙高；
• 校验短路——一旦发现必选参数缺失，立即返回错误，不继续执行后续参数的类型转换。

4.8 本章小结