人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载com.openjiuwen.core.foundation.tool.service_api.ApiParamLocation是 openJiuwen agent-core-java 中 RESTful 工具体系的参数位置枚举用于标记一个参数应当落在 URL 查询串、路径占位、请求体还是请求头。它是RestfulApi与ApiParamMapper之间传递位置信息的核心纽带。读完本文你将掌握该枚举的每个取值与对应的小写字符串、getValue()/fromString()的语义边界并能结合源码读懂参数从输入 Schema 到最终 HTTP 请求的完整分流链路。一、枚举定义与定位在com.openjiuwen.core.foundation.tool.service_api包下ApiParamLocation是描述“请求参数应该被放在 HTTP 请求的哪个位置”的枚举类型。其源码位于 ApiParamLocation.java声明如下public enum ApiParamLocation { QUERY(query), PATH(path), BODY(body), HEADER(header), FORM(form); private final String value; ApiParamLocation(String value) { this.value value; } public String getValue() { return value; } public static ApiParamLocation fromString(String rawValue) { for (ApiParamLocation location : values()) { if (location.value.equalsIgnoreCase(rawValue)) { return location; } } throw new IllegalArgumentException(No enum constant for API parameter location: rawValue); } }从源码注释可以确认该枚举与 Python 版本openjiuwen/core/foundation/tool/service_api/api_param_mapper.py中的APIParamLocation一一对应属于跨语言 SDK 参数映射协议的 Java 侧镜像实现。该枚举在整个 service_api 子包中处于“位置契约”地位ApiParamMapper.java 依据输入 Schema 中的location标记调用fromString把输入值分发到不同位置分组RestfulApi.java 在构造阶段创建ApiParamMapper执行请求时按分组结果拼装 URL、请求头与请求体RestfulApiCard.java 在卡片构造阶段校验路径参数与 Schema 中locationpath的声明是否匹配。二、枚举值详解按 ApiParamLocation.md 的说明该枚举用于标记参数属于查询串、路径、请求体或请求头其取值及对应小写字符串如下枚举值小写字符串说明HTTP 请求中的实际落点QUERYqueryURL 查询参数追加到 URL 的?之后如/search?qopenjiuwenPATHpath路径占位参数替换 URL 模板中的{name}占位符如/users/{id}→/users/42BODYbody请求体参数序列化为 JSON 请求体非 GET 请求或并入查询串GET/DELETE 等请求HEADERheaderHTTP 请求头参数写入请求头如Authorization、X-Test需要特别说明的是从当前仓库源码看该枚举实际还包含第 5 个取值FORM(form)用于 multipart/form-data 场景详见下文第四节。文档表格虽未列出但源码、RestfulApi.getParametersByLocation(...)与RestfulApiTest均确认了form位置的存在使用时应以源码为准。三、公开方法语义getValue()返回枚举对应的小写字符串值即QUERY→query、PATH→path、BODY→body、HEADER→header、FORM→form。该字符串正是 Schema 中location字段采用的书写形式例如 RestfulApiTest.java 中 Schema 就写为location, path、location, query。fromString(String)按文档描述该方法“忽略大小写解析字符串未知值回退到BODY”。结合源码需要补充两点精确语义忽略大小写fromString内部使用equalsIgnoreCase逐一比对value因此Query、QUERY、query等价未知值行为从当前源码看当字符串不匹配任何枚举值时fromString实际抛出IllegalArgumentException(No enum constant for API parameter location: ...)而不是回退到BODY。这一行为被 ApiParamMapperTest.java 的invalidExplicitLocationFailsFast用例锁定Schema 中显式声明location, invalid时map(...)会直接失败并抛出IllegalArgumentException。换句话说“回退到 BODY”的真实发生位置在ApiParamMapper.resolveLocation(...)即当参数 Schema 中根本没有声明location键时才启用默认位置逻辑默认 BODY。显式声明了非法位置则会快速失败fail-fast避免配置错误拖到运行时才暴露。四、在 ApiParamMapper 中的消费链路ApiParamMapper是枚举最主要的消费者其map(inputs, defaultLocation)方法把输入按位置分组成MapApiParamLocation, MapString, Object。核心流程见 ApiParamMapper.javaSchema 为空全部输入直接放入defaultLocation分组按 Schema 分流遍历schema.properties只对输入中存在的键做分流每个属性的location值经resolveLocation解析为枚举实例FORM 特例location FORM时只有“真值”非 null、非空字符串、非 0 数字、非空集合/Map的参数才会被放入 FORM 分组并包装为{form_handler_type: ..., value: ...}form_handler_type未显式声明时默认default默认值合并PATH、QUERY、HEADER三类位置在分流后会与构造时传入的默认参数合并且输入值覆盖默认值空字符串与 null 输入不会覆盖默认值见测试mapMergesDefaultsButKeepsDefaultsWhenInputIsNullOrEmptyString。resolveLocation的解析规则源码 L126-L134location值为字符串时转小写后调用fromString非法值抛异常location值为ApiParamLocation实例时直接采用未声明location时若默认位置是BODY则回退到BODY否则回退到QUERY。由测试 ApiParamMapperTest.java 可见典型分流结果q→QUERY、id→PATH、payload→BODY、token→HEADER各归其位多个 FORM 参数与 BODY 参数混用时L81-L102FORM 与 BODY 可同时存在。五、在 RestfulApi 中的最终落地卡片定义与构造期校验RestfulApiCard声明 URL、HTTP 方法、默认请求头、默认参数与执行约束默认方法为POST、默认超时 60 秒、默认最大响应体 10MB见 RestfulApiCard.md 与源码 RestfulApiCard.java。构造阶段即完成三类校验method必须属于SUPPORTED_METHODSGET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS非法方法直接抛错url必须是带 host 的 http/https 地址路径参数一致性URL 中每个{name}占位符都必须在input_paramsSchema 中以location: path声明否则抛TOOL_RESTFUL_API_CARD_CONFIG_INVALID反之 Schema 中声明了 URL 未用到的 path 参数只记 warning源码 L166-L210。执行时的位置拼装RestfulApi.invoke(...)先对输入做 Schema 格式化再交给apiParamMapper.map(formattedInputs, ApiParamLocation.BODY)分流随后在buildPayloadRestfulApi.java L327-L368中按位置拼装请求PATHapplyPathParams用{name}占位符替换为参数值QUERYappendQueryParams追加?kv数组/集合值会展开为多个键值对参数经 UTF-8 URL 编码HEADER写入请求头并与request_args.headers合并BODY非 GET 请求序列化为 JSON 请求体并自动补充Content-Type: application/jsonGET/DELETE/HEAD/OPTIONS这类PARAM_METHODS请求则把 body 参数追加到查询串对应 service_api.README.md 中的关键行为说明FORM走FormHandlerManager的处理器后组装为multipart/form-data请求体自动移除调用方传入的Content-Type并重新生成 boundary。这些行为在 RestfulApiTest.java 中均有对应的本地 HttpServer 验证例如testInvokeGetWithParamsid42落入路径/users/42format/ids/keyword与默认limit10落入查询串X-Test落入请求头testInvokePutWithBodyAndPathParamsPUT 请求发送 JSON body路径占位被替换testDeleteUsesParamsForBodyLocationDELETE 的 body 参数并入查询串testFormSubmissionFlowlocationform的参数发送 multipart body。响应标准化响应先经 ParserRegistry 按Content-Type解析再封装为统一六字段结构code、data、url、headers、reason、message。响应字节数超过max_response_byte_size、HTTP 状态码 ≥ 400且未关闭raise_for_status或响应解析失败时分别转换为对应StatusCode错误。六、完整实战示例把以上机制串起来一个典型的天气查询 REST 工具定义如下改写自仓库示例 ReActWeatherAgentExample.javaimport com.openjiuwen.core.foundation.tool.Tool; import com.openjiuwen.core.foundation.tool.service_api.RestfulApi; import com.openjiuwen.core.foundation.tool.service_api.RestfulApiCard; import java.util.Map; RestfulApiCard card RestfulApiCard.builder() .id(weather_tool) .name(WeatherReporter) .description(天气查询插件输入 city 获取实时天气和未来几天预报) .url(https://uapis.cn/api/v1/misc/weather) .method(GET) .timeout(10.0) .queries(Map.of(lang, zh, forecast, true)) .inputParams(Map.of( type, object, properties, Map.of( city, Map.of( type, string, description, 城市名称支持中文北京和英文Tokyo, location, query ) ) )) .build(); Tool tool new RestfulApi(card);示例中city通过location, query声明为查询参数lang、forecast作为卡片级默认查询参数在每次请求时自动携带。注册进 ReActAgent 后模型调用WeatherReporter(city北京)时会自动拼出?langzhforecasttruecity北京。若 URL 含路径占位符则必须配套声明// URL: https://api.example.com/api/v1/Activities/{id} properties, Map.of( id, Map.of(type, integer, description, Activity ID, location, path), name, Map.of(type, string, description, Activity name, location, body), api_key, Map.of(type, string, description, API Key, location, header) )上述 Schema 中id会替换 URL 占位符、name进入请求体、api_key进入请求头。类似的混合位置定义与 GUI 辅助方法RestfulApi.getParametersByLocation(...)按path/query/header/body/form分组输出参数元数据都能在 RestfulApiTest.java 中找到验证。七、行为边界与注意事项综合文档与源码使用ApiParamLocation时需要留意以下边界位置值大小写不敏感Schema 中写query、Query、QUERY均可被fromString接受非法显式位置快速失败显式声明了location但值非法时构造/调用阶段即抛IllegalArgumentException不会静默回退未声明位置才回退 BODY参数未写location键时默认进入BODYmap默认defaultLocation为BODY这也是 REST 工具最常见的默认行为路径占位符强校验URL 中的{name}必须能在 Schema 中按locationpath找到对应声明否则卡片构造直接失败GET 与 DELETE 的 body 会变成查询参数因此“body 参数”的落点取决于 HTTP 方法FORM 是文档表格之外的扩展位置实际源码支持locationform配合form_handler_type组装 multipart 请求测试覆盖可参考TestProcessFormDataMethod与TestCompleteFormSubmissionFlow系列用例响应限流与状态检查kwargs.timeout、kwargs.max_response_byte_size、kwargs.raise_for_status可在调用时覆盖卡片默认值。八、相关文档与测试清单枚举 API 文档ApiParamLocation.md参数映射器文档ApiParamMapper.mdREST 工具文档RestfulApi.md工具卡片文档RestfulApiCard.md子包总览service_api.README.md开发者指南自定义工具.md含RestfulApi使用要点与注意事项核心测试ApiParamMapperTest.java、RestfulApiTest.java可运行示例ReActWeatherAgentExample.java通过ApiParamLocation这一层轻量枚举契约openJiuwen agent-core-java 把“参数放在哪”的声明与“请求怎么拼”的实现彻底解耦上层 Schema 只需写一行location底层ApiParamMapper与RestfulApi就能稳定地把它翻译成正确的路径、查询串、请求头、请求体或 multipart 表单这也是整个 RESTful 工具体系在模型函数调用与实际 HTTP 执行之间保持一致的根基。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐wuzz请求构造详解URL参数与请求头配置wuzz请求构造详解URL参数与请求头配置 在日常开发中你是否还在为复杂的HTTP请求构造而烦恼是否经常记不清各种参数的配置格式本文将带你全面掌握wuz开发工具openJiuwen agent-core 的 Agent Builder 工具集枚举、进度追踪与 JSON 工具函数详解openJiuwen agent core 的 Agent Builder 工具集枚举、进度追踪与 JSON 工具函数详解 本文深入解析 openJiuwen人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习graphql-ruby 动态 Schema 实战按请求定制字段、参数、枚举值与类型的可见性graphql ruby 动态 Schema 实战按请求定制字段、参数、枚举值与类型的可见性 导读 GraphQL Ruby 允许每个请求每个 Opera后端API设计创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
