使用 LangChain4J 实现 Agent 与 Tool 调用

init() 方法在 Quarkus 启动时执行，创建 AiServices 实例，配置 LLM 模型（智谱 GLM-4）、对话记忆提供者及工具列表。chat() 方法作为对外接口，接收用户消息并返回 LLM 响应。

Assistant 接口

package dev.example

import dev.langchain4j.service.MemoryId
import dev.langchain4j.service.SystemMessage
import dev.langchain4j.service.UserMessage
import dev.langchain4j.service.V

interface Assistant {

    @SystemMessage(
        """
        你是一个智能助理，一个能够帮助用户查询附近美食店、蛋糕店、奶茶店、冰品店、特色餐厅等，并能帮助用户下单的助手。
        如果你不知道答案，并发现有函数可以调用以得到答案，请每次都调用函数并以函数的返回结果为正确答案。
        调用函数时不需要向用户说明，直接调用。
        """,
        """
        You are an intelligent assistant, an assistant that can help users search for nearby gourmet shops, cake shops,
        milk tea shops, ice cream shops, specialty restaurants, etc., and help users place orders.
        If you don't know the answer and find a function you can call to get the answer, call the function everytime
        and use the function's return result as the correct answer. When calling a function, there is no need
        explain it to the user, just call it directly.
        """
    )
    @UserMessage("我是用户：{{message}}")
    fun sendMessage(
        @MemoryId memoryId: String,
        @V("message")
        userMessage: String
    ): String

}

Assistant 是一个 Interface，通过注解定义系统提示词和用户消息模板。@SystemMessage 引导 LLM 的行为和能力，提供中英文提示词有助于提升推断准确性。@UserMessage 中的 {{message}} 会被实际输入替换。

Tool 定义

package dev.example

import dev.langchain4j.agent.tool.P
import dev.langchain4j.agent.tool.Tool
import dev.langchain4j.agent.tool.ToolMemoryId
import org.jboss.logging.Logger

class Tools {

    companion object {
        private val LOGGER: Logger = Logger.getLogger("Tools")
    }

    internal class FindAndOrderSomething {

        @Tool(
            "想吃点什么得先找附近的店。查询附近的美食店、蛋糕店、奶茶店、咖啡店、特色餐厅...等。",
            "If user wants something to eat, need to find a nearby store first. Check nearby gourmet shops, cake shops, milk tea shops, coffee shops, special restaurants, etc."
        )
        fun some_nice_stores_nearby(
            @ToolMemoryId memoryId: String,
            @P("当前地点，location") location: String
        ): String {
            LOGGER.info("I am looking for something yammy around $location")
            return ToolResults._1
        }

        @Tool(
            "找出在用户当前地点附近，所有用户指定想吃的东西的店。",
            "Find all stores near the user's current location that have the food the user specifies they want to eat."
        )
        fun something_delicious_nearby(
            @ToolMemoryId memoryId: String,
            @P("当前地点，location") location: String,
            @P("想吃的东西，food product") yammy: String
        ): String {
            LOGGER.info("I am in $location and I am interested in $yammy")
            return ToolResults._2
        }

        @Tool(
            "在一家指定的商店里下单，指定商品名称与数量。",
            "Place an order in a designated store, specifying the food product name and quantity."
        )
        fun press_an_order(
            @ToolMemoryId memoryId: String,
            @P("店名，store") store: String,
            @P("想吃的东西，food product") yammy: String,
            @P("数量，quantity") quantity: Int
        ): String {
            LOGGER.info("Press an order of $quantity $yammy in $store")
            return ToolResults._3
        }
    }
}

每个 Tool 方法使用 @Tool 注解描述功能，@P 注解描述参数。LangChain4J 通过反射机制自动识别并调用这些方法。返回值支持 String 或 JSON 格式。

Web 服务接口

package dev.example

import jakarta.inject.Inject
import jakarta.ws.rs.*
import jakarta.ws.rs.core.MediaType

@Path("/llm")
class WebResource {

    @Inject
    lateinit var aiService: AiService

    @Path("/hello")
    @Consumes(MediaType.TEXT_PLAIN)
    @Produces(MediaType.TEXT_PLAIN)
    @GET
    fun hello(): String {
        return "hello"
    }

    @Path("/chat")
    @Consumes(MediaType.TEXT_PLAIN)
    @Produces(MediaType.TEXT_PLAIN)
    @POST
    fun chat(question: String): String {
        val answer = aiService.chat(question)
        return answer
    }
}

提供 /llm/chat 接口供前端调用，内部委托给 AiService 处理。

测试验证

通过多轮对话验证 Agent 能力：

1. 初始化：用户问候，LLM 回应友好。
2. 能力确认：询问能做什么，LLM 明确列出查询与下单能力。
3. 工具调用 1：用户询问附近好店，LLM 调用 some_nice_stores_nearby，返回模拟店铺列表。
4. 工具调用 2：用户指定想吃拿破仑蛋糕，LLM 调用 something_delicious_nearby，利用上下文记住地点。
5. 工具调用 3：用户下单，LLM 调用 press_an_order，参数准确。
6. 追加订单：用户追加一份，LLM 识别上下文意图再次调用下单工具。
7. 组合调用：用户要求直接找最近店下单，LLM 按顺序组合调用查询与下单工具。

日志显示 Tool 被正确触发，参数传递无误，体现了 Function Calling 的自动化处理能力。

提示词的重要性

提示词工程对 Agent 行为有决定性影响。LLM 虽然智能，但需要明确的正向与反向提示。例如，在 @SystemMessage 中明确要求'调用函数时不需要向用户说明'，可以避免 LLM 暴露内部逻辑，达到逻辑隐藏的目的。提供英文提示词通常能提升 LLM 的推断准确率，因为预训练语料中英语占比更高。

一些技术解释

1. 协议交互机制：LLM 并不直接调用 Function，而是返回包含调用指示的 Body。应用端需解析该 Body 并自行调用 Tool。LangChain4J 封装了这一过程，自动识别要调用的 Tool，完成调用并将结果反馈给 LLM。涉及 Tool 调用时，HTTP 请求会多次 POST，第一次获取工具调用指令，第二次发送工具结果生成最终答案。
2. 模型兼容性：使用 LangChain4J 需满足三个条件：模型原生支持 Function Calling；有对应的 Java SDK 或 HTTP Client 接入；LangChain4J 已适配该模型接口。示例中使用智谱 GLM-4 是因为上述条件均满足。

生产环境部署与安全

在实际生产中，除了功能实现，还需关注以下方面：

1. 密钥管理：API Key 不应硬编码在代码中，应通过环境变量或配置中心注入，如示例中的 System.getenv("ZHIPU_API_KEY")。
2. 内存管理：ChatMemory 需合理设置最大消息数（如 99），防止上下文溢出导致 Token 超限或成本过高。多用户场景下务必使用唯一的 MemoryId 隔离会话。
3. 错误处理：Tool 调用可能失败（如网络超时、参数校验错误）。建议在 Tool 实现中添加 try-catch 块，返回友好的错误信息而非抛出异常中断流程。
4. 限流与熔断：外部 API 调用需考虑速率限制，必要时引入熔断机制，避免单个 Agent 请求拖垮后端服务。
5. 监控与日志：记录每次 Tool 调用的输入输出，便于排查问题及分析用户意图分布。

通过上述实践，可构建更稳定、安全且高效的 LangChain4J Agent 应用。