LangChain4j全集-14-Agents and Agentic AI

Agents and Agentic AI梳理

下面我按这个页面的内容，结合你是 Spring Boot 开发者的视角，帮你把 LangChain4j 里面的Agents and Agentic AI梳理一遍。

这个页面主要讲的是：
如何使用langchain4j-agentic模块来构建“智能体应用”，也就是让多个 AI 服务像一个团队一样协作，完成更复杂的任务。

1. 先说结论：Agentic AI 是什么？

你可以先这样理解：

普通 AI 应用：

用户问题 -> 调用一次大模型 -> 返回答案

Agentic AI 应用：

用户目标 -> AI 分析任务 -> 拆分步骤 -> 调用不同 Agent -> 可能调用工具、数据库、接口 -> 汇总结果 -> 返回最终答案

也就是说，Agentic AI 更像是一个“AI 工作流系统”。

举个例子：

你让 AI：

帮我写一篇适合小学生阅读的科幻故事，并检查语言风格是否足够简单。

普通 AI 可能直接写一篇。

Agentic AI 可能这样做：

CreativeWriter Agent：先写故事 AudienceEditor Agent：改成适合小学生 StyleScorer Agent：检查语言是否足够简单 FinalReview Agent：最终润色

每个 Agent 都负责一件事，组合起来完成复杂任务。

2. 页面开头的 note：实验性模块

文档一开始强调：

langchain4j-agentic 模块目前是 experimental，未来版本可能变化。

也就是说，这个模块还不是完全稳定 API。

对于你这种 Spring Boot 开发者来说，要注意：

• 可以学习、实验、做原型；
• 生产环境使用要谨慎；
• 升级 LangChain4j 版本时，相关 API 可能会变；
• 最好把 Agent 相关代码封装在单独的 service 层，避免后续改动影响业务代码。

例如：

Controller -> YourBusinessService -> AgenticService / Agent Workflow

不要让 Controller 直接依赖太多 agentic 模块的细节。

3. Agentic systems：智能体系统是什么？

文档中说：

虽然 AI Agent 没有统一定义，但现在有一些常见模式，可以通过多个 AI 服务组合，完成复杂任务。

你可以理解为：

Agentic System = 多个 AI 能力 + 编排逻辑 + 上下文管理 + 工具调用

它解决的问题是：

普通大模型只会“回答”，但复杂业务通常需要：

• 拆任务；
• 调接口；
• 查数据库；
• 调工具；
• 多步骤推理；
• 保存中间结果；
• 根据结果继续判断；
• 多个 AI 角色协作。

这就是 Agentic System 要做的事情。

4. Anthropic 提到的两大类：Workflows 和 Pure Agents

文档引用了 Anthropic 的观点，把 Agentic System 分成两大类：

1. Workflows：工作流型 2. Pure Agents：纯智能体型

这两个概念很重要。

4.1 Workflows：工作流型 Agent

Workflow 就是：流程由程序员提前设计好。

比如你写死流程：

第一步：写故事 第二步：改成儿童风格 第三步：评分 第四步：如果分数不够，再重新改 第五步：返回结果

这就是 Workflow。

特点：

Spring Boot 业务系统里面，我个人建议你优先学习 Workflow。

因为企业应用通常需要：

• 可控；
• 可审计；
• 可测试；
• 可回滚；
• 可观测；
• 出错能定位。

Workflow 更符合这些要求。

4.2 Pure Agents：纯智能体型

Pure Agent 是让大模型自己决定：

下一步该做什么？ 调用哪个工具？ 调用哪个 Agent？ 什么时候停止？

比如用户说：

帮我分析这个客户为什么流失，并给出挽回方案。

Pure Agent 可能自己判断：

1. 先查客户订单记录 2. 再查客服工单 3. 再分析聊天记录 4. 再调用营销方案 Agent 5. 最后生成挽回建议

这些步骤不是你写死的，而是大模型自己规划的。

特点：

所以 Pure Agent 适合：

• 探索型任务；
• 助手型应用；
• 自动化研究；
• 复杂问题分析；
• 对稳定性要求没有那么高的场景。

5. langchain4j-agentic 模块是干什么的？

文档中说：

langchain4j-agentic 模块提供了一组抽象和工具， 帮助你构建 workflow 和 pure agentic AI 应用。

它主要帮你做几件事：

5.1 定义 Agent

让你可以把一个 AI 能力定义成一个 Java 接口方法。

比如：

publicinterfaceCreativeWriter{@UserMessage(""" You are a creative writer. Generate a draft of a story no more than 3 sentences long around the given topic. Return only the story and nothing else. The topic is {{topic}}. """)@Agent("Generates a story based on the given topic")StringgenerateStory(@V("topic")Stringtopic);}

这个CreativeWriter就是一个 Agent。

它的作用是：

根据 topic 生成一个短故事。

5.2 管理工具调用

Agent 不一定只能调用大模型，它也可以调用工具。

比如：

• 查数据库；
• 调 REST API；
• 查订单；
• 发邮件；
• 生成文件；
• 调用内部系统；
• 查询向量数据库；
• 调用搜索引擎。

在 LangChain4j 里，这类能力通常通过 Tool / Function Calling 暴露给大模型。

Agentic 模块可以把这些能力组合进工作流或智能体系统里。

5.3 维护上下文

复杂任务经常需要多个步骤共享数据。

例如：

topic = "太空旅行" story = CreativeWriter 生成的故事 editedStory = AudienceEditor 修改后的故事 score = StyleScorer 打分结果

这些中间结果需要保存起来，后面的 Agent 才能使用。

Agentic 模块会帮你管理这些输入输出和上下文。

你可以把它理解成一个 Map：

{"topic":"太空旅行","story":"...","editedStory":"...","score":8.5}

这类上下文在 Agent 工作流里面非常重要。

6. Agents in LangChain4j：LangChain4j 里的 Agent 是什么？

文档中说：

LangChain4j 中的 Agent 是一个使用 LLM 执行特定任务的组件。

也就是说，每个 Agent 最好只负责一类清晰任务。

比如：

CreativeWriter：负责创作 AudienceEditor：负责根据目标读者修改 StyleEditor：负责调整风格 Reviewer：负责审核 Translator：负责翻译 SummaryAgent：负责总结 RouterAgent：负责判断走哪个分支

不要让一个 Agent 什么都干。

好的 Agent 设计应该像好的 Java 类设计一样：

职责单一，边界清晰。

这和 Spring Boot 里面的 Service 设计很像：

UserServiceOrderServicePaymentServiceNotificationService

不要写一个超级大的：

EverythingService

Agent 也是一样。

7. @Agent 注解是干什么的？

文档中最核心的注解之一就是：

@Agent

它的作用是：标记某个方法是一个 Agent 能力。

比如：

@Agent("Generates a story based on the given topic")StringgenerateStory(@V("topic")Stringtopic);

这里的含义是：

generateStory 方法是一个 Agent。 这个 Agent 的能力是：根据给定主题生成故事。

7.1 @Agent 里的描述有什么用？

文档特别说，最好给 Agent 提供简短描述。

为什么？

因为在 Pure Agent 模式下，可能会有别的 Agent 或 orchestrator 需要知道：

这个 Agent 是干什么的？ 什么时候应该调用它？ 它能解决什么问题？

比如你有三个 Agent：

CreativeWriter：写故事 Translator：翻译文本 MathSolver：解决数学题

当用户输入：

帮我把这个故事翻译成英文

系统就应该知道要调用Translator，而不是MathSolver。

所以描述越清晰，调度越准确。

你可以把它理解成：
@Agent的描述就是给大模型看的“接口文档”。

8. Agent 的 name：为什么每个 Agent 要有名字？

文档说：

Agents must also have a name uniquely identifying them inside the agentic system.

意思是：

每个 Agent 在一个 agentic system 里都要有唯一名称。

原因很简单：

如果多个 Agent 协作，系统要区分它们。

比如：

creativeWriter audienceEditor styleScorer translator

如果不指定名称，LangChain4j 会默认使用@Agent标注的方法名作为名称。

例如：

@AgentStringgenerateStory(...)

默认 name 可能就是：

generateStory

但是在复杂系统中，我建议你显式指定清楚。

例如：

@Agent(name="creativeWriter",description="Generates a short story based on a topic")

或者通过 builder 编程式设置。

9. @UserMessage 是干什么的？

示例里面有：

@UserMessage(""" You are a creative writer. Generate a draft of a story no more than 3 sentences long around the given topic. Return only the story and nothing else. The topic is {{topic}}. """)

这个和普通 LangChain4j AI Service 里的用法类似。

它的作用是：

定义发送给大模型的用户提示词模板。

你可以理解成 Prompt 模板。

里面的：

{{topic}}

是变量占位符。

调用时传入：

generateStory("机器人和小猫")

LangChain4j 会替换成：

The topic is 机器人和小猫.

然后发给大模型。

10. @V 是干什么的？

示例中有：

StringgenerateStory(@V("topic")Stringtopic);

@V的作用是给参数命名，让它能对应 Prompt 里的变量。

@V("topic")Stringtopic

对应：

{{topic}}

所以：

generateStory("太空冒险")

会把：

{{topic}}

替换成：

太空冒险

你可以把@V理解成：

参数绑定注解。

类似 Spring MVC 里面的：

@PathVariable@RequestParam@RequestBody

只不过这里是把 Java 参数绑定到 Prompt 变量里。

11. Agent 和普通 AI Service 有什么区别？

从写法上看，它们很像。

普通 AI Service 可能这样：

interfaceAssistant{@UserMessage("回答用户问题：{{question}}")Stringchat(@V("question")Stringquestion);}

Agent 则加了：

@Agent

比如：

interfaceWriterAgent{@UserMessage("根据主题 {{topic}} 写一个故事")@Agent("Writes a story")Stringwrite(@V("topic")Stringtopic);}

区别在于：

一句话：

AI Service 是单个 AI 能力； Agent 是可以被编排、调度、协作的 AI 能力。

12. AgenticServices.agentBuilder() 是干什么的？

文档后面提到：

AgenticServices.agentBuilder()

它的作用是创建 Agent 实例。

大致思路类似普通 LangChain4j 的AiServices.builder()。

你可以理解成：

通过 builder，把接口 + 模型 + 配置 组装成一个真正可调用的 Agent 对象。

概念上类似：

CreativeWritercreativeWriter=AgenticServices.agentBuilder(CreativeWriter.class).chatModel(chatModel).build();

这里的意思是：

用指定的大模型 chatModel，为 CreativeWriter 接口创建一个 Agent 实例。

在 Spring Boot 里面，你可以把它注册成 Bean。

例如概念上：

@ConfigurationpublicclassAgentConfig{@BeanCreativeWritercreativeWriter(ChatLanguageModelchatModel){returnAgenticServices.agentBuilder(CreativeWriter.class).chatModel(chatModel).build();}}

然后在业务服务中注入：

@ServicepublicclassStoryService{privatefinalCreativeWritercreativeWriter;publicStoryService(CreativeWritercreativeWriter){this.creativeWriter=creativeWriter;}publicStringcreateStory(Stringtopic){returncreativeWriter.generateStory(topic);}}

13. 工作流编排是干什么的？

Agentic AI 里最重要的一点就是：

不是只创建一个 Agent，而是把多个 Agent 编排起来。

常见模式有几种。

13.1 顺序执行 Sequential Workflow

这是最常见的模式。

Agent A -> Agent B -> Agent C -> 最终结果

例如：

CreativeWriter 写初稿 -> AudienceEditor 改成儿童可读 -> StyleEditor 改成幽默风格 -> 返回最终故事

适合场景：

• 文档生成；
• 内容润色；
• 审核流程；
• 数据清洗；
• 多步骤业务处理；
• 报告生成。

Spring Boot 中类似：

result1=serviceA.process(input);result2=serviceB.process(result1);result3=serviceC.process(result2);returnresult3;

只不过这里的 service 是 AI Agent。

13.2 并行执行 Parallel Workflow

多个 Agent 同时处理同一个任务，然后汇总结果。

-> Agent A 用户输入 -> Agent B -> Agent C ↓ 汇总 Agent

例如写一篇产品分析报告：

MarketAgent：分析市场 UserAgent：分析用户 CompetitorAgent：分析竞品 RiskAgent：分析风险 SummaryAgent：汇总报告

适合场景：

• 多角度分析；
• 多专家评审；
• 内容比较；
• 风险评估；
• 多模型投票。

优点：

速度快，多视角。

缺点：

成本更高，因为会同时调用多个模型。

13.3 条件分支 Conditional Workflow

根据前一步结果，决定走哪个 Agent。

输入 -> 判断类型 -> 如果是投诉：ComplaintAgent -> 如果是咨询：ConsultAgent -> 如果是退款：RefundAgent

这很像 Java 里的：

if(...){...}elseif(...){...}

适合场景：

• 工单分类；
• 客服路由；
• 意图识别；
• 多业务入口；
• 智能客服；
• 审批流程。

例如：

用户说：我要退款 系统判断：退款类问题 调用：RefundAgent

13.4 循环 Loop Workflow

循环模式是：

执行 Agent -> 评估结果 -> 不合格，继续修改 -> 合格，结束

例如：

写故事 -> 打分 -> 分数 < 8，继续润色 -> 分数 >= 8，返回

适合场景：

• 文案优化；
• 代码修复；
• 自动评审；
• 自动改错；
• 反复生成直到达标。

但要注意：

一定要设置最大循环次数。

否则可能变成：

一直调用大模型，一直花钱。

在生产环境里非常重要。

14. 上下文管理：为什么重要？

多个 Agent 协作时，最麻烦的是中间数据传递。

比如：

topic -> story -> editedStory -> score -> finalStory

如果你手动传，代码会越来越乱。

Agentic 模块的一个目标就是简化这个过程。

你可以把上下文理解成一个共享数据区。

类似：

Map<String,Object>context=newHashMap<>();context.put("topic","太空旅行");context.put("story",story);context.put("score",score);

每个 Agent 可以从上下文里拿自己需要的数据，也可以把结果写回上下文。

这对于复杂 workflow 非常有用。

15. Agent 的描述为什么在 Pure Agent 里特别重要？

在 Workflow 里，调用顺序是你写死的：

先 A 后 B 再 C

所以 Agent 描述没那么关键。

但在 Pure Agent 里，调用谁是大模型决定的。

大模型需要看 Agent 描述来判断：

我现在应该调用哪个 Agent？

如果描述写得很模糊：

@Agent("处理内容")

大模型可能不知道什么时候用它。

更好的写法是：

@Agent("Generates a short creative story based on a given topic")

或者：

@Agent("Translates Chinese text into fluent English")

描述要做到：

• 短；
• 准；
• 明确输入；
• 明确输出；
• 明确适用场景。

16. Agent 名称设计建议

建议你给 Agent 起语义清晰的名字。

好的名字：

creativeWriter audienceEditor storyReviewer customerIntentClassifier refundPolicyAgent orderQueryAgent

不好的名字：

agent1 testAgent doSomething processor handler

因为在复杂系统里，Agent 名字可能会出现在：

• 日志；
• 调试信息；
• tracing；
• prompt；
• 其他 Agent 的工具列表；
• workflow 配置中。

名字不清晰，后面很难排查问题。

17. 对 Spring Boot 开发者来说怎么落地？

你可以按照这个结构来组织代码。

17.1 定义 Agent 接口

publicinterfaceCreativeWriter{@UserMessage(""" 你是一个创意作家。 请围绕主题 {{topic}} 写一个不超过 3 句话的故事。 只返回故事内容，不要解释。 """)@Agent("根据给定主题生成短故事")StringgenerateStory(@V("topic")Stringtopic);}

17.2 配置 Agent Bean

@ConfigurationpublicclassAgentConfig{@BeanCreativeWritercreativeWriter(ChatLanguageModelchatModel){returnAgenticServices.agentBuilder(CreativeWriter.class).chatModel(chatModel).build();}}

17.3 在 Service 中使用

@ServicepublicclassStoryApplicationService{privatefinalCreativeWritercreativeWriter;publicStoryApplicationService(CreativeWritercreativeWriter){this.creativeWriter=creativeWriter;}publicStringgenerate(Stringtopic){returncreativeWriter.generateStory(topic);}}

17.4 Controller 暴露接口

@RestController@RequestMapping("/stories")publicclassStoryController{privatefinalStoryApplicationServicestoryService;publicStoryController(StoryApplicationServicestoryService){this.storyService=storyService;}@GetMappingpublicStringgenerate(@RequestParamStringtopic){returnstoryService.generate(topic);}}

18. 学习这页文档时你要重点掌握什么？

我建议你按下面顺序学。

第一层：理解基本概念

先搞明白：

Agent 是什么？ Agentic System 是什么？ Workflow 和 Pure Agent 有什么区别？

这是基础。

第二层：会定义单个 Agent

重点掌握：

@Agent@UserMessage@VAgenticServices.agentBuilder()

你先能写一个最简单的 Agent。

第三层：会组合多个 Agent

重点掌握：

顺序执行 并行执行 条件分支 循环优化

这才是 Agentic AI 真正有价值的地方。

第四层：结合工具调用

比如 Agent 能调用：

数据库查询工具 HTTP 接口工具 订单查询工具 库存查询工具 知识库检索工具

这样 AI 才能真正和你的业务系统结合。

第五层：生产化问题

最后考虑：

日志 超时 重试 异常处理 Token 成本 最大循环次数 权限控制 敏感信息过滤 结果校验 可观测性

这些是 Spring Boot 项目真正上线时绕不开的问题。

19. 你可以把 LangChain4j Agentic 模块类比成什么？

如果你熟悉 Spring Boot，可以这样类比：

所以它不是一个完全陌生的东西。

本质上还是：

定义组件 -> 注入模型 -> 编排流程 -> 对外提供能力

20. 简单总结

这个页面的核心内容可以总结成一句话：

LangChain4j 的 agentic 模块让你可以把多个基于大模型的 AI Service 定义成 Agent，然后通过工作流或智能体调度的方式组合起来，完成比单次问答更复杂的任务。

你需要重点记住：

1. @Agent 用来声明一个 Agent。 2. Agent 最好职责单一。 3. Agent 要有清晰的 name 和 description。 4. Workflow 是程序员控制流程，稳定可控。 5. Pure Agent 是大模型自己决定流程，灵活但不可控。 6. 多 Agent 协作时，上下文管理非常重要。 7. 在 Spring Boot 项目里，建议把 Agent 配置成 Bean，在 Service 层封装使用。

如果你刚开始学，我建议你先不要一上来就做 Pure Agent。

更推荐学习路径是：

普通 AI Service -> 单个 Agent -> 顺序 Workflow -> 条件 Workflow -> 循环 Workflow -> 工具调用 -> Pure Agent

这样会比较稳。