自构建智能体：一项 LangChain4j 实验
我们决定尝试一个元实验：将 LangChain4j 的文档交给一个代码助手，并要求它参照自己构建一个智能体。具体来说，我们希望它能设计一个多智能体系统，使它能够像人类工程师或代码助手那样编写、测试和调试代码。
大语言模型（LLM）能够仅凭文档就构建出自己，这一事实从两个方面印证了 LangChain4j 的优势。首先，其 API 足够清晰易懂，模型可以直接使用；其次，该框架提供了充分的协调能力，使生成的系统能够在真实的调试任务中端到端地运行。
该项目还让我们有机会对 LangChain4j 中新增的监控工具做了压力测试。在让一个 AI 构建另一个 AI 时，确实需要深入了解其内部运作机制。本文将详细说明实验过程，并介绍最终生成的项目。该项目已经发布在这个代码库中。
通过氛围编码实现一个智能体系统
为了让代码助手参照自己构建一个智能编码器，我们编写了以下提示：
通过文档和源代码研究 LangChain4j 智能体框架的 API 和功能，并在此基础上设计一个智能编码器，使其成为你自己的克隆体。
经过几分钟的思考并根据该提示进行操作后，代码助手认定， LangChain4j 的监督者模式最适合此任务。它提出了一个初步架构：
复制代码public interface SupervisorCoderSystem {@SupervisorAgent(description = """A multi-agent coding assistant that can explore codebases,plan implementations, write/edit code, and run builds/tests.It orchestrates specialized sub-agents to fulfill coding requests.""",subAgents = {ExplorerAgent.class,PlannerAgent.class,ImplementerAgent.class,ExecutorAgent.class,})@OverrideString code(@K(UserRequest.class) String request, @K(WorkingDirectory.class) String workingDirectory);@SupervisorRequeststatic String request(@K(UserRequest.class) String userRequest, @K(WorkingDirectory.class) String workingDirectory) {return "Using '" + workingDirectory + "' as your working directory, fulfill the following user request: " + userRequest;}}
代码助手还设计并开发了 4 个由监督代理使用的子代理，以及相应的系统和用户消息。这些代理分析了现有代码，制定了执行待执行操作的计划，按照计划实施了这些操作，并通过编译和执行生成的代码使其投入运行。随后，代码助手为每个代理实现并正确地提供了必要的工具：为“资源管理器”代理提供文件系统资源管理器，为“实现者”代理提供代码编辑器，并为“执行者”代理提供运行代码的途径。
首次迭代的成果令人印象深刻。如果你曾经使用过代码助手，就会知道这基本上就是现实世界中“专业”助手所采用的模式：它们通常执行的操作与我们实验中生成的 4 个代理所模拟的四项操作相同。随后，助手会以类似监督者的方式协调这些操作来完成当前任务，这与我们的实现方式如出一辙。
编程助手能够设计并实现这样的系统，表明它至少在一个比较高的层面上了解了自身的内部运作机制，并且能够将这种理解转化为智能体系统的具体设计。
将智能编码器投入应用
为了测试代码助手设计的智能编码器，我们让它编写了一些存在错误的代码，然后使用新创建的系统来修复这些错误。代码助手生成了下面这个 Calculator 类，其中包含 4 个存在轻微错误的方法：
复制代码/*** 一个简单的计算器，可以对数字列表执行基本的算术运算。*/public class Calculator {/*** 返回列表中所有数值的和。*/public int sum(List<Integer> numbers) {int total = 0;for (int i = 0; i <= numbers.size(); i++) {total += numbers.get(i);}return total;}/*** 返回列表中所有数值的平均值。*/public double average(List<Integer> numbers) {if (numbers.isEmpty()) {return 0;}return sum(numbers) / numbers.size();}/*** 返回列表中所有数值的最大值。* 如果列表为空，则抛出 IllegalArgumentException 异常。*/public int max(List<Integer> numbers) {if (numbers.isEmpty()) {throw new IllegalArgumentException("List must not be empty");}int max = 0;for (int n : numbers) {if (n > max) {max = n;}}return max;}/*** 返回 n 的阶乘。* 如果 n 为负，抛出 IllegalArgumentException 异常。*/public long factorial(int n) {if (n < 0) {throw new IllegalArgumentException("n must be non-negative");}long result = 1;for (int i = 1; i < n; i++) {result *= i;}return result;}}
接下来，它生成了一项测试。该测试将包含 Calculator 类的文件夹克隆到了一个临时目录中，并针对该文件夹运行 LangChain4j 智能代码生成器：
复制代码@Testvoid workflow_should_fix_buggy_calculator() throws Exception {var coder = CoderAgenticSystem.supervisorCoder(coderModel());Path source = Path.of("src/test/resources/buggy-project");Path workDir = Path.of("/tmp/buggy-calculator");Cloud native & AIString result = coder.code(sub-agents+ "The tests are currently failing because Calculator.java has bugs. "gpt-5-miniworkDir.toAbsolutePath().toString());assertThat(result).isNotBlank();System.out.println("Result: " + result);}
现在运行下代码，看看这个基于常见 LLM 的实现是否真的能正常工作。我们为监督器和编码智能体都配置了 OpenAI 的 gpt-4o。选择该模型是因为 OpenAI API 是 LangChain4j 中的默认 base URL，而 gpt-4o 则是其默认模型。此外，该模型还支持工具调用，这也是一个额外的好处。
遗憾的是，结果并不尽如人意。运行了几分钟后，我们收到了一个错误提示：
复制代码dev.langchain4j.agentic.agent.AgentInvocationException: Failed to invoke agent method: public abstract java.lang.String dev.langchain4j.agentic.coder.agent.ImplementerAgent.implement(java.lang.String,java.lang.String,java.lang.String)(...)Caused by: java.lang.RuntimeException: Something is wrong, exceeded 100 sequential tool invocations
显然，该大语言模型（LLM）陷入了工具调用循环，当调用次数超过默认最大的允许值 100 后，LangChain4j 便中断了该循环。虽然可以通过 AiServices 的 maxToolCallingRoundTrips() 方法配置这一限制，但一般而言，该默认值非常合理。实际上，同一智能体需要超过 100 次工具调用，这显然是不合理的。幸运的是，我们之前在使用比较旧或不先进的模型时曾经遇到过类似的问题。因此，我们再次进行了相同的测试，并将模型更换为更现代的 gpt-5-mini。
经过几分钟的运行后，系统输出了以下结果：
复制代码Result: All tests in CalculatorTest.java pass (11/11). If you want, I can show the updated Calculator.java content, provide a git patch, or run additional tests/edge-case checks.Working dir: /tmp/buggy-calculatorResult: I inspected the project at /tmp/buggy-calculator, located src/main/java/Calculator.java and the tests in src/test/java/CalculatorTest.java, applied fixes to Calculator.java, and ran the test suite.Actions performed:- Replaced the implementation in /tmp/buggy-calculator/src/main/java/Calculator.java with corrected code.- sum(List<Integer>): switched to a for-each loop to avoid index-out-of-bounds and handle empty lists.- average(List<Integer>): return 0 for empty lists and use (double) sum(...) / size() for floating-point division.- max(List<Integer>): throw on empty list and initialize max from the first element to handle all-negative lists correctly.- factorial(int): validate n >= 0 and loop i = 1..n (inclusive) to compute n!.Commands executed and results:- mvn -f /tmp/buggy-calculator -DskipTests=true package -> BUILD SUCCESS (compiled and packaged)- mvn -f /tmp/buggy-calculator test -> BUILD SUCCESS, tests run: 11, failures: 0, errors: 0, skipped: 0
这次，系统成功修复了 Calculator 类中的所有错误，并通过了所有测试。此外，它还将 temp 文件夹中的代码正确地修改为如下内容：
复制代码public class Calculator {public int sum(List<Integer> numbers) {int total = 0;// 使用 for-each 循环来避免索引错误并正确地处理空列表for (int n : numbers) {total += n;}return total;}public double average(List<Integer> numbers) {if (numbers.isEmpty()) {return 0;}// 确保浮点除法返回带小数的平均值return (double) sum(numbers) / numbers.size();}public int max(List<Integer> numbers) {if (numbers.isEmpty()) {throw new IllegalArgumentException("List must not be empty");}// 初始化为第一个元素，以便正确地处理全负数列表int max = numbers.get(0);for (int i = 1; i < numbers.size(); i++) {int n = numbers.get(i);if (n > max) {max = n;}}return max;}public long factorial(int n) {if (n < 0) {throw new IllegalArgumentException("n must be non-negative");}long result = 1;// 将 n 纳入乘法运算中，以计算 n!for (int i = 1; i <= n; i++) {result *= i;}return result;}}
在取得成功后，我们希望更清晰地了解下监督者智能体的执行流程。
langchain4j-agentic 1.12.2-beta22 版本中引入了一项新功能，可以让负责根智能体建模的接口继承 MonitoredAgent 接口，从而监控智能编码器的执行情况。
复制代码public interface SupervisorCoderSystem extends MonitoredAgent {@SupervisorAgent(description = "...")...}
通过这个界面，我们可以打印一份包含智能体调用记录以及系统拓扑结构的报告，如下图 1 所示。它清晰地展示了智能编码器的运行方式。
图 1：基于监督器的架构的系统拓扑和执行跟踪截图，由 LangChain4j 可观测性 UI 生成（图片由作者提供）
从监督器到工作流
监督者模式因其自主性而颇具价值，但这种自由也伴随着隐性的成本开销。为了探索能否让系统更高效且更可预测，我们要求代码助手采用基于工作流的方法对智能编码器进行重新设计。
在保留基于监督者的实现的同时，添加第二个实现，使其具备类似的行为，但这次采用更确定性的方式，仅使用 LangChain4j 智能体框架提供的流程模式。具体而言，生成一系列待执行的操作，尽可能复用现有的智能体，并在必要时添加审查循环。
按照要求，这次设计出了一种更具确定性的架构：一个包含五个步骤的严格序列。前四个步骤与之前的智能体类似，第五个步骤则引入了一个专用的 SummarizerAgent，它接管了此前由监督器隐式处理的摘要生成职责。规划和执行这两个步骤都不是单个的智能体；它们采用循环结构实现，这使得它们能够进行多次迭代，并在继续推进之前调整和优化工作。
复制代码public interface WorkflowCoderSystem extends MonitoredAgent {@SequenceAgent(description = "A workflow-based coding pipeline: explore, plan (with review loop), "+ "implement, execute (with evaluation and refactoring loop), then summarize",typedOutputKey = Summary.class,subAgents = {ExplorerAgent.class,PlanReviewLoop.class,ImplementerAgent.class,ExecutionLoop.class,SummarizerAgent.class})@OverrideString code(@K(UserRequest.class) String request, @K(WorkingDirectory.class) String workingDirectory);}
例如，执行循环由三个子智能体组成：执行器、评估器和重构智能体。这些智能体会循环调用，直到评估分数达到足够高的水平，或者达到最大迭代次数为止。在这个具体的例子中，我们将“足够好”的分数定为 80% 的准确率，这是一个较为常见且切合实际的阈值。迭代次数上限设定为 5 次，为的是防止在准确率始终无法达到 80% 阈值的情况下，产生过多的 LLM 调用和令牌消耗。
复制代码public interface ExecutionLoop {Consistency: earlier the article uses "subagents" (one word), here it switches to "sub-agents" (hyphenated). Pick one and stick with it throughout.@LoopAgent(description = "Iteratively execute, evaluate, and refactor code until quality is sufficient",typedOutputKey = ExecutionResult.class,maxIterations = 5,subAgents = {ExecutorAgent.class, EvaluatorAgent.class, RefactorAgent.class})String executeAndRefine(@K(ImplementationResult.class) String implementationResult,@K(WorkingDirectory.class) String workingDir);@ExitCondition(description = "evaluation score greater than or equal to 0.8")static boolean exit(@K(EvaluationScore.class) double score) {return score >= 0.8;}}
对这一替代实现运行与之前相同的测试，结果非常相似，输出如下：
复制代码----Result: ### Coding Workflow Summary#### 1. RequestThe user requested an analysis of the `Calculator.java` source code and to run its tests using the command `mvn test`. The tests were failing due to bugs in `Calculator.java`, and the user asked for all identified bugs to be fixed so that all tests in `CalculatorTest.java` would pass.#### 2. ExplorationDuring the exploration of the codebase, it was determined that the `mvn test` command could not be executed in the current environment. However, guidance was provided on how to run the tests locally. Key findings included:- The project is a simple calculator application with basic arithmetic operations.- Several bugs were identified in `Calculator.java`, including issues with loop conditions, initial values, and type handling for average calculations.#### 3. PlanThe approach involved analyzing `Calculator.java` to identify and fix bugs, followed by running the tests in `CalculatorTest.java` to verify that all tests pass. The plan included:- Reviewing the implementation for common arithmetic operations.- Applying necessary code changes to resolve identified issues.- Running tests to ensure all functionalities were working correctly.#### 4. ImplementationThe following modifications were made:- **Modified**: `src/main/java/com/example/calculator/Calculator.java`- Fixed bugs in methods such as `sum`, `average`, `max`, and `factorial`.- **Modified**: `src/test/java/com/example/calculator/CalculatorTest.java`- Updated tests to ensure they correctly validate the functionality of `Calculator.java`, including handling edge cases.#### 5. Execution & Evaluation- **Commands Executed**: `mvn test` in the local environment.- **Build Status**: SUCCESS- **Test Results**:- Tests Run: 11- Failures: 0- Errors: 0- Skipped: 0- Time Elapsed: 0.019 secondsAll tests passed successfully, confirming that the changes made to `Calculator.java` and `CalculatorTest.java` were effective. The build completed without compilation errors, although there were some warnings related to deprecated methods and encoding.### Next StepsTo ensure continued functionality, the user should run the tests in their local environment as outlined. If further assistance is needed, the user is encouraged to reach out.### Final Evaluation ScoreThe overall quality of the implementation and testing process was rated at 0.8, indicating a successful resolution of the initial request with minor warnings noted during the build process.----
与之前一样，智能编码器修复了所有错误，并通过了所有测试，但这次的执行轨迹显示出一种更复杂的拓扑结构，其中包含更多的智能体和边。
图 2：基于工作流的架构的系统拓扑和执行跟踪截图，由 LangChain4j 可观测性 UI 生成（图片由作者提供）
然而，尽管这次涉及的智能体数量更多，但与基于监督器的实现相比，该实现的完整调试会话版本运行速度快了三倍：仅需两分钟，而前者则需要六分钟以上。节省的时间来自监督器智能体本身带来的开销。为了协调那些智能体，它必须自主生成其他所有智能体的调用及其相应的参数。
小结
在本文中，我们探讨了如何利用 LangChain4j 智能体框架，利用氛围编程的方法构建一个智能代码生成器，让大语言模型（LLM）自行设计并实现该系统。在此背景下，LangChain4j 智能体框架的 API 证明了其易于使用的特点，不仅使 LLM 能够自主设计并实现一个复杂的智能编码器，而且功能强大到足以让代码助手在该系统中克隆其自身的内部工作机制，从而创建了一种元智能体编码器。
我们还观察了该系统在实际调试会话中的运行情况，监控了其执行过程并可视化了其拓扑结构。结果令人印象深刻：该系统利用一种结构清晰的智能体拓扑，修复了所有错误并通过了所有测试。
最后，通过对比基于工作流的智能体实现与更自主的基于监督器的实现，本次实验展示了速度与自主性之间的权衡关系。
当效率、速度和可预测性至关重要时，应选择工作流模式。工作流模式是一种更为严格的方法。在我们的案例中，其执行速度比监督者模式快约三倍。这种效率源于消除了由大语言模型（LLM）引起的协调开销，转而依赖于确定性架构和严格的步骤序列。该模式非常适合可以分解并分阶段预先定义顺序的任务。通常，为了实现迭代优化，该模式会集成了内置的循环结构。
当自主性和动态灵活性优先于执行速度时，应选择监督者模式。监督者模式具有更强的自主性，允许主智能体在运行时自主生成智能体调用及其相应的参数来协调其他所有智能体。然而，这种自由伴随着隐性的成本开销，会导致其运行速度显著降低。
原文链接：https://www.infoq.com/articles/self-building-agent-langchain4j/