agent-workflow：用Java DSL构建可观测、可评估的Agent工作流

一个基于Java 21的Agent工作流基础库，通过流式DSL定义步骤化流程，集成质量门控和完整追踪，让AI Agent的决策过程透明可分析。

当前大多数LLM应用采用简单的"调用-响应"模式，但在实际业务场景中，AI往往需要执行多步骤任务：获取数据、分析内容、做出决策、调用工具、验证结果。这些步骤之间的依赖关系、错误处理、重试逻辑很快就会让代码变得难以维护。更重要的是，当AI做出错误决策时，开发者往往难以定位问题根源——是提示词设计不当？还是某个中间步骤产生了偏差？

agent-workflow的核心设计理念是"构建能工作的Agent，并能衡量它们为什么能工作"。它将工作流抽象为可组合的步骤图，每个步骤都有明确的输入输出契约，每一步转换都被记录用于行为分析。

agent-workflow采用流畅的Java DSL来定义工作流，代码可读性接近自然语言描述：

Workflow.define("pr-review")
    .step(fetchDiff)
    .then(analyzeDiff)
    .gate(new JudgeGate(jury, 0.8))
    .onPass(postComment)
    .onFail(revise)
    .end()
    .run(event);

这种链式调用风格让业务逻辑一目了然：先获取代码差异，然后分析差异，通过质量门控评估，根据评估结果决定是发布评论还是要求修改。

框架将步骤分为三个层次，适应不同复杂度需求：

确定性步骤——普通的Java函数，用于API调用、数据解析、格式化等无需AI参与的操作。这类步骤性能确定、成本可控、结果可预测。

单轮LLM调用——通过ChatClientStep包装Spring AI的ChatClient，适合需要语言理解但无需复杂推理的场景。

完整Agent会话——ClaudeStep可以运行包含数十次工具调用、持续数分钟的多轮Agent循环，对工作流而言这仍然只是一个步骤，返回类型化的最终结果。这种抽象让复杂认知任务可以被无缝嵌入更大的业务流程。

区别于简单的条件分支，agent-workflow引入了JudgeGate作为质量评估节点。门控接收一个"评审团"(jury)配置和置信度阈值(如0.8)，对工作流中间产物进行评分。如果评分不达标，流程可以自动路由到修正分支，并将评审反馈传递给重试逻辑。

这种设计让AI系统具备了自我修正能力——不是简单的错误捕获，而是基于质量标准的主动优化。

agent-workflow的一大创新是将工作流定义编译为图中间表示(IR)，实现定义与执行的分离。这意味着：

• 可移植运行时：同一套工作流代码可以在LocalStepRunner（进程内零开销）、CheckpointingStepRunner（基于JDBC的崩溃恢复）或TemporalStepRunner（分布式持久执行）之间切换，只需更换一个@Bean配置。

• 完整追踪：每一步转换都被记录，支持行为分析和性能调优。开发者可以回答关键问题：哪些步骤应该从LLM驱动改为确定性实现？Agent缺少哪些知识？是否需要更好的实时引导？

• 可序列化检查：编译后的图可以被序列化、遍历、可视化，便于调试和监控。

框架提供了丰富的流程控制原语：step、then、branch、repeatUntil、repeatUntilOutput、parallel、decision、gate、supervisor、onError、terminate。这些原语覆盖了从简单顺序执行到复杂并行协调的各种场景。

错误处理方面，框架支持细粒度的异常捕获和恢复策略，让关键业务流程具备韧性。

agent-workflow基于Java 21构建，充分利用了虚拟线程等现代特性。它与Spring AI深度集成，可以无缝接入各种LLM提供商。项目采用Business Source License 1.1许可，在保持开源可见性的同时为企业应用提供了法律保障。

构建和测试非常简单：

./mvnw clean compile
./mvnw test