agent框架

      《agent和集成 I Agent》篇分析了lg4j提供给用户的agent开发范式，agent图的构建组件，但没有提供完整的agent框架。本文介绍的agent框架是spring ai alibaba移植过来，适配到lg4j，实现agent，多agent

本文认为 Agent  = （推理框架 + 工具调用 + 上下文）× 用户逻辑

其中，推理框架的大模型调用， 工具调用 + 上下文是spring ai实现， 推理框架运行由lg4j的图框架实现

Agent 在用户逻辑层面，把业务规则、流程片段、工具策略、状态契约和人工介入点沉淀为可复用的智能体能力。相比直接使用图结构，Agent 抽象让开发者不必从零编排每个节点和边，而是以“任务目标、协作模式、约束规则”的方式描述业务逻辑。图负责提供可恢复、可观测、可分支的执行底座，Agent 负责把这些底层能力包装成业务友好的复用单元。

单 Agent 会遇到三类瓶颈：

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

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

上图 agent框架，分4块，下面详细模块解析

• Agent基类

定义了智能体的基础契约，包括流式执行图，stream；同步执行图方法，invoker；agent图相关的，toGraph，getAndCompileGraph

• 单 Agent (BaseAgent)：  
• ReActAgent：实现了通用的“推理-行动”范式，多agent框架以ReActAgent搭建
• ReAct/Reflection/Plan-and-Execute：封装了具体的推理框架，是实际执行 LLM 调用、工具选择和反思的引擎
• 用户agent（User Agent）用户实现自己的agent，自己的业务逻辑，直接使用推理框架
• 多 Agent (MultiAgent)：
• 继承了 Agent 的能力，并包含多个子 Agent，支持并行、顺序、路由等多种协作模式。
• 提供 SequentialAgent、ParallelAgent、LoopAgent 以及 LlmRoutingAgent（基于 LLM 动态决定下一步走向的 Agent）等多种拓扑实现。

• Agent编排，包括单agent和多agent

MultiAgent与 FlowAgentBuilder：

• FlowAgentBuilder 负责将多个子 Agent 组装成一个复合的 MultiAgent。
• 支持常用的多 Agent 拓扑结构（如并行执行 ParallelResultAggregator、路由分发 RoutingNode 等），这些节点被复用为 MultiAgent 的底层执行单元。

图构建：

框架的核心机制，负责将Agent转化StateGraph，单agent部分在《图 I状态图，推理框架》分析过，这里看看多agent

• 图构建器 (FlowGraphBuilder)：
  构建器，根据类型获取图building策略实现构建图
• 图构建策略: 负责映射多agent的图
• FlowGraphBuildingStrategy 接口定义了标准的 buildGraph 方法
• 采用策略模式，LoopGraphBuildingStrategy 等具体类负责根据不同的 Agent 类型（如 LoopAgent）生成对应的状态图。

多agent

单 Agent 会遇到三类瓶颈：

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

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

多agent关键是角色定义和agent间数据传递

角色定义是业务问题，类似面向对象开发，定义agent的角色和职责，在技术层面，多agent可以是flow，agent之间连接和协作，本节介绍几种常用的协作模式

单个agent推理框架以图结构支持，多agent的拓扑也是以图支持，复用图结构和执行，本节分析多agent图映射

状态图

ParallelAgent

并行agent，多个Agent同时处理相同的输入，结果被收集合并输出

流程：

1. 输入同时发送给所有Agent
2. 所有Agent并行处理
3. 结果被合并成单一输出

下面分析ParallelAgent的图构建，分agent的构建和图的构建两部分

上图是并行agent构建1/2，创建子agent，构建

• 增加聚合节点，多个并行节点结果合并为一个结果
• 并行start节点

上图是并行agent的图构建2/2

• 并行的子agent作为节点，子agent的内部graph作为子图，子agent的节点向前连接并行start节点，向后连接聚合节点
• 5/6聚合节点连接END节点

上图 构建代码生成的图，子图内部均是ReAct，3个子agent并行执行，结果聚合到聚合节点

下面其他agent简单展示一下图形

LlmRoutingAgent

调用大模型选择子agent

SequentialAgent

两个agent序列执行，前面agent的结果成为后面的参数

LoopAgent

上图 复合的多agent示例，整体是loop，内嵌的blog agent是SequentialAgent，loop设置退出策略，一般是迭代次数限制，特定的输出条件

总结：本节简单介绍了几种常用的flow agent，flow agent也可以嵌套，组合成更复杂的agent

子agent

多agent执行环境，子agent需要解决两个问题，

1. 结果传递，上一个agent执行的结果怎样传递下一节点，下一节点怎样接收上一节点的结果
2. 子agent选择哪些输出到全局状态，多agent重点之一，减少agent的上下文

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

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

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

returnReasoningContents 是否返回推理内容开关，若false，只返回outputKey的messages

示例

本节示例详细介绍agent框架开发使用，组合多个ReactAgent实现复杂的场景：

“竞品分析报告智能体”

该实例是从《spring ai Alibaba原理源码分析》的agent示例移植过来

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

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

1. 研究agent：思考如何查资料 -> 动作（调用搜索工具） -> 观测（获取原始数据）
2. 起草agent：思考如何写文章 -> 动作（撰写初稿） -> 观测（生成草稿）。
3. 主编agent：思考草稿质量 -> 动作（审阅打分） -> 观测（输出反馈）。如果打分不及格，工作流会触发循环，将反馈交还给起草专家重新思考。

agent整体使用SequentialAgent，研究 -> (起草 <-> 反思)，其中，起草 <-> 反思使用LoopAgent

构建ReactAgent

下面以产品研究agent rearchAgent为例，介绍agent构建

上图 agent定义角色，负责特定的职能，工具使用魔搭社区的bing-search

构建agent团队

本节看一下multi agent组合，构建agent团队

上图 多agent组合3个角色agent，成为团队，共同完成工作

agent整体使用SequentialAgent，研究 -> (起草 <-> 反思)，其中，起草 <-> 反思使用LoopAgent，上图设置loop退出，迭代次数超过3次，或者审核意见是APPROVE

其他核心组件

本节简单介绍其他核心组件

上图 序列化组件，序列化用于前后端传输，存储。本框架的序列化组件增加instruction消息的序列化器

上图 channel组件

上图  channel的二次处理，增加agent设置的outputKey channel

设置任务

本节介绍agent任务设置

上图，每个角色agent安排具体的工作，系统提示词为agent定义人格，用户提示词每个agent具体任务，agent框架提供instruction，用户提示词的参数化模板，根据用户输入input，构建用户提示词

应用

上面几节介绍了智能体的部件构建和设置，智能体就绪，

上图 模拟client输入目标产品

上图 client端返回结果，流式运行，过程的中间结果源源不断返回，打印到控制台，最终结果是writer agent的输出，outputKey是draft_article

运行示例

本节运行示例，首先介绍智能体运行图

上图运行的示例图，简化了loop，writer-reviewer只运行一次，运行中可以图的节点对照

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

>上图 进入第一个SequentialAgent，该节点TransparentNode，没有实际的逻辑

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

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

>上图 action节点

上图 经过多轮的查询，researcher节点结束，生成outpoutKey research_data的消息，下面进入writer

>上图 进入另一个SequentialAgent节点，writer agent和reviewer agent序列

>上图 writer的推理节点

>上图 writer agent没有需要调用的工具，回到推理节点，生成了报告草稿

>上图 writer子图结束，下面开始reviewer

>上图 进入评审agent，评审的推理节点

>上图 评审的instruction消息

>上图 评审给了反馈，判定结果REJECTED，本版本去掉loop，若有loop，评审意见带回到writer，writer重写

   >最后，生成报告

总结：

整个agent的运行按照图的节点走，每步到哪个agent子图(subgraph)，哪个agent子图节点，但有两个问题：

1.  lg4j的hook是node级别的，本框架做了扩展，支持设置nodeId，但node反复执行出现无效hook执行，解决办法可以增加在状态中增加标记，或者，参看spring ai alibaba做法，支持agent级别节点，在图的前面增加agent hook节点，但这样增加节点，图结构与用户的预期不一样
2. 过滤消息没有实现，导致前面步骤消息传到后面，这个主要考虑，该功能需要修改lg4j源码，本agent组件设计是拔插式，兼容lg4j

next

图执行源码分析篇分析实现了returnReasoningContents开关的子图action，并给出示例