第 2 章：第一个 ReactAgent，先做一个会回答的小助手

第 1 章我们知道了大地图：Spring Boot 接请求，Agent 组织任务，Graph 控制流程。这一章把镜头拉近，只做一个最小 ReactAgent。它暂时不用工具、不记忆、不分工，只负责收到一句话，给出一句回答。

本章边界

这一章只解决“最小 Agent 怎么装起来、怎么调用、它和 ChatModel 有什么区别”。工具调用、记忆、结构化输出、生产异常会在后面逐步加上去。

1. 生活类比：先装台灯，再装修整栋房子

学 Agent 最容易犯的错，是第一天就把工具、RAG、记忆、多智能体全塞进去。像刚学电路就要装修整栋楼，最后可能连开关为什么亮都没看清。

所以我们先装一盏台灯：

台灯零件	框架概念	你要记住的作用
电源	`ChatModel`	提供模型能力
灯罩和开关	`ReactAgent`	把模型包装成可调用助手
使用说明	`instruction(...)`	规定助手的角色和回答风格
按一下开关	`call(...)`	发起一次 Agent 调用

先让灯亮起来，再谈调光、定时、远程控制。

2. 最小可运行示例

下面这个示例假设 Spring Boot 已经装配好了一个 ChatModel。

java

@Configuration
class LessonAgentConfig {

    @Bean
    ReactAgent studyAgent(ChatModel chatModel) {
        return ReactAgent.builder()
                .name("study_agent")
                .model(chatModel)
                .instruction("""
                        你是一个 Java 学习助教。
                        回答要短，先给结论，再给一个小例子。
                        """)
                .build();
    }
}

调用时像调用一个 Service：

java

AssistantMessage answer = studyAgent.call("用一句话解释什么是 ReactAgent");
System.out.println(answer.getText());

这段代码看起来很短，但它已经有了 Agent 的基本骨架：

name(...) 给它一个身份，方便日志、Studio 或多 Agent 场景识别。
model(...) 接入底层模型能力。
instruction(...) 设定它的角色边界。
build() 把这些配置组装成一个可执行 Agent。
call(...) 触发一次完整执行。

3. 不看源码也要懂的调用链

最小 ReactAgent 的运行过程，可以理解成“把一句话包装成一次可执行任务”：

重点不是背方法名，而是理解这个分层：

层次	解决的问题
`ChatModel`	我能不能和模型说话
`ChatClient`	我怎么组织一次模型请求
`ReactAgent`	我怎么把模型请求变成一个可扩展的 Agent 流程
`Graph`	这个流程以后怎么插入工具、记忆、分支和中断

现在这个 Agent 虽然很小，但它已经站在 Graph 的轨道上。后面加工具、记忆、多 Agent，不是推倒重来，而是在这条轨道上加车厢。

4. 工程里怎么判断该不该用 ReactAgent

不是所有模型调用都要上 Agent。一个很朴素的判断表：

场景	建议
只做一次简单问答或文本改写	直接用 `ChatClient` 就够
需要统一角色、提示词、日志和后续扩展	用 `ReactAgent`
需要工具调用、记忆、循环推理	用 `ReactAgent` 更合适
需要多步骤流程、人工审核、复杂状态	继续往 Graph / FlowAgent 扩展

把 Agent 当成“未来可能长出手脚的助手”。如果你确定它永远只是一次纯文本问答，就别过度设计；如果你知道它迟早要查工具、记上下文、做审批，那早点放进 Agent 结构里会更顺。

5. 新手容易误解什么

误解一：ChatModel 就是 Agent。

ChatModel 是发动机，不是汽车。它能产生动力，但不负责方向盘、仪表盘、路线和安全带。ReactAgent 才把模型能力组织成一个可调用的助手。

误解二：instruction(...) 只是注释。

它不是写给程序员看的注释，而是写给模型看的行为规则。它会影响模型怎样回答、用什么语气、遵守什么边界。

误解三：call(...) 就是直接调模型。

表面像普通方法调用，实际会进入 Agent 的执行流程。今天这条流程很短，后面挂上工具和记忆后，它会变成一个会流转状态的任务。

6. 本章小结

本章的核心句：

text

ReactAgent = ChatModel + 行为规则 + 可扩展执行流程

你可以先把它想成一个干净的小助手：现在只会回答，下一章我们给它装“手”，让它能调用工具。

7. 练习题

把 instruction(...) 改成“只用一句话回答”，观察输出是否变短。
写一个 codingAgent，要求它只回答 Java 代码相关问题，非代码问题礼貌拒绝。
用自己的话解释：为什么一个最小 ReactAgent 也可以看成未来复杂 Agent 的地基？

课后源码索引：想验证实现时再打开

你想验证的结论	源码锚点
官方最小 Agent 示例	`examples/documentation/src/main/java/com/alibaba/cloud/ai/examples/documentation/framework/tutorials/AgentsExample.java`，类 `AgentsExample`，方法 `basicModelConfiguration()`、`advancedModelConfiguration()`、`basicSystemPrompt()`、`instructionUsage()`
ReactAgent 的构建和调用入口	`spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/ReactAgent.java`，类 `ReactAgent`，方法 `builder()`、`call(...)`、`doMessageInvoke(...)`
Builder 支持哪些配置项	`spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/Builder.java`，类 `Builder`，方法 `name(...)`、`model(...)`、`instruction(...)`、`systemPrompt(...)`、`build()`
Builder 如何创建模型节点和工具节点	`spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/DefaultBuilder.java`，类 `DefaultBuilder`，方法 `build()`
用户输入如何进入 Graph state	`spring-ai-alibaba-agent-framework/src/main/java/com/alibaba/cloud/ai/graph/agent/Agent.java`，类 `Agent`，方法 `buildMessageInput(...)`、`doInvoke(...)`

第 2 章：第一个 ReactAgent，先做一个会回答的小助手 ​

本章边界 ​

1. 生活类比：先装台灯，再装修整栋房子 ​

2. 最小可运行示例 ​

3. 不看源码也要懂的调用链 ​

4. 工程里怎么判断该不该用 ReactAgent ​

5. 新手容易误解什么 ​

6. 本章小结 ​

7. 练习题 ​