Java工程师视角：j-langchain 快速上手 Agent

引言为什么 Java 工程师也需要 Agent过去两年几乎所有 AI Agent 教程都默认使用 Python。你看到的往往是LangChainLangGraphAutoGenCrewAI但现实情况是大多数企业后端系统并不是 Python而是 Java。很多 Java 工程师会遇到一个非常现实的问题我已经有 Spring Boot、MySQL、Redis、MQ、公司内部接口难道为了做 AI就要整套系统重写成 Python答案当然是否定的。对于绝大多数企业场景更合理的方式是在现有 Java 服务里直接接入 AI 能力。而 j-langchain就是专门为这件事准备的。它是一个纯 Java 实现的 AI 应用开发框架对标 Python 版 LangChain帮助 Java 工程师快速实现问答摘要翻译RAG 知识库工具调用Agent流式输出而且它的使用方式非常符合 Java 工程师熟悉的“链式调用”和“组件编排”思维。一句话理解j-langchain 用 Java 写 LangChain。一、j-langchain 到底是什么j-langchain 的核心思想其实很简单把 Prompt、模型、输出解析器、工具调用像流水线一样串起来。也就是说一次 AI 调用本质上是输入 → Prompt 模板 → 大模型 → 输出解析 → 最终结果在 j-langchain 里这种流水线被称为FlowInstance你可以把它理解为类似 Spring 中的一条调用链类似责任链模式类似一个“AI 工作流”而 Agent就是在这个基础上继续增加工具多步决策推理循环所以如果你会 Java、会 Spring其实上手会非常快。二、第一步添加依赖首先在 Maven 项目中加入依赖dependencygroupIdorg.salt.jlangchain/groupIdartifactIdj-langchain/artifactIdversion1.0.12/version/dependency如果你使用的是 Spring Boot 项目建议直接放到现有服务里。例如my-project ├─ src/main/java ├─ src/test/java ├─ application.yml └─ pom.xml这样后面就可以直接在现有 Controller、Service 中接入 AI。三、第二步配置 API Keyj-langchain 默认支持多种模型提供商。例如阿里云通义千问OpenAIOllama本地模型对于国内开发者最容易开始的通常是通义千问。在application.yml中加入spring:ai:aliyun:api-key:${ALIYUN_KEY}然后在系统环境变量里设置exportALIYUN_KEY你的keyWindowsset ALIYUN_KEY你的key不要把 Key 写死在代码里很多人第一次测试时会直接这样写StringapiKeyxxxxxx;这非常危险。推荐始终使用环境变量application.yml.env这样未来无论你换模型换环境部署服务器提交 Git都不会出问题。四、Hello AI三步构建第一个 AI 调用j-langchain 最核心的体验就是Prompt → 模型 → 输出解析下面这个例子就是最小可运行版本。Testpublicvoidhello(){// Step 1定义 Prompt 模板PromptTemplatepromptPromptTemplate.fromTemplate(Tell me a joke about ${topic});// Step 2选择模型ChatAliyunllmChatAliyun.builder().model(qwen-plus).build();// Step 3组装流水线FlowInstancechainchainActor.builder().next(prompt).next(llm).next(newStrOutputParser()).build();// Step 4执行ChatGenerationresultchainActor.invoke(chain,Map.of(topic,Java));System.out.println(result.getText());}如果你是 Java 工程师可以把它理解成输入参数 ↓ PromptTemplate 负责拼 Prompt ↓ ChatAliyun 负责调用大模型 ↓ StrOutputParser 负责解析返回值最终得到字符串结果。整个过程其实非常像Controller → Service → Converter → Result只是中间调用的不是数据库而是大模型。五、核心概念为什么 PromptTemplate 很重要很多 Java 工程师第一次接触 Prompt 时会把它理解成一段字符串。但在 j-langchain 中更推荐你把 Prompt 当成“模板”。例如PromptTemplatepromptPromptTemplate.fromTemplate(请用中文总结下面内容${content});后面真正执行时只需要传入变量Map.of(content,article)这样做的好处是Prompt 和业务逻辑分离更容易维护更适合复用更适合后期抽到配置文件里在企业项目里一个 Prompt 往往会不断调整。如果你把它写死在代码里后面会非常难维护。六、流式输出像 ChatGPT 一样逐字显示默认情况下大模型会等全部生成完再一次性返回。但真实产品里这种体验并不好。用户会感觉卡住了。所以大多数 AI 产品都会使用流式输出。在 j-langchain 中只需要调用llm.stream()示例TestpublicvoidstreamOutput(){ChatAliyunllmChatAliyun.builder().model(qwen-plus).build();AIMessageChunkchunkllm.stream(请用一句话解释什么是 Agent);StringBuildersbnewStringBuilder();while(chunk.getIterator().hasNext()){Stringtokenchunk.getIterator().next().getContent();sb.append(token);System.out.print(token);}}运行效果会像Agent 是一种能够自主完成目标的 AI 系统。但它不是一次性打印而是一个字一个字出来。这对于WebSocketSSE前端聊天框实时日志都非常有用。如果你已经在 Spring Boot 中做过 SSE那么这里会非常容易接。七、结构化输出不要让 AI 返回一大段乱文本很多业务系统并不希望 AI 返回一大段自然语言。真正需要的往往是{name:Java,year:1995}因为这样才能保存数据库返回前端继续下一步处理j-langchain 提供了JsonOutputParser示例TestpublicvoidjsonOutput(){ChatAliyunllmChatAliyun.builder().model(qwen-plus).build();FlowInstancechainchainActor.builder().next(llm).next(newJsonOutputParser()).build();ChatGenerationresultchainActor.invoke(chain,请以 JSON 格式列出3个编程语言包含 name 和 year 字段。);System.out.println(result.getText());}输出示例[{name:Java,year:1995},{name:Python,year:1991},{name:Go,year:2009}]这一步非常重要。因为真正的企业 Agent最后都需要让 AI 输出“可被程序消费的数据”。八、事件流调试为什么 Agent 经常“看起来没问题实际上有问题”很多人第一次做 AI 调用时会遇到一个问题最终结果不对但不知道是哪一步出了问题。可能是Prompt 写错模型理解错Parser 解析失败工具返回异常j-langchain 提供了一个非常实用的能力streamEvent()它会把整个链路中每个节点的输入输出都打印出来。TestpublicvoideventMonitor(){PromptTemplatepromptPromptTemplate.fromTemplate(Tell me a joke about ${topic});ChatAliyunllmChatAliyun.builder().model(qwen-plus).build();FlowInstancechainchainActor.builder().next(prompt).next(llm).next(newStrOutputParser()).build();EventMessageChunkeventschainActor.streamEvent(chain,Map.of(topic,Java));while(events.getIterator().hasNext()){EventMessageChunkeventevents.getIterator().next();System.out.println(event.toJson());}}你会看到类似on_chain_start on_llm_start on_llm_end on_parser_end on_chain_end对于调试复杂 Agent这个功能几乎是必备的。九、切换到本地模型不用花钱也能跑 Agent很多人刚开始做 Agent 时最担心的是调 API 太贵。其实你完全可以先在本地跑开源模型。最常见的方法就是 Ollama。先安装 Ollama然后拉取模型ollama pull qwen2.5:0.5b然后只需要把这一行ChatAliyunllmChatAliyun.builder()换成ChatOllamallmChatOllama.builder().model(qwen2.5:0.5b).build();完整代码TestpublicvoidlocalModel(){PromptTemplatepromptPromptTemplate.fromTemplate(用中文回答${question});ChatOllamallmChatOllama.builder().model(qwen2.5:0.5b).build();FlowInstancechainchainActor.builder().next(prompt).next(llm).next(newStrOutputParser()).build();ChatGenerationresultchainActor.invoke(chain,Map.of(question,Java 和 Python 有什么区别));System.out.println(result.getText());}其余代码完全不用改。这就是框架抽象层最大的价值换模型不换业务逻辑。十、从“调用模型”到“真正的 Agent”还差什么很多 Java 工程师跑通第一个 Demo 后会有一个误区我已经在用 AI 了。其实这时候你只是完成了Prompt LLM真正的 Agent还需要工具调用多步推理状态记忆ReAct 循环多轮决策例如用户帮我查今天北京天气如果下雨就提醒我带伞。这已经不是一个简单的 Prompt而是调天气工具判断结果决定是否提醒这类能力通常会在后面的 ReAct Agent 中实现。而 j-langchain 后续也支持ToolAgentExecutorReAct多工具路由所以你现在看到的只是第一步。十一、核心 API 一张表看懂API作用PromptTemplate.fromTemplate()创建 Prompt 模板ChatAliyun.builder()创建通义千问模型ChatOllama.builder()创建本地模型chainActor.builder()构建调用链chainActor.invoke()同步执行llm.stream()流式输出JsonOutputParserJSON 解析streamEvent()调试链路如果你已经会 Spring、MyBatis、责任链模式那么理解这些 API 会非常快。结语对于 Java 工程师来说最大的障碍从来不是不会 AI而是过去没有一个足够 Java 化、足够工程化的 AI 框架。而 j-langchain 正在解决这个问题。一句话总结PromptTemplate 负责“说什么”ChatAliyun / ChatOllama 负责“让模型回答”Parser 负责“把结果变成程序可用的数据”FlowInstance 负责“把这些串起来”。只要你会 Java就已经可以开始做 AI 应用了。下一步你就可以继续进入多步链式编排RAGTool CallingReAct Agent多 Agent 系统而这一切都不需要离开你熟悉的 Java 技术栈。