前言当AI学会“团队协作”在2026年的今天大语言模型(LLM)早已不是新鲜事物。但如何让LLM真正像人类一样“思考-行动-协作”完成复杂任务依然是AI领域的核心挑战。LangChain4j的langchain4j-agentic模块实验性特性为我们提供了一套优雅的解决方案——Agentic AI。本文将带你从零开始深入理解LangChain4j中的Agent概念并通过丰富的代码示例掌握从简单工作流到纯Agentic系统的完整构建过程。无论你是Java开发者还是AI应用架构师这篇文章都将为你打开一扇新的大门。一、Agentic系统Workflow与Pure Agent根据Anthropic研究者的分类Agentic系统架构主要分为两大类类型特点适用场景Workflow通过预定义代码路径和LLM编排工具任务步骤明确、流程固定Pure AgentLLM动态控制自身流程和工具使用任务复杂、路径不确定LangChain4j的langchain4j-agentic模块同时支持这两种模式并且允许你灵活组合。二、快速上手定义你的第一个Agent在LangChain4j中Agent本质上是一个增强版的AI Service。你只需要定义一个接口并用Agent注解标记方法即可。publicinterfaceCreativeWriter{UserMessage( 你是一位创意作家。 根据给定主题生成一个不超过3句话的故事草稿。 只返回故事本身不要其他内容。 主题是{{topic}}。 )Agent(根据主题生成故事)StringgenerateStory(V(topic)Stringtopic);}最佳实践在Agent注解中添加description描述Agent的用途这在纯Agentic模式中尤为重要——其他Agent需要根据描述来决定何时调用它。构建Agent实例CreativeWritercreativeWriterAgenticServices.agentBuilder(CreativeWriter.class).chatModel(myChatModel).outputKey(story)// 指定输出在共享变量中的名称.build();三、核心概念AgenticScope共享变量Agentic系统中的多个Agent需要协作它们通过AgenticScope共享数据。你可以把Scope想象成一个内存中的共享数据池Agent通过outputKey将结果写入ScopeAgent通过V注解从Scope读取所需参数Scope自动记录所有Agent的调用序列和响应// Agent写入数据.outputKey(story)// Agent读取数据UserMessage(故事是{{story}})StringeditStory(V(story)Stringstory);四、工作流模式实战4.1 顺序工作流Sequential Workflow最简单的模式Agent依次执行前一个的输出作为后一个的输入。// 定义三个AgentCreativeWritercreativeWriterAgenticServices.agentBuilder(CreativeWriter.class).chatModel(BASE_MODEL).outputKey(story).build();AudienceEditoraudienceEditorAgenticServices.agentBuilder(AudienceEditor.class).chatModel(BASE_MODEL).outputKey(story).build();StyleEditorstyleEditorAgenticServices.agentBuilder(StyleEditor.class).chatModel(BASE_MODEL).outputKey(story).build();// 组合成顺序工作流UntypedAgentnovelCreatorAgenticServices.sequenceBuilder().subAgents(creativeWriter,audienceEditor,styleEditor).outputKey(story).build();// 执行MapString,ObjectinputMap.of(topic,龙与巫师,style,奇幻,audience,年轻人);Stringstory(String)novelCreator.invoke(input);4.2 循环工作流Loop Workflow通过循环迭代逐步优化结果直到满足条件。// 评分AgentStyleScorerstyleScorerAgenticServices.agentBuilder(StyleScorer.class).chatModel(BASE_MODEL).outputKey(score).build();// 循环工作流评分 - 编辑 - 再评分直到分数0.8或达到最大迭代次数UntypedAgentstyleReviewLoopAgenticServices.loopBuilder().subAgents(styleScorer,styleEditor).maxIterations(5).exitCondition(scope-scope.readState(score,0.0)0.8).build();4.3 并行工作流Parallel Workflow多个独立任务同时执行提高效率。FoodExpertfoodExpertAgenticServices.agentBuilder(FoodExpert.class).chatModel(BASE_MODEL).outputKey(meals).build();MovieExpertmovieExpertAgenticServices.agentBuilder(MovieExpert.class).chatModel(BASE_MODEL).outputKey(movies).build();EveningPlannerAgentplannerAgenticServices.parallelBuilder(EveningPlannerAgent.class).subAgents(foodExpert,movieExpert).executor(Executors.newFixedThreadPool(2)).output(scope-{// 组合两个Agent的输出ListStringmoviesscope.readState(movies,List.of());ListStringmealsscope.readState(meals,List.of());returncombinePlans(movies,meals);}).build();4.4 条件工作流Conditional Workflow根据条件动态选择执行哪个Agent。// 路由Agent分类用户请求CategoryRouterrouter// ...// 条件工作流UntypedAgentexpertsAgentAgenticServices.conditionalBuilder().subAgents(scope-scope.readState(category)MEDICAL,medicalExpert).subAgents(scope-scope.readState(category)LEGAL,legalExpert).subAgents(scope-scope.readState(category)TECHNICAL,technicalExpert).build();五、高级特性5.1 异步AgentAsynchronous通过async(true)让Agent异步执行不阻塞主流程。FoodExpertfoodExpertAgenticServices.agentBuilder(FoodExpert.class).async(true)// 异步执行.outputKey(meals).build();5.2 流式AgentStreaming支持TokenStream返回类型实现流式输出。publicinterfaceStreamingCreativeWriter{AgentTokenStreamgenerateStory(V(topic)Stringtopic);}StreamingCreativeWriterwriterAgenticServices.agentBuilder(StreamingCreativeWriter.class).streamingChatModel(streamingModel).outputKey(story).build();TokenStreamstreamwriter.generateStory(龙与巫师);注意流式Agent只有在工作流中作为最后一个Agent时才会将流式响应传播给调用方。5.3 动态模型选择根据Scope状态动态选择使用哪个模型如简单任务用廉价模型复杂任务用高级模型。StoryEditoreditorAgenticServices.agentBuilder(StoryEditor.class).chatModel(scope-{CritiqueResultcritiquescope.readState(critique);returncritique.score()7.8?enhancedModel():baseModel();}).build();5.4 错误处理Error Handling通过errorHandler优雅处理Agent执行中的异常。UntypedAgentagentAgenticServices.sequenceBuilder().errorHandler(ctx-{if(ctx.exception()instanceofMissingArgumentException){// 补全缺失参数并重试ctx.agenticScope().writeState(topic,默认主题);returnErrorRecoveryResult.retry();}returnErrorRecoveryResult.throwException();}).build();六、可观测性监控与调试6.1 AgentListener监听器注册监听器跟踪Agent调用全过程。CreativeWriterwriterAgenticServices.agentBuilder(CreativeWriter.class).listener(newAgentListener(){OverridepublicvoidbeforeAgentInvocation(AgentRequestreq){System.out.println(开始调用: req.agentName());}OverridepublicvoidafterAgentInvocation(AgentResponseresp){System.out.println(调用完成输出: resp.output());}}).build();6.2 AgentMonitor监控器内置的AgentMonitor可以记录所有Agent调用并生成可视化HTML报告。AgentMonitormonitornewAgentMonitor();// 注册到根AgentStyledWriterwriterAgenticServices.sequenceBuilder().listener(monitor)// 自动继承给所有子Agent.build();// 执行任务...Stringresultwriter.invoke(input);// 生成HTML报告HtmlReportGenerator.generateReport(monitor,Path.of(report.html));生成的报告包含Agent系统拓扑图每次调用的耗时、Token数、输入输出嵌套调用树形结构七、声明式API更简洁的Agent定义LangChain4j提供了一套注解让你用更声明式的方式定义Agent系统。publicinterfaceEveningPlannerAgent{ParallelAgent(outputKeyplans,subAgents{FoodExpert.class,MovieExpert.class})ListEveningPlanplan(V(mood)Stringmood);OutputstaticListEveningPlancombine(V(movies)ListStringmovies,V(meals)ListStringmeals){// 组合逻辑returncombined;}}// 创建Agent系统EveningPlannerAgentagentAgenticServices.createAgenticSystem(EveningPlannerAgent.class,BASE_MODEL);支持的注解包括ChatModelSupplier/StreamingChatModelSupplierChatMemorySupplierToolsSupplierSystemMessageProviderSupplier等等八、纯Agentic AISupervisor模式当任务路径不确定时可以使用Supervisor Agent。它会自主规划决定调用哪个子Agent、何时完成任务。// 定义子Agent取款、存款、货币兑换WithdrawAgentwithdraw// ...CreditAgentcredit// ...ExchangeAgentexchange// ...// 创建SupervisorSupervisorAgentbankSupervisorAgenticServices.supervisorBuilder().chatModel(PLANNER_MODEL).subAgents(withdraw,credit,exchange).responseStrategy(SupervisorResponseStrategy.SUMMARY).build();// 用户自由输入指令StringresponsebankSupervisor.invoke(从Mario账户取100美元然后兑换成欧元);Supervisor会自主决定先调用WithdrawAgent再调用ExchangeAgent最后总结结果并返回九、最佳实践与注意事项描述清晰为每个Agent添加详细description帮助Supervisor或其他Agent理解其用途。合理使用异步IO密集型或耗时操作设为异步提高吞吐量。监控先行开发阶段务必启用AgentMonitor便于调试和优化。错误兜底为关键Agent配置errorHandler避免整个系统崩溃。模型匹配根据任务复杂度动态选择模型平衡成本与质量。实验性质langchain4j-agentic模块目前是实验性的API可能在未来版本发生变化。结语LangChain4j的Agentic模块为Java开发者提供了一套强大、类型安全、可观测的AI Agent构建框架。从固定的Workflow到自主的Pure Agent你可以根据业务需求灵活选择。随着LLM能力的增强Agentic AI必将成为下一代智能应用的核心范式。希望这篇文章能帮助你快速上手LangChain4j Agentic开发。如果你有任何问题或心得欢迎在评论区交流讨论参考资料LangChain4j官方文档 - AgentsAnthropic - Building effective agents