企业官网建设流程全解析

1. Java 开发者做 AI Agent，为什么总卡在“跑不起来”

你可能已经看过不少 AI Agent 的科普，知道它由大模型、工具调用、记忆、检索几块拼起来。但真到动手，Java 开发者面对的第一个问题往往不是原理，而是：Spring AI 的依赖怎么配、MCP 工具怎么暴露、RAG 的向量库怎么接、本地启动后接口怎么验证。这些环节任何一个报错，都会让“8 周从入门到产品”变成“8 周还在配环境”。

这篇内容聚焦一个可运行的最小骨架：用 Spring AI 作为底座，把 MCP 工具调用和 RAG 检索增强串起来，产出一个能本地启动、能用 curl 验证的 Agent 骨架。它适合有 Java/Spring Boot 基础、想按周推进 AI Agent 学习路径的开发者。你不需要先成为算法工程师，只要会写 Controller、会看 application.yml，就能跟着把骨架跑通。

我试过把 MCP 和 RAG 拆成两个独立 Demo 再合并，结果发现工具注册和检索上下文经常互相干扰。后来改成先固定一个 ChatClient 配置，再分别挂载工具 Advisor 和检索 Advisor，问题就清晰了。下面按“前置准备 → 可复制配置 → 启动验证 → 排障”的顺序展开，每一步都给出可粘贴的代码和命令。

2. TaoToken 前置：模型接入与 Key 管理

Agent 骨架要跑起来，第一步是让 Spring AI 能调到大模型。这里用 TaoToken 作为模型接入层，它提供 OpenAI 兼容的 API 形态，Spring AI 的 openai starter 可以直接对接，不需要改代码结构。

你需要先拿到一个 API Key。访问控制台创建密钥：

• 控制台入口：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=console
• API Keys 管理：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys

创建后把 Key 存到环境变量，不要写进代码仓库。Linux/macOS 下：

export TAOTOKEN_API_KEY="sk-你的密钥"

Windows PowerShell：

$env:TAOTOKEN_API_KEY="sk-你的密钥"

TaoToken 的 API 基地址是https://taotoken.net/api，注意这个地址不带查询参数，直接作为 base-url 使用。模型对话调试可以在模型对话页先验证 Key 是否可用：

• 模型对话：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model-chat

如果你后续要做长期编码或 Agent 任务，可以了解 Coding Plan：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan

接入文档在：

• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc

注意：Key 只放在环境变量或配置中心，不要提交到 Git。Spring AI 读取的是spring.ai.openai.api-key，我们用占位符引用环境变量即可。

3. 可复制配置：pom、application.yml 与 MCP 骨架

3.1 pom.xml 依赖

Spring AI 的版本要和 Spring Boot 对齐。下面用 Spring Boot 3.x 加 Spring AI 1.0.x 的组合，这是目前稳定可用的搭配。MCP 部分用 Spring AI 的 MCP Server starter。

<parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>3.3.5</version> <relativePath/> </parent> <properties> <java.version>21</java.version> <spring-ai.version>1.0.0</spring-ai.version> </properties> <dependencies> <!-- Web + 接口验证 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Spring AI OpenAI 兼容模型接入 --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-model-openai</artifactId> </dependency> <!-- 向量库：先用内存版跑通 RAG，后续换 Milvus --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-vector-store-simple</artifactId> </dependency> <!-- MCP Server（WebMVC 传输） --> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-starter-mcp-server-webmvc</artifactId> </dependency> <!-- 可观测性，方便看调用链 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-actuator</artifactId> </dependency> </dependencies> <dependencyManagement> <dependencies> <dependency> <groupId>org.springframework.ai</groupId> <artifactId>spring-ai-bom</artifactId> <version>${spring-ai.version}</version> <type>pom</type> <scope>import</scope> </dependency> </dependencies> </dependencyManagement>

如果拉不到依赖，检查 Maven 仓库是否配置了 Spring 的里程碑仓库。Spring AI 1.0.0 GA 之后已进入中央仓库，一般不需要额外配置。

3.2 application.yml

这里把模型、向量库、MCP 三块配置放在一起。注意 base-url 指向 TaoToken 的 API 地址。

server: port: 8080 spring: application: name: java-agent-skeleton ai: openai: api-key: ${TAOTOKEN_API_KEY} base-url: https://taotoken.net/api chat: options: model: gpt-4o-mini temperature: 0.3 embedding: options: model: text-embedding-3-small vectorstore: simple: initialize-schema: true mcp: server: name: infra-agent-mcp version: 1.0.0 protocol: STREAMABLE type: SYNC management: endpoints: web: exposure: include: health,info,metrics tracing: sampling: probability: 1.0

模型名按你账号下可用的模型填写。embedding 模型用于 RAG 向量化，如果暂时不做 RAG，可以先注释掉 embedding 相关配置，但向量库 starter 会要求一个 EmbeddingModel，所以建议保留。

3.3 ChatClient 与 Advisor 链配置

把 ChatClient 的构建集中到一个配置类，工具 Advisor 和检索 Advisor 都挂在这里。这样后续加功能只改一处。

@Configuration public class AgentConfig { @Bean public ChatClient chatClient(ChatClient.Builder builder, VectorStore vectorStore, InfraTools infraTools) { return builder .defaultSystem("你是 Infra 运维助手，回答要具体、可执行。") .defaultTools(infraTools) .defaultAdvisors( new QuestionAnswerAdvisor(vectorStore) ) .build(); } }

QuestionAnswerAdvisor是 Spring AI 自带的 RAG Advisor，它会自动把用户问题拿去向量库检索，再把检索结果拼进上下文。defaultTools注册的是带@Tool注解的方法。

3.4 MCP 工具骨架

MCP 工具用注解声明，一个方法就是一个工具。下面给两个示例：查磁盘、查服务状态。

@Component public class InfraTools { @Tool(description = "查询指定路径的磁盘使用率") public String checkDiskUsage( @ToolParam(description = "路径，如 /data") String path) { return "路径 " + path + " 磁盘使用率 78%"; } @Tool(description = "查询指定服务的运行状态") public String checkServiceStatus( @ToolParam(description = "服务名，如 mysql") String service) { return service + " 状态: running, 连接数 150/200"; } }

如果要把这些工具通过 MCP 协议暴露给外部客户端，再加一个 MCP 配置类，把工具注册为 MCP 工具。Spring AI 的 MCP Server starter 会自动扫描@Tool方法并暴露，具体取决于版本，建议先用下面的 Controller 验证工具调用，再验证 MCP 端点。

3.5 RAG 文档入库

启动时把几段运维文档灌进向量库，这样检索 Advisor 才有内容可查。

@Component public class DocIngestor implements CommandLineRunner { private final VectorStore vectorStore; public DocIngestor(VectorStore vectorStore) { this.vectorStore = vectorStore; } @Override public void run(String... args) { List<Document> docs = List.of( new Document("MySQL 连接数过高时，先查 Sleep 连接，再考虑临时调高 max_connections。"), new Document("Nginx 502 通常检查后端服务是否存活，以及 upstream 配置是否正确。"), new Document("Redis 内存溢出时，检查 maxmemory 策略和大 key 分布。") ); vectorStore.add(docs); } }

4. 验证请求：本地启动与接口测试

4.1 启动应用

./mvnw spring-boot:run

看到Started AgentApplication且端口 8080 监听，说明启动成功。如果报api-key为空，检查环境变量是否在当前终端生效。

4.2 验证模型对话

写一个最简单的 Controller：

@RestController public class ChatController { private final ChatClient chatClient; public ChatController(ChatClient chatClient) { this.chatClient = chatClient; } @GetMapping("/chat") public String chat(@RequestParam String q) { return chatClient.prompt().user(q).call().content(); } }

用 curl 验证：

curl "http://localhost:8080/chat?q=你好，介绍一下你自己"

返回一段模型生成的文本，说明模型接入通了。

4.3 验证工具调用

提问一个会触发工具的问题：

curl "http://localhost:8080/chat?q=帮我查一下 /data 的磁盘使用率"

如果返回内容里包含“78%”，说明模型正确选择了checkDiskUsage工具并使用了返回值。这一步是 Agent 骨架的关键验证点。

4.4 验证 RAG 检索

提问一个只有文档里才有答案的问题：

curl "http://localhost:8080/chat?q=MySQL 连接数过高先查什么"

期望返回里提到“Sleep 连接”。如果模型回答的是通用知识而不是文档内容，说明检索 Advisor 没生效，检查向量库是否入库成功。

4.5 验证 MCP 端点

MCP Server 启动后一般会暴露一个 HTTP 端点，具体路径看 starter 版本。可以用：

curl http://localhost:8080/actuator/health

确认应用健康。MCP 的详细端点验证建议参考接入文档里的 MCP 章节，不同版本路径有差异。

5. 本篇常见错排查

5.1 启动报 api-key 为空

现象：OpenAI API key must be set。原因是环境变量没生效或 yaml 占位符写错。检查echo $TAOTOKEN_API_KEY是否有值，yaml 里必须是${TAOTOKEN_API_KEY}，不要加默认值空字符串。

5.2 工具不被调用

现象：模型直接回答，没有触发@Tool方法。常见原因有三个：一是defaultTools没注册；二是工具方法所在类没加@Component；三是模型本身不支持工具调用。换一个支持 function calling 的模型再试。

5.3 RAG 检索不到内容

现象：提问文档里的问题，模型答非所问。先确认DocIngestor是否执行，可以在vectorStore.add后打日志。再确认QuestionAnswerAdvisor是否挂到了 ChatClient 上。如果向量库是 simple 版，重启后数据会丢，需要每次启动重新入库。

5.4 MCP 端点 404

现象：访问 MCP 路径返回 404。不同 starter 版本的端点路径不同，有的在/mcp，有的在/sse。先看启动日志里打印的 MCP 端点，再按日志路径访问。如果用的是 STREAMABLE 协议，注意请求方法可能是 POST。

5.5 依赖冲突

现象：NoSuchMethodError或ClassNotFoundException。多半是 Spring AI 版本和 Spring Boot 版本不匹配。Spring AI 1.0.x 对应 Spring Boot 3.3+，不要混用 3.2。用mvn dependency:tree看是否有旧版本被传递进来。

5.6 向量维度不一致

现象：入库时报维度错误。原因是 embedding 模型换了但向量库 schema 没重建。simple 向量库重启即清空，Milvus 需要删 collection 重建。换 embedding 模型时务必同步重建索引。

6. 按周推进与下一步

这个骨架对应 8 周路径的前两周：第一周把模型接入和工具调用跑通，第二周把 RAG 检索接上。后面几周可以在这个骨架上逐步加东西：第三周加多工具编排，第四周加多 Agent 协作，第五周把工具通过 MCP 暴露给外部客户端，第六周加可观测性和安全护栏，第七八周做产品化整合。

如果你在验证模型对话时遇到问题，可以回到模型对话页单独测 Key：

• 模型对话：https://taotoken.net/model-chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=model-chat

如果卡在接入配置或 MCP 端点，先看接入文档：

• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=doc

需要新建或轮换 Key，去 API Keys 页：

• API Keys：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=api-keys

长期做编码类 Agent 任务，可以看 Coding Plan：

• Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=coding-plan

骨架跑通之后，建议你做的第一件事是把DocIngestor里的三行文档换成你自己领域的真实文档，然后提一个只有你的文档才能回答的问题。这一步能同时验证 RAG 和工具调用两条链路，比任何理论都直观。