文章目录dev.langchain4j.agent.tool.Tool是什么官方定义的核心行为在包里的位置最典型的官方用法它解决了什么问题使用时你要注意的点1它标注的是“方法”不是类2参数语义通常要配合 P3返回值设计会直接影响模型效果1. Tool2. P3. ToolMemoryId官方 **package summary** 里还能看到这些非注解类型dev.langchain4j.agent.tool.ToolTool不是普通业务类而是一个注解annotation。它的作用是把某个 Java 方法声明成可被 LLM 调用的工具 / function。LangChain4j 官方包说明里对它的定义很直接被Tool标注的方法会被当作 language model 可以执行/调用的工具函数。(javadoc.io)dev.langchain4j.agent.tool.Tool是什么LangChain4j 的官方主页明确说明这个框架支持“Java 调用 LLM”和“LLM 反过来调用 Java 代码”两个方向Tool就属于后者的核心能力。(docs.langchain4j.dev)在官方源码/Javadoc 语义里Tool的职责是把 Java 方法暴露给模型作为 tool/function配合AiServices自动生成底层ToolSpecification把方法签名、参数、注解信息发送给模型当模型决定调用时自动解析参数并执行方法 (GitHub)官方定义的核心行为官方源码对Tool的执行行为描述得比较完整方法会被自动转成ToolSpecification如果 LLM 选择调用该工具框架会自动解析 arguments 并调用对应方法返回值如果是String会原样传回给 LLM返回值如果是void会返回Success其他类型会被序列化为 JSON 再传回模型 (GitHub)这意味着Tool本质上是高层工具 API 的入口注解让你不必手写底层ToolSpecification和执行器。在包里的位置官方 Javadoc 的dev.langchain4j.agent.tool包里围绕Tool一起工作的几个核心成员有Tool声明工具方法P声明工具参数ReturnBehavior定义工具返回值如何处理ToolExecutionRequest模型生成的工具调用请求ToolSpecification发送给模型的工具描述ToolSpecifications从对象/方法提取工具描述的工具类 (javadoc.io)所以你可以把Tool理解成这一整套 tool-calling 机制的入口注解。最典型的官方用法官方教程说明在高层 API 里你可以直接给 Java 方法加Tool然后在创建 AI Service 时通过.tools(...)注册。AI Service 会自动把这些方法转成ToolSpecification在每次与 LLM 交互时带上当 LLM 决定调用时AI Service 会自动执行相应方法并把返回值再送回模型。(GitHub)典型写法如下classWeatherTools{Tool(查询指定城市天气)StringgetWeather(P(城市名称)Stringcity){returnweatherService.query(city);}}注册方式通常是AssistantassistantAiServices.builder(Assistant.class).chatModel(chatModel).tools(newWeatherTools()).build();这个模式来自官方 Tools 教程描述的高层 Tool API。(GitHub)它解决了什么问题如果不用Tool你通常需要自己维护工具名称工具描述参数 schema参数解析工具执行映射而ToolP的组合把这些从“手工拼装”提升成了“注解驱动配置”。官方教程明确说这一层属于High Level Tool API与之对应的另一层是手动构造ToolSpecification的Low Level Tool API。(GitHub)使用时你要注意的点1它标注的是“方法”不是类Tool是给方法加的不是给整个类加的。类本身通常只是一个工具容器对象。这个从官方对它的定义“Java methods annotated withTool…”就能看出来。(javadoc.io)2参数语义通常要配合P如果只写裸参数模型能拿到类型但未必拿到足够好的参数语义。官方包里把P明确描述为“Parameter of a Tool”也就是专门给工具参数补充语义的注解。(javadoc.io)3返回值设计会直接影响模型效果因为String会原样给 LLM复杂对象会转 JSON所以简单文本型结果用String很直接结构化结果用对象返回更适合下游推理/拼装没有返回内容时void也可用但实际送回模型的是Success(GitHub)LangChain4j 用来把 Java 方法声明成 LLM 可调用工具的注解。这个包dev.langchain4j.agent.tool里当前和注解直接相关的主要有 3 个注解类型ToolPToolMemoryId(Javadoc)如果你问的是“这些注解里各自有哪些注解元素annotation elements”可以这样看1.ToolTool用在方法上把 Java 方法声明成可被 LLM 调用的工具。它现在包含这些注解元素name()工具名默认空字符串没写时通常用方法名value()工具描述类型是String[]returnBehavior()工具返回行为默认ReturnBehavior.TO_LLMsearchBehavior()工具参与 tool search 的方式默认SearchBehavior.SEARCHABLE标注为Experimentalsince 1.12.0metadata()provider-specific 的 JSON 字符串元数据默认{}标注为Experimentalsince 1.10.0(GitHub)2.PP用在参数上给工具参数补充 schema 语义。它现在包含这些注解元素value()参数描述name()参数名如果没写通常回退到反射拿到的参数名required()是否必填默认truejsonSchema()自定义参数 schema 类型默认NoneCustomSchemaElement.class这是后来加入的扩展能力用于自定义参数 schema/coercion (Javadoc)3.ToolMemoryIdToolMemoryId也是这个包里的注解类型用在工具方法参数上表示这个参数承接当前工具执行上下文里的 memory id。Javadoc 的类层级索引里能看到它和Tool一样都是实现java.lang.annotation.Annotation的注解类型。(Javadoc)官方package summary里还能看到这些非注解类型ReturnBehaviorToolExecutionRequest以及和工具规范/执行相关的其他类型其中 package summary 明确列出了P、Tool、ReturnBehavior、ToolExecutionRequest。(Javadoc)给你一个最实用的记忆方式Tool标方法声明“这是工具”P标普通参数声明“这个参数叫什么、怎么描述、是否必填”ToolMemoryId标特殊参数声明“这个参数接收 memoryId” (GitHub)