简介

langgraph4j是java技术栈ai agent框架，深入掌握其源码与原理，指导agent的开发，重构/改造框架，增加特性，快速定位和修复bug，发布私有版本

系列内容：

> 架构，包括逻辑架构，运行架构，集成架构

> 状态图

>> 状态和序列化

>> StatGraph分析

>> 推理框架

> 编译图

> 执行图

>> 检查点

>> aync-generator

>> 执行分析

>>> 中断/恢复

>>> 取消执行

> agent框架

>> agent

>> 多agent

> 观测&studio

本文分析agent框架的子agent/子图消息过滤，agent在推理过程产生很多的消息，ToolResponseMessage，AssistantMessage等，在多agent环境，这些消息在当前agent执行完，一同流转到下一个agent，这些消息对下一个agent通常没有价值，反而让提示词混乱，暴涨，影响agent的推理，因此需要过滤，过滤有两个方面

> 推理前提示词过滤，当前agent主动减少上一个agent的流入

> agent只保留返回的messages的最后一条

本文基于langgraph4j v1.8.20

关键词

workflow/agentic

langchain4j/springai

缩写

langgraph4j缩写lg4j

spring ai 缩写 sa

参考资料

Overview - LangGraph4j  langgraph4j官网

mp.weixin.qq.com/mp/appmsgalbum?action=getalbum&album_id=4540202703779627014

spring ai Alibaba原理源码分析，包括spring ai部分

 lg4j概览

本节逻辑架构，大概了解lg4j

上图 lg4j的逻辑架构图，逻辑架构展示lg4j功能模块，描述其职责，模块通过精密的协作，共同支撑起复杂 Agent 的构建与运行。

逻辑架构解构为以下四个核心域：图编排、执行与状态、基础设施扩展、集成外部能力生态、开发支持

1. 核心编排层：图的蓝图与引擎

StateGraph (状态图)：这是开发者构建 Agent 的核心抽象。它代表了整个工作流的“蓝图”，开发者在这里定义有哪些节点（Node）以及它们之间的流转规则（Edge）。

CompiledGraph (编译图)：当 StateGraph 被构建完成后，经过 compile() 方法转化而来。编译图重整了状态图的数据结构，支持高效的图执行；编译图包含了流执行逻辑、状态机引擎和调度策略的“可运行实例”。

2. 执行与状态层：原子动作与数据流转

3. 基础设施扩展层：持久化、异步与可观测

4. agent，agent有两部分，core内agent包是lg4j提供;  core外的agent框架，spring ai alibaba移植，提供完整的agent框架，多agent的支持

5. 外部能力生态层：AI 核心能力

这一层是LangGraph4j 与 AI 生态对接。

• Spring AI
  ：作为底层的能力供给层，Spring AI 提供了 Agent 所需的原子能力，包括 LLM model（大语言模型）、RAG（检索增强生成）、prompt（提示词工程）、memory（长期记忆）、mcp&tool&skills（工具调用与技能扩展）等。
• LangGraph4j
  也集成了langchain4j

5. 开发工具

Studio (可视化开发工具)：lg4j的Studio模块提供了一套完整的可视化调试和开发界面，让开发者能够直观地看到图的执行路径和状态流转，极大地降低了复杂 Agent 的开发门槛。

多agent

单 Agent 会遇到三类瓶颈：

• 工具过载
  工具太多，模型很难稳定选对；
• 上下文负担
  对话和中间结果越来越长，推理质量下降；
• 角色互斥
  同一个 Agent 既要“创意”，又要“审核”，提示词容易互相干扰。

多 Agent 通过“分而治之”解决这些问题：每个 Agent 只负责一个明确角色、一套工具和一个状态契约，再由协作模式把它们串成完整工作流。

子agent

子agent需要解决两个问题，

1. 结果传递，上一个agent执行的结果怎样传递下一节点，下一节点怎样接收上一节点的结果
2. 子agent过滤返回结果，多agent重点之一，减少多agent执行链的上下文，消息过滤的第二种

这是两个方面，agent调用前的提示词处理，调用后的结果过滤

上图 上述两个问题的解决方案

outputKey/instruction outputKey是agent返回的标识，结合instruction生成提示词

includeContents 是否包括主图/主agent消息内容，这是调用模型输入相关，消息过滤的第一种

returnReasoningContents 是否返回推理内容开关，若false，只返回最后的message，若true，返回推理过程的消息

上篇实现和分析了第一个问题，本文分析第二和第三个问题的实现，首先介绍一下saa的方案

spring ai alibaba消息过滤

本节分析一下saa的消息过滤设计

ReactAgent.AgentToSubCompiledGraphNodeAdapter saa子图/子agent的action类

该类支持includeContents/returnReasoningContents两个开关

上图 AgentToSubCompiledGraphNodeAdapter支持returnReasoningContents的关键方法

saa的图执行是使用reactor，上图利用flux的buffer方法，识别流的最后一个事件，逻辑是，buffer设置每次获取2个事件，当接收到一个事件，那个事件就是最后一个，后面的是state的操作，这里就不分析

lg4j设计和实现

本节解释lg4j子图/子agent消息过滤设计和实现，lg4j图执行使用async-generator组件，没有reactor对应的机制，async-generator是迭代器，迭代器使用hasNext判断是否最后一个事件

InternalIterator

上图 InternalIterator的hasNext方法，InternalIterator是async-generator的迭代器实现，看到红框hasNext判断

SubCompiledGraphNodeActionEx.getGraphResponseGenerator

上图  SubCompiledGraphNodeActionEx的getGraphResponseGenerator方法，

SubCompiledGraphNodeActionEx是子图/子agent的节点action，替代lg4j原有的SubCompiledGraphNodeAction，支持消息过滤

getGraphResponseGenerator返回匿名AsyncGenerator.Cancellable，包装子图的执行结果subGraphResult，拦截InternalIterator的next调用，hasNext判断是否为最后一个事件，进行处理。可以看到，代码逻辑比较简单，关键点与saa一致，识别最后一个事件

示例

本节示例沿用上篇的“竞品分析报告智能体”，做了简化，只保留researcher和draft两个agent

业务场景：分析一款新产品，例如“iphone duo”，“华为阔直板pura x view”，评估其产品力，生成专业的报告

整个流水线包含以下步骤：

1. 研究agent：思考如何查资料 -> 动作（调用搜索工具） -> 观测（获取原始数据）
2. 起草agent：思考如何写文章 -> 动作（撰写初稿） -> 观测（生成草稿）。

agent使用SequentialAgent，研究 -> 起草

首先介绍智能体运行图

上图 agent图，reasearch-writer，reasearch多轮调用bing-search工具，生成多个ToolResponseMessage和AssistantMessage，本文使用input “华为阔直板pura x view”，生成pura x view的产品竞争力报告作为测试

首先看一下agent的设置

上图，returnReasoningContents设为false，includeContents/returnReasoningContents在BaseAgent均为boolean类型，不设置就是false，也就是includeContents/returnReasoningContents 均设为false

下面看一下示例的运行：

>上图 图执行进入全局的START，初始状态input和review_feedback是用户输入

>上图 SequentialAgent的默认节点，该节点TransparentNode，没有实际的逻辑

>上图 进入子agent researcher, ReactAgent子图的START节点

>上图 子agent researcher的推理节点，返回工具执行消息，bing_search，规划了多个查询url，后续多轮的推理-action来回

>上图 action节点，返回搜索的url，下面多轮搜索返回产品数据

>上图 经过多轮的查询，researcher节点结束，生成outpoutKey research_data的消息

>上图 researcher节点进入end，此时，多个工具消息，搜索结果消息

>上图 researcher子图action结束，messages只剩下最后一个message，其他的state不影响，如，research_data

>上图 进入另一个agent, writer agent，看到messages空，因为includeContents设置为false，researcher的消息没有带入，下图，includeContents为false，去掉主图/主agent带入的messages

includeContents实现比较简单

总结

至此，子图/子agent过滤消息的action介绍完

SubCompiledGraphNodeActionEx需要更改StateGraph，增加addNode方法 

上图 StateGraph新增addNode，接收includeContents/returnReasoningContents参数，创建子编译图的节点node

SubCompiledGraphNodeEx，其内构建SubCompiledGraphNodeActionEx

下图 构建图的addNode调用