【Langchain4j-Java AI开发】09-Agent智能体工作流

LangChain4j 智能体工作流

概述

智能体工作流（Agentic Workflows）允许你编排多个 AI 智能体协同完成复杂任务。LangChain4j 提供了强大的智能体系统，支持顺序、并行、循环、条件等多种工作流模式。

什么是智能体（Agent）？

智能体是一个具有特定职责的 AI 单元，它可以：

• 接收输入
• 执行任务（调用 LLM、工具、检索文档等）
• 产生输出
• 与其他智能体协作

基础智能体

创建单个智能体

代码示例 （参考：agentic-tutorial/src/main/java/_1_basic_agent/_1a_Basic_Agent_Example.java）

package dev.langchain4j.example;

import dev.langchain4j.agentic.AgenticServices;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;

import static dev.langchain4j.model.openai.OpenAiChatModelName.GPT_4_O_MINI;

public class BasicAgentExample {

    // 1. 定义智能体接口
    interface CvGenerator {
        @SystemMessage("你是一位专业的简历撰写专家，能够将个人经历整理成专业的简历格式。")
        @UserMessage("将以下个人经历转换为专业简历：\n\n{{lifeStory}}")
        String generateCv(@V("lifeStory") String userInfo);
    }

    public static void main(String[] args) {

        // 2. 创建 ChatModel
        ChatLanguageModel chatModel = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName(GPT_4_O_MINI)
                .build();

        // 3. 使用 AgenticServices 创建智能体
        CvGenerator cvGenerator = AgenticServices
                .agentBuilder(CvGenerator.class)
                .chatModel(chatModel)
                .outputKey("masterCv")  // 定义输出键名
                .build();

        // 4. 调用智能体
        String lifeStory = """
                我叫张伟，毕业于清华大学计算机系。
                在腾讯工作了5年，负责后端开发。
                精通 Java、Spring Boot、微服务架构。
                """;

        String cv = cvGenerator.generateCv(lifeStory);

        System.out.println("=== 生成的简历 ===");
        System.out.println(cv);
    }
}

智能体 vs AI Service

特性	AI Service	Agent (AgenticServices)
用途	单一任务	多步骤工作流
状态管理	无	支持状态传递
组合能力	弱	强（可组合多个智能体）
适用场景	简单对话	复杂业务流程

顺序工作流（Sequential Workflow）

多个智能体按顺序执行，前一个智能体的输出作为后一个的输入。

代码示例 （参考：agentic-tutorial/src/main/java/_2_sequential_workflow/_2a_Sequential_Agent_Example.java）

package dev.langchain4j.example;

import dev.langchain4j.agentic.AgenticServices;
import dev.langchain4j.agentic.UntypedAgent;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;

import java.util.Map;

import static dev.langchain4j.model.openai.OpenAiChatModelName.GPT_4_O_MINI;

public class SequentialWorkflowExample {

    // 智能体1：生成简历
    interface CvGenerator {
        @UserMessage("将以下经历转换为简历：{{lifeStory}}")
        String generateCv(@V("lifeStory") String userInfo);
    }

    // 智能体2：定制简历
    interface CvTailor {
        @UserMessage({
                "根据以下要求定制简历：",
                "",
                "原简历：",
                "{{masterCv}}",
                "",
                "定制要求：",
                "{{instructions}}"
        })
        String tailorCv(@V("masterCv") String cv, @V("instructions") String requirements);
    }

    public static void main(String[] args) {

        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName(GPT_4_O_MINI)
                .build();

        // 1. 创建第一个智能体
        CvGenerator cvGenerator = AgenticServices
                .agentBuilder(CvGenerator.class)
                .chatModel(model)
                .outputKey("masterCv")  // 输出键为 masterCv
                .build();

        // 2. 创建第二个智能体
        CvTailor cvTailor = AgenticServices
                .agentBuilder(CvTailor.class)
                .chatModel(model)
                .outputKey("tailoredCv")  // 输出键为 tailoredCv
                .build();

        // 3. 组合成顺序工作流
        UntypedAgent workflow = AgenticServices
                .sequenceBuilder()
                .subAgents(cvGenerator, cvTailor)  // 按顺序执行
                .outputKey("tailoredCv")  // 最终输出
                .build();

        // 4. 准备输入数据
        Map<String, Object> arguments = Map.of(
                "lifeStory", "我是 Java 开发工程师，5年经验...",
                "instructions", "突出微服务和云原生技术经验"
        );

        // 5. 执行工作流
        String result = (String) workflow.invoke(arguments);

        System.out.println("=== 定制后的简历 ===");
        System.out.println(result);
    }
}

工作流程：

输入 → CvGenerator → masterCv → CvTailor → tailoredCv → 输出

循环工作流（Loop Workflow）

重复执行智能体，直到满足退出条件。

代码示例 （参考：agentic-tutorial/src/main/java/_3_loop_workflow/_3a_Loop_Agent_Example.java）

package dev.langchain4j.example;

import dev.langchain4j.agentic.AgenticServices;
import dev.langchain4j.agentic.UntypedAgent;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;

import java.util.Map;

import static dev.langchain4j.model.openai.OpenAiChatModelName.GPT_4_O_MINI;

public class LoopWorkflowExample {

    // 简历评审智能体
    interface CvReviewer {
        @UserMessage("评审以下简历并给出0-1的分数：\n\n{{cv}}")
        CvReview reviewCv(@V("cv") String cv);
    }

    // 简历改进智能体
    interface CvImprover {
        @UserMessage({
                "根据评审意见改进简历：",
                "",
                "原简历：{{cv}}",
                "评审意见：{{review}}"
        })
        String improveCv(@V("cv") String cv, @V("review") CvReview review);
    }

    static class CvReview {
        public double score;
        public String feedback;

        // constructor, getters, setters...
    }

    public static void main(String[] args) {

        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName(GPT_4_O_MINI)
                .build();

        // 创建智能体
        CvReviewer reviewer = AgenticServices
                .agentBuilder(CvReviewer.class)
                .chatModel(model)
                .outputKey("cvReview")
                .build();

        CvImprover improver = AgenticServices
                .agentBuilder(CvImprover.class)
                .chatModel(model)
                .outputKey("cv")
                .build();

        // 创建循环工作流
        UntypedAgent loopWorkflow = AgenticServices
                .loopBuilder()
                .subAgents(reviewer, improver)  // 循环执行这两个智能体
                .outputKey("cv")
                .exitCondition(agenticScope -> {
                    // 读取当前状态
                    CvReview review = (CvReview) agenticScope.readState("cvReview");
                    // 如果分数 > 0.8，退出循环
                    return review != null && review.score > 0.8;
                })
                .maxIterations(5)  // 最多循环5次
                .build();

        // 执行工作流
        Map<String, Object> arguments = Map.of(
                "cv", "初始简历内容..."
        );

        String finalCv = (String) loopWorkflow.invoke(arguments);

        System.out.println("=== 优化后的简历 ===");
        System.out.println(finalCv);
    }
}

工作流程：

输入简历 → CvReviewer → 评分
              ↓
        分数 > 0.8?
         否 ↓     是 → 输出
        CvImprover → 改进后的简历 → 循环

并行工作流（Parallel Workflow）

多个智能体同时执行，然后聚合结果。

代码示例 （参考：agentic-tutorial/src/main/java/_4_parallel_workflow/_4_Parallel_Workflow_Example.java）

package dev.langchain4j.example;

import dev.langchain4j.agentic.AgenticServices;
import dev.langchain4j.agentic.UntypedAgent;
import dev.langchain4j.model.chat.ChatLanguageModel;
import dev.langchain4j.model.openai.OpenAiChatModel;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.V;

import java.util.Map;
import java.util.concurrent.Executors;

import static dev.langchain4j.model.openai.OpenAiChatModelName.GPT_4_O_MINI;

public class ParallelWorkflowExample {

    // HR 评审智能体
    interface HrReviewer {
        @UserMessage("从 HR 角度评审简历：{{cv}}")
        CvReview reviewFromHrPerspective(@V("cv") String cv);
    }

    // 技术经理评审智能体
    interface TechManagerReviewer {
        @UserMessage("从技术经理角度评审简历：{{cv}}")
        CvReview reviewFromTechPerspective(@V("cv") String cv);
    }

    // 团队成员评审智能体
    interface TeamMemberReviewer {
        @UserMessage("从团队协作角度评审简历：{{cv}}")
        CvReview reviewFromTeamPerspective(@V("cv") String cv);
    }

    static class CvReview {
        public double score;
        public String feedback;
    }

    public static void main(String[] args) {

        ChatLanguageModel model = OpenAiChatModel.builder()
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName(GPT_4_O_MINI)
                .build();

        // 创建三个评审智能体
        HrReviewer hrReviewer = AgenticServices
                .agentBuilder(HrReviewer.class)
                .chatModel(model)
                .outputKey("hrReview")
                .build();

        TechManagerReviewer techReviewer = AgenticServices
                .agentBuilder(TechManagerReviewer.class)
                .chatModel(model)
                .outputKey("techReview")
                .build();

        TeamMemberReviewer teamReviewer = AgenticServices
                .agentBuilder(TeamMemberReviewer.class)
                .chatModel(model)
                .outputKey("teamReview")
                .build();

        // 创建并行工作流
        var executor = Executors.newFixedThreadPool(3);

        UntypedAgent parallelWorkflow = AgenticServices
                .parallelBuilder()
                .subAgents(hrReviewer, techReviewer, teamReviewer)  // 并行执行
                .executor(executor)  // 可选：自定义线程池
                .outputKey("aggregatedReview")
                .output(agenticScope -> {
                    // 聚合所有评审结果
                    CvReview hrReview = (CvReview) agenticScope.readState("hrReview");
                    CvReview techReview = (CvReview) agenticScope.readState("techReview");
                    CvReview teamReview = (CvReview) agenticScope.readState("teamReview");

                    // 计算平均分
                    double avgScore = (hrReview.score + techReview.score + teamReview.score) / 3.0;

                    return String.format("综合评分: %.2f\nHR: %s\n技术: %s\n团队: %s",
                            avgScore,
                            hrReview.feedback,
                            techReview.feedback,
                            teamReview.feedback);
                })
                .build();

        // 执行工作流
        Map<String, Object> arguments = Map.of("cv", "候选人简历...");

        String result = (String) parallelWorkflow.invoke(arguments);

        System.out.println("=== 综合评审结果 ===");
        System.out.println(result);

        executor.shutdown();
    }
}

工作流程：

               输入简历
                  ↓
    ┌─────────────┼─────────────┐
    ↓             ↓             ↓
HrReviewer  TechReviewer  TeamReviewer
    ↓             ↓             ↓
    └─────────────┼─────────────┘
                  ↓
            聚合结果 → 输出

条件工作流（Conditional Workflow）

根据条件选择不同的执行路径。

package dev.langchain4j.example;

import dev.langchain4j.agentic.AgenticServices;
import dev.langchain4j.agentic.UntypedAgent;

import java.util.Map;

public class ConditionalWorkflowExample {

    interface ScoreEvaluator {
        CvReview evaluate(String cv);
    }

    interface BasicImprover {
        String improveBasic(String cv);
    }

    interface AdvancedImprover {
        String improveAdvanced(String cv);
    }

    public static void main(String[] args) {

        // 创建智能体...
        ScoreEvaluator evaluator = ...;
        BasicImprover basicImprover = ...;
        AdvancedImprover advancedImprover = ...;

        // 条件工作流
        UntypedAgent workflow = AgenticServices
                .conditionalBuilder()
                .firstAgent(evaluator)
                .condition(agenticScope -> {
                    CvReview review = (CvReview) agenticScope.readState("review");
                    return review.score < 0.5;  // 分数低于0.5走高级改进
                })
                .ifTrue(advancedImprover)      // 条件为真执行
                .ifFalse(basicImprover)        // 条件为假执行
                .outputKey("improvedCv")
                .build();

        String result = (String) workflow.invoke(Map.of("cv", "..."));
    }
}

工作流程：

输入 → ScoreEvaluator → 评分
                          ↓
                    分数 < 0.5?
                  是 ↓     ↓ 否
        AdvancedImprover  BasicImprover
                  ↓         ↓
                  └────┬────┘
                       ↓
                     输出

组合工作流（Composed Workflow）

将多个工作流组合成更复杂的流程。

// 创建子工作流1：简历生成和改进
UntypedAgent cvGenerationWorkflow = AgenticServices
        .sequenceBuilder()
        .subAgents(cvGenerator, cvImprover)
        .outputKey("improvedCv")
        .build();

// 创建子工作流2：多角度评审
UntypedAgent reviewWorkflow = AgenticServices
        .parallelBuilder()
        .subAgents(hrReviewer, techReviewer, teamReviewer)
        .outputKey("reviews")
        .build();

// 组合成完整工作流
UntypedAgent completeWorkflow = AgenticServices
        .sequenceBuilder()
        .subAgents(
                cvGenerationWorkflow,  // 先生成和改进
                reviewWorkflow         // 再多角度评审
        )
        .outputKey("finalResult")
        .build();

智能体状态管理

读取和写入状态

UntypedAgent agent = AgenticServices
        .agentBuilder(MyAgent.class)
        .chatModel(model)
        .outputKey("result")
        .stateAccessor(agenticScope -> {
            // 读取状态
            String previousResult = (String) agenticScope.readState("previousKey");

            // 写入状态
            agenticScope.writeState("newKey", "newValue");

            // 获取所有状态
            Map<String, Object> allState = agenticScope.allState();

            return previousResult;
        })
        .build();

工具集成

智能体可以使用工具：

static class DatabaseTools {
    @Tool("查询用户信息")
    User findUser(String userId) {
        return database.findById(userId);
    }
}

interface DataAnalyst {
    @UserMessage("分析用户 {{userId}} 的数据")
    String analyzeUser(@V("userId") String userId);
}

DataAnalyst analyst = AgenticServices
        .agentBuilder(DataAnalyst.class)
        .chatModel(model)
        .tools(new DatabaseTools())  // 添加工具
        .outputKey("analysis")
        .build();

RAG 集成

智能体可以访问文档：

interface DocumentAnalyst {
    @UserMessage("根据文档回答：{{question}}")
    String answer(@V("question") String question);
}

DocumentAnalyst analyst = AgenticServices
        .agentBuilder(DocumentAnalyst.class)
        .chatModel(model)
        .contentRetriever(contentRetriever)  // 添加 RAG
        .outputKey("answer")
        .build();

人机协作（Human in the Loop）

在工作流中添加人工审核点：

代码示例 （参考：agentic-tutorial/src/main/java/_9_human_in_the_loop/_9a_HumanInTheLoop_Simple_Validator.java）

import java.util.Scanner;

public class HumanInTheLoopExample {

    interface Proposer {
        String proposeDecision(String context);
    }

    public static void main(String[] args) {

        Proposer proposer = AgenticServices
                .agentBuilder(Proposer.class)
                .chatModel(model)
                .outputKey("proposal")
                .build();

        // 创建验证器（人工审核）
        UntypedAgent validator = AgenticServices
                .agentBuilder(HumanValidator.class)
                .outputKey("approved")
                .build();

        // 组合工作流
        UntypedAgent workflow = AgenticServices
                .sequenceBuilder()
                .subAgents(proposer, validator)
                .outputKey("finalDecision")
                .build();

        String result = (String) workflow.invoke(Map.of("context", "..."));
    }

    static class HumanValidator implements UntypedAgent {

        @Override
        public Object invoke(Map<String, Object> state) {
            String proposal = (String) state.get("proposal");

            System.out.println("AI 建议: " + proposal);
            System.out.print("是否批准？(y/n): ");

            Scanner scanner = new Scanner(System.in);
            String input = scanner.nextLine();

            if ("y".equalsIgnoreCase(input)) {
                return proposal;
            } else {
                return "提案被拒绝，请重新考虑";
            }
        }
    }
}

最佳实践

1. 合理划分智能体职责

// ✅ 好：职责清晰
interface ContentGenerator { }  // 生成内容
interface ContentReviewer { }   // 审核内容
interface ContentPublisher { }  // 发布内容

// ❌ 不好：职责混杂
interface ContentManager { }    // 做所有事情

2. 设置合理的退出条件

// ✅ 好：有明确退出条件和最大迭代次数
.exitCondition(scope -> /* 明确条件 */)
.maxIterations(10)

// ❌ 不好：可能无限循环
.exitCondition(scope -> false)
.maxIterations(1000)

3. 处理失败情况

try {
    String result = (String) workflow.invoke(arguments);
} catch (AgentExecutionException e) {
    log.error("工作流执行失败", e);
    // 执行降级逻辑
}

4. 监控和日志

UntypedAgent workflow = AgenticServices
        .sequenceBuilder()
        .subAgents(agent1, agent2)
        .onStateChange((key, value) -> {
            log.info("状态更新: {} = {}", key, value);
        })
        .build();

实战示例：招聘流程自动化

public class RecruitmentWorkflow {

    public static void main(String[] args) {

        ChatLanguageModel model = /* ... */;

        // 1. 简历筛选智能体
        interface ResumeScreener {
            List<String> screenResumes(List<String> resumes);
        }

        // 2. 技术评估智能体
        interface TechnicalAssessor {
            TechAssessment assessCandidate(String resume);
        }

        // 3. 面试安排智能体
        interface InterviewScheduler {
            String scheduleInterview(TechAssessment assessment);
        }

        // 创建智能体
        ResumeScreener screener = /* ... */;
        TechnicalAssessor assessor = /* ... */;
        InterviewScheduler scheduler = /* ... */;

        // 组合工作流
        UntypedAgent recruitmentWorkflow = AgenticServices
                .sequenceBuilder()
                .subAgents(screener, assessor, scheduler)
                .outputKey("interviewSchedule")
                .build();

        // 执行
        Map<String, Object> input = Map.of(
                "resumes", List.of("resume1", "resume2", "resume3")
        );

        String schedule = (String) recruitmentWorkflow.invoke(input);
        System.out.println("面试安排: " + schedule);
    }
}

下一步学习

• 10-框架集成 - 在生产环境部署智能体
• 07-RAG检索增强生成 - 为智能体添加知识库
• 06-工具与函数调用 - 扩展智能体能力

参考资料

• 基础智能体: agentic-tutorial/src/main/java/_1_basic_agent/
• 顺序工作流: agentic-tutorial/src/main/java/_2_sequential_workflow/
• 循环工作流: agentic-tutorial/src/main/java/_3_loop_workflow/
• 并行工作流: agentic-tutorial/src/main/java/_4_parallel_workflow/
• 官方文档: https://docs.langchain4j.dev/tutorials/agentic-rai