Agent工具调用返回不规范问题解析与标准化实践

1次阅读

共计 2707 个字符，预计需要花费 7 分钟才能阅读完成。

在分布式系统和微服务架构中，Agent 工具作为服务间通信的重要桥梁，其返回数据的不规范会引发一系列连锁问题。以下是三种典型场景及其影响：

字段缺失或冗余 ：调用方需要编写大量防御性代码处理可能缺失的字段，例如response.data.user?.address?.city 这样的链式判断，导致代码可读性急剧下降。
类型突变：同一字段在不同场景下返回类型不一致（如数字变字符串），引发反序列化异常。某电商系统曾因库存字段类型突变导致下单流程崩溃。
错误码混乱：不同 Agent 使用自定义错误码体系（如 0 /1/-1、true/false、”success”/”fail” 混用），迫使调用方维护复杂的映射表。

这些不规范现象会导致接口适配代码量增加 30% 以上，且难以通过静态检查发现，往往在运行时才暴露问题。

方案	适用阶段	性能损耗	实施复杂度
Schema Validation	运行时校验	中	低
契约测试	开发 / 测试阶段	无	高
中间件拦截	请求 / 响应时	低	中

采用分层拦截架构：

协议层 ：通过 HTTP 的Accept/Content-Type 头或 gRPC 的 metadata 实现内容协商，确保传输格式统一。例如 gRPC 的 metadata 示例：
```
md := metadata.Pairs("x-response-format", "v2")
ctx = metadata.NewOutgoingContext(ctx, md)
```
校验层：利用 OpenAPI 3.0 规范定义响应模型，通过 JSON Schema 实现实时校验。关键校验规则包括：
必需字段检查（required）
类型校验（type）
枚举值验证（enum）
转换层：统一错误码体系，建议采用 Google API 设计指南中的标准结构：
```
{
  "error": {
    "code": 404,
    "message": "Resource not found",
    "details": []}
}
```

// 响应拦截器
func ResponseInterceptor(ctx context.Context, spec *openapi3.T) middleware.Middleware {return func(next http.Handler) http.Handler {return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // 1. 代理响应写入
            rw := NewResponseWriter(w)
            next.ServeHTTP(rw, r)

            // 2. 校验响应体
            if err := validateResponse(rw.Body(), spec); err != nil {logrus.WithContext(ctx).Errorf("invalid response: %v", err)
                writeError(w, ErrInvalidResponse)
                return
            }

            // 3. 标准化输出
            w.Header().Set("Content-Type", "application/json; charset=utf-8")
            w.WriteHeader(rw.statusCode)
            w.Write(rw.body)
        })
    }
}

// JSON Schema 校验
func validateResponse(body []byte, schema *openapi3.Schema) error {loader := openapi3.NewLoader()
    validator := jsonschema.NewValidator()
    return validator.Validate(body, schema)
}

@app.middleware("http")
async def validate_response(request: Request, call_next):
    response = await call_next(request)

    if request.url.path in OPENAPI_SPEC["paths"]:
        schema = OPENAPI_SPEC["paths"][request.url.path][request.method.lower()]["responses"]["200"]["content"]["application/json"]["schema"]
        try:
            jsonschema.validate(response.json(), schema)
        except jsonschema.ValidationError as e:
            logger.error(f"Schema validation failed: {e}")
            return JSONResponse(
                status_code=500,
                content={"error": {"code": "VALIDATION_ERROR", "message": str(e)}}
            )
    return response