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

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

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-03-30T18:45:55.000Z
- 最近活动: 2026-03-30T18:50:41.405Z
- 热度: 157.9
- 关键词: Java, AI Agent, Workflow, LLM, Spring AI, DSL, Observability
- 页面链接: https://www.zingnex.cn/forum/thread/agent-workflow-java-dslagent
- Canonical: https://www.zingnex.cn/forum/thread/agent-workflow-java-dslagent
- Markdown 来源: ingested_event

---

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

在AI Agent开发领域，Python长期占据主导地位，但企业级应用对类型安全、性能监控和可维护性的需求，让Java生态重新获得关注。agent-workflow项目正是这一趋势下的重要探索——它提供了一套基于Java 21的Agent工作流基础库，让开发者能够以声明式方式构建复杂的AI驱动流程，同时保持对每一步执行的完整可见性。

## 为什么需要Agent工作流框架

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

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

## 核心架构与设计哲学

### 流式DSL定义工作流

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

```java
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许可，在保持开源可见性的同时为企业应用提供了法律保障。

构建和测试非常简单：

```bash
./mvnw clean compile
./mvnw test
```

## 应用场景与价值

这个框架特别适合以下场景：

**代码审查自动化**：如示例所示，可以构建理解代码语义、评估变更质量的智能审查流程。

**文档处理管道**：从原始文档提取、结构化、摘要到质量校验的端到端流程。

**客户服务工作流**：结合知识检索、情感分析、回复生成和多轮确认的复杂对话管理。

**数据分析任务**：将数据获取、清洗、分析、可视化、报告生成串联成可维护的流程。

## 项目意义与展望

agent-workflow代表了AI工程化的一种成熟思路：不再把LLM调用视为简单的函数调用，而是将其嵌入到结构化的业务流程中，同时保持对整个流程的可见性和控制力。这种"编排式AI"的范式，可能是企业AI应用从实验走向生产的关键一步。

对于Java生态的开发者而言，这个项目提供了与Python阵营LangChain、LlamaIndex等工具对标的解决方案，同时保留了Java在类型安全、性能监控、企业集成方面的传统优势。

项目文档位于lab.pollack.ai/projects/agent-workflow，感兴趣的开发者可以深入了解其设计理念和最佳实践。