人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载本文基于openJiuwen/agent-core-java开源仓库中 com.openjiuwen.core.foundation.tool.Tool 的 API 文档并结合仓库源码Tool.java、LocalFunction.java、McpTool.java、RestfulApi.java 等进行纵深展开。全文围绕该抽象基类的设计意图、字段与构造约束、统一调用入口、子类扩展机制及配套回调事件展开帮助读者理解 openJiuwen Core Java 版工具体系的调用形态并掌握自定义工具、接入 MCP/HTTP 工具与流式输出的完整实现路径。Tool是 openJiuwen agent-core-java 工具体系的抽象基类。它本身不承载任何具体业务逻辑而是通过持有一张ToolCard元数据卡片为所有工具本地函数、MCP 工具、RESTful API 工具等定义统一的「同步执行」与「流式执行」两个入口并围绕这两个入口挂接完整的回调事件生命周期。理解Tool就掌握了 openJiuwen 中所有工具被 LLM 调用时的统一形态入参解析 → 调用开始 → 结果产出/异常上报 → 输出变换。一、Tool 在工具体系中的定位从源码结构看Tool位于core/src/main/java/com/openjiuwen/core/foundation/tool/Tool.java是全工具族系的抽象基类仓库中的具体工具实现均直接或间接继承自它实现类源码路径用途LocalFunctionfunction/LocalFunction.java包装本地 Java 函数/方法将可调用对象封装为工具McpToolmcp/McpTool.java包装 MCPModel Context Protocol客户端透传远端工具调用RestfulApiservice_api/RestfulApi.java将 RESTful HTTP 接口封装为工具执行请求并解析响应这些子类共享同一套「卡片 调用入口」抽象构造时注入一张描述工具元数据的ToolCard对外通过invoke/stream两个统一入口被上层调用。源码注释明确指出该类镜像了 Python 侧openjiuwen/core/foundation/tool/base.py中的Tool因此本仓库的 Java 实现与 openJiuwen Python 版保持一致的调用契约。设计要点Tool自身不实现具体业务逻辑只负责约束所有工具共有的调用形态。具体行为全部由子类通过两个受保护的模板方法invokeInternal/streamInternal提供父类负责输入预处理、回调触发与输出变换的公共编排。二、唯一字段 card 与构造约束Tool只有一个实例字段card类型ToolCard即工具卡片保存工具的名称、描述、输入参数 Schema 等元数据。字段说明如下字段类型默认值说明cardToolCard-工具卡片。构造时要求非空且id非空字符串。源码 Tool.java 中的受保护构造器Tool(ToolCard card)在初始化时执行两条硬性校验public Tool(ToolCard card) { if (card null) { throw toolCardInvalid(null, card is None); } if (card.getId() null || card.getId().isEmpty()) { throw toolCardInvalid(card, card id is None or empty); } this.card card; }card为null直接抛出异常错误码TOOL_CARD_INVALID由 ErrorHelper 构造card.getId()为空或 null同样拒绝构造。因此「每个工具必须携带一张有合法 id 的卡片」是工具体系不可绕过的约束。值得注意该构造器为受保护protected仅供子类初始化时调用不作为公开构造方法暴露这与文档「源码中的Tool(ToolCard card)为受保护构造器供子类初始化时使用」的说明一致。card声明为final一旦构造完成不可替换保证工具生命周期内元数据稳定。三、统一调用入口invoke 与 streamTool为所有工具定义了两种执行模式同步执行invoke与流式执行stream各自提供带/不带kwargs两个重载版本。公开方法签名如下签名说明public ToolCard getCard()返回当前工具持有的卡片对象。public abstract Object invoke(MapString, Object inputs, MapString, Object kwargs) throws Exception执行完整工具调用具体行为由子类实现。public Object invoke(MapString, Object inputs) throws Exception以空kwargs调用重载版本。public abstract IteratorObject stream(MapString, Object inputs, MapString, Object kwargs) throws Exception以流式方式执行工具返回增量结果迭代器。public IteratorObject stream(MapString, Object inputs) throws Exception以空kwargs调用流式重载版本。3.1 参数语义两个入口的第一个参数inputs是结构化输入需要符合工具卡片ToolCard.inputParams声明的 JSON Schema第二个参数kwargs是附加执行参数用于向执行过程传递额外控制信息。以 LocalFunction.java 的实现为例kwargs中以下两个键会被识别并影响入参解析skip_none_value布尔为true时跳过值为None/null的输入字段skip_inputs_validate布尔为true时跳过输入 Schema 校验。单参数重载版本内部直接以Map.of()构造空kwargs调用双参数版本见 Tool.java因此无论调用方传不传kwargs行为路径完全一致。3.2 invoke 的内部编排从源码 Tool.java 看invoke并非简单转发到子类而是父类编排的一整条事件链入参准备prepareInput复制inputs/kwargs若注册了回调框架DecoratorFramework先触发tool_invoke_input变换事件允许回调修改入参调用开始触发tool_call_started事件携带tool_name、tool_id、inputs等生命周期参数执行与结果/异常上报调用子类实现的invokeInternal成功触发tool_call_finished失败捕获异常并触发tool_call_error后重新抛出输出变换触发tool_invoke_output事件回调可对结果做二次加工transformOutput。3.3 stream 的流式生命周期stream的编排见 Tool.java父类先触发tool_stream_input与tool_call_started然后调用子类的streamInternal获得底层迭代器若返回null则替换为空迭代器Collections.emptyIterator()最后包一层内部的CallbackIterator返回。该迭代器在遍历过程中按需触发每取出一块增量结果触发tool_result_received与tool_stream_output迭代耗尽触发tool_call_finished遍历抛异常触发tool_call_error同一迭代器只上报一次通过finished标志保证幂等。所有事件名常量集中在 ToolCallEvents.java 中完整清单包括tool_call_started、tool_call_finished、tool_call_error、tool_result_received、tool_parse_started、tool_parse_finished、tool_invoke_input、tool_invoke_output、tool_stream_input、tool_stream_output、tool_auth。这意味着Tool 层的可观测能力是全体系统一的无论底层是本地函数、MCP 远端还是 HTTP 接口回调消费者拿到的生命周期事件形态一致。四、子类如何实现具体工具invokeInternal / streamInternalTool将「父类编排 子类实现」分离。公开的invoke/stream是final级编排入口非 abstract而真正的业务逻辑由两个受保护模板方法承载protected Object invokeInternal(MapString, Object inputs, MapString, Object kwargs) throws Exception; protected IteratorObject streamInternal(MapString, Object inputs, MapString, Object kwargs) throws Exception;若子类未覆盖某一方法基类默认抛出明确错误未实现invokeInternal→TOOL_INVOKE_NOT_SUPPORTED工具不支持同步调用未实现streamInternal→TOOL_STREAM_NOT_SUPPORTED工具不支持流式调用。这正是McpTool的做法MCP 远端调用本身不具备原生增量流式契约因此 McpTool.java 的streamInternal直接抛出TOOL_STREAM_NOT_SUPPORTED而invokeInternal则完成参数按 Schema 清洗、调用 MCP 客户端的callTool/call_tool方法、并支持operation_timeout/operationTimeout/timeout键动态覆盖超时默认McpBase.NO_TIMEOUT。LocalFunction则两个方法都实现LocalFunction.java其流式策略很有代表性返回结果是Iterator直接透传返回结果是Iterable如List取其iterator()返回普通对象包装成单元素迭代器singletonList(result).iterator()。同时invokeInternal中若发现函数返回的是Iterator会抛出func can not be generator错误——即同步调用不允许返回生成器语义的迭代器必须走stream入口从源码与测试双重印证了这一约束。五、ToolCard工具元数据卡片ToolCardToolCard.java继承自BaseCard除基础的身份信息id、name、description外还维护工具声明的输入 Schema 与执行特性成员默认值含义inputParams空LinkedHashMap输入参数的 JSON Schematype、properties、required等properties空LinkedHashMap附加属性如 MCP 场景的传输细节isParallelSafetrue是否可并行安全调用isStatelessfalse是否无状态isIdempotentfalse是否幂等ToolCard提供两种构建方式多参构造器ToolCard(id, name, description[, inputParams[, properties]])Builder 模式ToolCard.builder().id(...).name(...).description(...).inputParams(...).parallelSafe(...).stateless(...).idempotent(...).build()其中id缺省时会自动生成name/description缺省为空字符串。卡片的核心产出方法是toolInfo()返回 ToolInfo.java 描述符——遵循OpenAI function calling 格式typefunction、name、description、parameters可直接用于 LLM 的 function/tool 参数拼接。equals/hashCode覆盖了完整声明面身份 参数/属性 三个特性标志用于工具重复注册时的等价性判定ability-declaration reuse check。六、工具的三种典型创建方式围绕Tool基类仓库提供了三种把「普通代码」变成「工具」的路径6.1 手动构造 LocalFunction最直接的方式先构建ToolCard再new LocalFunction(card, func)其中func是FunctionMapString, Object, Object。LocalFunction还支持ContextFunction变体(inputs, kwargs) - Object可在函数体内访问session等执行期上下文且函数返回CompletionStage如CompletableFuture时会被自动等待并解包见 LocalFunction.java。6.2 ToolDecorator 工厂ToolDecorator.java 是 Python 版tool(...)装饰器的 Java 等价物提供tool(Function)、tool(name, Function)、toolFromMethod(target, method)等静态工厂方法以及携带完整选项的Options记录name、description、inputParams、card、autoExtract、sourceMethod未显式指定inputParams且autoExtracttrue时通过 CallableSchemaExtractor.java 基于反射自动生成参数 Schema方法参数为Optional类型时会自动包裹空值argumentValue显式传入card时若name/description/inputParams与卡片不一致会生成一张覆盖后的新卡片而非修改原卡片。6.3 ToolDefinition 注解扫描annotation/ToolDefinition.java 提供name、description、autoExtract三个注解属性配合 AnnotatedToolFactory.java 的scan(target)可一键扫描目标对象上所有ToolDefinition标注的方法并批量转换为LocalFunction适用于工具注册表批量装配场景。七、异步执行与虚拟线程Java 版的设计取舍文档明确说明Java 版本没有内建异步接口Tool的invoke/stream均为同步阻塞形态throws Exception。如果需要异步执行由调用方自行结合虚拟线程或CompletableFuture处理。这一点与 Python 版Tool的协程语义不同——Java 侧刻意不把异步写进基类契约原因可以从两个层面印证函数层支持异步返回值LocalFunction允许包装的函数返回CompletionStage父类在调用线程上统一await等待完成awaitIfNeeded因此「异步函数 同步调用入口」天然兼容调用层由使用者编排异步需要真正并行发起多个工具调用时可在外层用虚拟线程本项目文档 Java版本与虚拟线程兼容 有专项说明包裹每个invoke或将调用提交给CompletableFuture组合工具自身无需感知线程模型。另外LocalFunction.invokeFunction在调用前后会保存/恢复SessionContextHolder中的当前 Session见 LocalFunction.java其注释明确指出这是为「并行工具调用不互相污染调用线程绑定的 Session」而设计——从源码结构看这是对虚拟线程/并行场景的显式防护。八、测试验证四个相关测试覆盖的行为文档列出四个相关测试均可在仓库core/src/test下找到覆盖了Tool体系的核心行为契约测试类路径验证重点LocalFunctionTestcore/src/test/java/com/openjiuwen/core/foundation/tool/function/LocalFunctionTest.java构造时拒绝null函数输入按 Schema 填充默认值如mode缺省补texttool_parse_started/tool_parse_finished回调携带tool_name/tool_id/raw_inputs/schema/formatted_inputsCompletableFuture返回值被自动等待同步invoke拒绝迭代器返回func can not be generatorstream正确产出Iterator元素并触发解析回调McpToolTestcore/src/test/java/com/openjiuwen/core/foundation/tool/mcp/McpToolTest.javaMCP 客户端调用透传、参数清洗与超时控制RestfulApiTestcore/src/test/java/com/openjiuwen/core/foundation/tool/service_api/RestfulApiTest.javaRESTful 工具的 URL 校验、HTTP 执行与响应解析ToolCardTestcore/src/test/java/com/openjiuwen/core/foundation/tool/ToolCardTest.javaBuilder 构建卡片属性、id自动生成、默认inputParams为空 Map、默认特性标志isParallelSafetrue、isStatelessfalse、isIdempotentfalse、toolInfo()输出其中LocalFunctionTest的invokeFormatsInputsWithSchemaDefaults用例直观展示了 Schema 默认值填充卡片声明mode字段默认text且path必填仅传path调用即可得到readme.md:text的结果——这正是「工具卡片声明驱动入参解析」的具体体现。九、小结Tool 基类的设计价值从整体设计看openJiuwen agent-core-java 的Tool抽象基类承担了三层职责统一契约以ToolCard承载元数据、以invoke/stream承载调用入口所有工具本地、MCP、HTTP对上层与 LLM 暴露一致的形态集中编排输入变换、生命周期回调、输出变换全部收敛在父类子类只需实现invokeInternal/streamInternal两个模板方法且通过默认抛错让「不支持的能力」显式化可观测基础tool_call_started/finished/error、tool_parse_started/finished、tool_stream_output等标准事件构成统一的工具调用追踪与装饰器挂接点。对于希望在本仓库中自定义工具的开发者标准路径是构建一张ToolCard或直接用ToolDecorator/ToolDefinition自动生成→ 继承Tool实现invokeInternal必要时实现streamInternal→ 通过setCallbackFramework注册回调框架即可获得全套调用事件。若仅需快速接入优先使用LocalFunction包装函数或通过McpTool/RestfulApi对接远端能力。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐openJiuwen agent-core 工具系统实战从 ToolCard、tool 装饰器到 RESTful API 与 MCP 的统一 Tool 抽象openJiuwen agent core 工具系统实战从 ToolCard、tool 装饰器到 RESTful API 与 MCP 的统一 Tool 抽象人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 检索器统一抽象接口Retriever 基类深度解析与实战指南openJiuwen agent core 检索器统一抽象接口Retriever 基类深度解析与实战指南 导读 本文围绕 openJiuwen agent c人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习openJiuwen agent-core 沙箱启动器SandboxLauncher基类解析生命周期抽象、配置模型与内置实现openJiuwen agent core 沙箱启动器SandboxLauncher基类解析生命周期抽象、配置模型与内置实现 导读 本文围绕 openji人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考