从 0 到 1 开发一个 Agent：我的 Spring AI 实战流程

以后再开发一个 Agent，我不想一上来就写 Prompt，而是先把业务流程设计清楚。

一个 Agent 的完整开发链路，可以沉淀成：

明确任务
  ↓
定义输入 / 输出
  ↓
判断单 Agent 还是 Workflow
  ↓
选择 Model
  ↓
设计 Prompt
  ↓
挂载 Memory / Tools
  ↓
Structured Output
  ↓
Advisor / ReAct
  ↓
注册到 Router
  ↓
监控 + 兜底

1. 先定义 Agent 到底负责什么

比如开发一个：

岗位推荐 Agent

职责应该尽量单一：

输入：
用户求职需求

能力：
查询岗位 + 推荐岗位

输出：
推荐结果

不要一个 Agent 同时负责：

岗位推荐
简历优化
身份采集
岗位爬取
任务管理

Agent 越小，Prompt 越简单，也越容易测试。

2. 判断要不要 LangGraph4j

如果流程只是：

用户
↓
LLM
↓
Tool
↓
回答

直接：

Spring AI + ChatClient + ReAct

就够了。

如果任务是：

步骤 A
↓
条件判断
↓
步骤 B
↓
步骤 C

例如：

分类
↓
采集
↓
清洗
↓
发布

再使用：

LangGraph4j

所以可以记：

对话用 ChatClient，多步骤业务流程用 LangGraph4j。

3. 再设计 Agent 的三样东西

一个 Agent 最核心就三个东西：

Prompt
告诉模型要干什么

Tool
告诉模型能干什么

Output
规定模型最后返回什么

例如岗位推荐：

Prompt
→ 你是岗位推荐助手

Tool
→ searchJob()

Output
→ JobRecommendResult

结构化结果优先使用：

.entity(JobRecommendResult.class)

不要让业务代码解析模型生成的一大段自然语言。

4. 再决定需不需要 Memory

一次性任务：

文本摘要
意图分类
信息提取

通常：

不需要 ChatMemory

多轮业务：

用户：推荐武汉 Java 岗位
用户：25K 以上
用户：第二个详细说说

需要：

ChatMemory
+
Conversation ID

原则很简单：

后一句依赖前一句，就需要 Memory。

5. Agent 需要外部能力就加 Tool

模型不知道实时数据，也不能直接操作业务系统。

所以：

查岗位
→ Tool

查数据库
→ Tool

浏览网页
→ Tool

创建任务
→ Tool

本地能力：

@Tool

远程能力：

MCP

最终统一成：

ToolCallback

Agent 不应该关心工具运行在本机还是远程。

6. 用 LlmCaller 隐藏底层复杂度

业务 Agent 最好不要自己处理：

选 DeepSeek 还是 GLM
TEXT 还是 VISION
ChatMemory
Advisor
ReAct
MCP
ToolContext

统一下沉：

Agent
 ↓
LlmCaller
 ↓
ChatClient
 ↓
Advisor / Tools / Memory
 ↓
ChatModel
 ↓
LLM

于是 Agent 只需要关注：

llmCaller.call(user, prompt);

这一步很重要：

Agent 写业务，LlmCaller 管 AI 基础设施。

7. 最后接入 Router

Agent 写完还不能自己运行，需要告诉系统：

什么时候应该找我？

比如：

@Component
public class JobRecommendAgent implements BizAgent {
}

声明：

支持意图：
JOB_RECOMMEND

之后：

用户消息
↓
Message Router
↓
Intent Classifier
↓
Agent Registry
↓
JobRecommendAgent

这样新增 Agent 不需要修改 Router。

我的 Agent 开发模板

以后开发新 Agent，可以直接检查这 8 件事：

职责：这个 Agent 到底只负责什么？
输入输出：输入是什么，最终要返回什么？
流程：单次调用还是 LangGraph4j Workflow？
模型：TEXT、VISION，还是特殊模型？
上下文：需不需要 ChatMemory？
能力：需要哪些 @Tool / MCP？
输出：能不能用 Structured Output？
工程化：Router、Advisor、日志、Token、Fallback 是否完成？

最后沉淀

一套比较完整的 Agent 架构最终是：

User
 ↓
Router
 ↓
Agent
 ↓
LlmCaller
 ↓
ChatClient
 ├─ Memory
 ├─ Advisor
 ├─ ReAct
 ├─ Local Tool
 └─ MCP Tool
 ↓
LLM
 ↓
Structured Output
 ↓
Business

如果是复杂流程：

LangGraph4j
   ↓
Node A
   ↓
Node B → Agent / LLM
   ↓
Conditional Edge
   ↓
Node C

所以以后从 0 到 1 开发 Agent，最值得记住的一句话是：

先设计业务流程，再设计 Agent；先确定哪些事情必须由 AI 做，再把剩下的事情交给确定性的 Java 代码。