Spring AI 把 RAG、MCP 和多 Agent 编排拼到一个工程里后真正的排障入口通常不是 SupervisorAgent 的源码而是 application.yml 里的模型通道。TaoToken官网https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content在这里扮演的是统一模型请求入口SupervisorAgent 分解任务、ResearchAgent 调 MCP 工具、KnowledgeAgent 走 RAG 检索、ReviewAgent 审校回溯每一轮 Agent Loop 都要过模型通道。原文 8.4/8.5 节直接写${OPENAI_API_KEY}开始跑现在改成先创建 Key再把spring.ai.openai.api-key填成这把 Keyspring.ai.openai.base-url设为https://taotoken.net/api。这样 RAG 管道、MCP 配置、Supervisor 编排源码都不用动只替换模型接入层。原问题与场景SupervisorAgent 调度 ResearchAgent、KnowledgeAgent、ReviewAgent 时的模型通道在一个完整的 Spring AI 多 Agent 工程里通常会有下面这些角色SupervisorAgent接收用户任务输出 JSON 执行计划决定先 RAG 检索、再外部搜索、再生成回答、最后审校。ResearchAgent负责外部信息检索可能通过 MCP 工具访问 GitHub、文件系统或 Web 搜索。KnowledgeAgent负责知识库问答底层是 RAG 管道包含分块、嵌入、向量检索、重排序。ReviewAgent对最终答案做质量审校必要时返回NEEDS_REVISION让主流程重新生成。RagPipeline文档上传、分块、嵌入、pgvector 存储、混合检索。McpAgentService通过mcp-servers.json加载 MCP Server把工具动态注入 ChatClient。这条链路的问题不在于单个组件能不能跑而在于“长会话 多工具 任务编排”会把模型请求放大。Supervisor 第一轮要理解任务第二轮要生成计划第三轮要汇总结果ResearchAgent 调完 MCP 工具后要把工具结果塞回上下文KnowledgeAgent 检索后要拼上下文ReviewAgent 还要再请求一次模型做审校。只要其中任何一轮的 Key、base-url、模型 ID 不一致就会出现 401、404、超时或空回复。更麻烦的是MCP 工具本身不负责模型鉴权。MCP Server 只负责暴露工具ChatModel 才负责模型请求。如果application.yml里还留着默认 OpenAI 地址或者环境变量OPENAI_API_KEY没有换成 TaoToken Key那么 Supervisor 的计划生成能失败ReviewAgent 的审校也会失败。表面看是 Agent 编排问题实际是模型通道没有统一。所以本文按 Agent / Harness 视角处理先把 TaoToken Key 建好再把 Spring AI 的 OpenAI starter 指向https://taotoken.net/api。RAG 管道不改mcp-servers.json不改SupervisorAgent源码不改。所有 Agent 共用同一把 Key、同一个 base-url只是每轮模型请求都由 TaoToken 承接。TaoToken 前置先建 Key再决定模型 ID先打开官网创建 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content登录后进入控制台创建 API Key。复制出来的 Key 就是后面application.yml里的YOUR_API_KEY。建议不要硬编码进 Git而是放到环境变量export TAOTOKEN_API_KEYYOUR_API_KEY export TAOTOKEN_MODEL_IDYOUR_MODEL_ID export TAOTOKEN_EMBEDDING_MODELYOUR_EMBEDDING_MODEL_ID模型 ID 以控制台里实际可用的为准。本文不写具体模型评测也不建议猜模型名。Spring AI 的spring.ai.openai.chat.options.model填什么取决于你在 TaoToken 控制台选择的模型通道。Embedding 模型也一样如果 RAG 管道要用向量检索就需要确认 TaoToken 侧是否开通对应 embedding 模型并保证向量维度与 pgvector 表里的vector(1536)或实际维度一致。API 地址使用https://taotoken.net/api注意三点不要写成https://taotoken.net/api/v1因为本文要求 base-url 不带/v1。不要给 API 地址加 UTM 参数UTM 只用于官网和 CTA 链接。不要把官网首页地址直接填进base-url官网用于创建 KeyAPI 用于模型请求。Key 管理、重新生成、查看接入信息时可以走 API Keys 和接入文档API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspring_ai_multi_agent接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspring_ai_multi_agent可复制配置application.yml、mcp-servers.json 与 SupervisorAgent 共用 ChatClient原来的application.yml可能是这样spring: ai: openai: api-key: ${OPENAI_API_KEY} chat: options: model: gpt-4o temperature: 0.3现在改成 TaoToken 统一通道spring: ai: openai: api-key: ${TAOTOKEN_API_KEY:YOUR_API_KEY} base-url: https://taotoken.net/api chat: options: model: ${TAOTOKEN_MODEL_ID:YOUR_MODEL_ID} temperature: 0.3 embedding: options: model: ${TAOTOKEN_EMBEDDING_MODEL:YOUR_EMBEDDING_MODEL_ID} datasource: url: jdbc:postgresql://localhost:5432/agent_db username: postgres password: ${DB_PASSWORD} servlet: multipart: max-file-size: 50MB max-request-size: 50MBmcp-servers.json保持原样不需要因为 TaoToken 而改{ mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /data/knowledge], env: {} }, github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } }, postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres, postgresql://localhost:5432/agent_db], env: {} } } }Agent 配置类里ChatClient 仍然按原来的方式组装Configuration public class AgentConfig { Bean public ChatMemory chatMemory() { return MessageWindowChatMemory.withMaxMessages(20); } Bean public ChatClient chatClient( ChatClient.Builder builder, ToolCallbackProvider mcpToolProvider, ChatMemory chatMemory, VectorStore vectorStore) { return builder .defaultSystem(你是企业知识库多 Agent 主管负责调度 RAG、MCP 工具和审校流程。) .defaultTools(mcpToolProvider) .defaultAdvisors( new MessageChatMemoryAdvisor(chatMemory), new QuestionAnswerAdvisor(vectorStore) ) .build(); } }SupervisorAgent中生成计划的调用不变String planJson chatClient.prompt() .system(SUPERVISOR_PROMPT) .user(userTask) .call() .content();ReviewAgent审校也不变String review reviewAgent.review(finalAnswer, userTask); if (review.contains(NEEDS_REVISION)) { finalAnswer chatClient.prompt() .user(根据审校意见修改回答 finalAnswer \n审校意见 review) .call() .content(); }RagPipeline里的生成调用同样不变return chatModel.generate(prompt);变化只在spring.ai.openai这一段。因为 Spring AI 的 OpenAI starter 会统一使用api-key和base-url所以 SupervisorAgent、ResearchAgent、KnowledgeAgent、ReviewAgent、RagPipeline 都走同一个 TaoToken 通道。验证请求RAG 检索、MCP 工具调用与 ReviewAgent 审校回溯先启动 PostgreSQL 和 pgvector执行初始化 SQL然后设置环境变量export TAOTOKEN_API_KEYYOUR_API_KEY export TAOTOKEN_MODEL_IDYOUR_MODEL_ID export TAOTOKEN_EMBEDDING_MODELYOUR_EMBEDDING_MODEL_ID export DB_PASSWORDyourpassword启动 Spring Bootmvn spring-boot:run先验证知识库上传curl -X POST http://localhost:8080/api/agent/knowledge/upload \ -F file/tmp/spring-ai-agent.pdf期望返回类似{ status: success, fileName: spring-ai-agent.pdf, chunkCount: 42 }chunkCount大于 0说明分块和嵌入请求已经发出。如果这里报 401 或连接错误优先检查spring.ai.openai.api-key和base-url。再验证多 Agent 问答curl -X POST http://localhost:8080/api/agent/chat \ -H X-Session-Id: session-001 \ -H Content-Type: application/json \ -d {message:结合知识库说明 SupervisorAgent 如何调度 MCP 工具并让 ReviewAgent 审校}成功返回里应包含这些字段{ answer: SupervisorAgent 先分解任务再调度 ResearchAgent 与 KnowledgeAgent..., sources: [spring-ai-agent.pdf, Web Search: MCP tool calling], plan: { steps: [ {action: rag_search, query: SupervisorAgent 调度}, {action: research, query: MCP 工具调用}, {action: answer}, {action: review} ] }, durationMs: 12345 }你要观察的成功标志有没有401 Unauthorized说明 Key 生效。没有404 Not Found说明base-url没有多写/v1或错写路径。plan.steps中出现rag_search、research、answer、review说明 SupervisorAgent 正常分解。sources中出现知识库文件名说明 RAG 检索和 KnowledgeAgent 参与。MCP 工具如 filesystem、github、postgres 返回结构化内容说明ToolCallbackProvider注入正常。ReviewAgent 没有反复返回NEEDS_REVISION或者只触发一次修订后通过。Agent Loop 没有连续多次调用同一个工具、同一组参数。如果这些点都满足就说明 Spring AI 的多 Agent 工程已经在统一通道下完成 RAG 检索、MCP 工具调用和审校回溯。本篇常见错排查application.yml、base-url、Agent Loop 与 ReviewAgent下面这些是本篇场景里最容易遇到的错误。1. base-url 写成https://taotoken.net/api/v1本文要求 base-url 是https://taotoken.net/api不要带/v1也不要加 UTM 参数。Spring AI 的 OpenAI starter 会自己拼接请求路径手动多写/v1可能导致路径重复表现为 404。2. api-key 还在读${OPENAI_API_KEY}原文 8.4/8.5 节是${OPENAI_API_KEY}改成 TaoToken 后应该改为api-key: ${TAOTOKEN_API_KEY:YOUR_API_KEY}如果环境变量没切换Spring 仍然去读旧变量就会 401。3. 模型 ID 与控制台不一致spring.ai.openai.chat.options.model不能凭感觉写。去控制台复制实际模型 ID再填到TAOTOKEN_MODEL_ID。如果模型 ID 不存在Supervisor 第一轮计划生成就会失败。4. Embedding 维度与 pgvector 不一致RAG 管道如果报维度错误检查 embedding 模型输出维度与建表语句里的vector(1536)是否一致。切换 embedding 模型后旧向量数据需要重新导入。5. MCP 工具调用正常但模型请求失败MCP 工具调用和模型鉴权是两条链路。MCP Server 返回工具结果不代表 ChatModel 能访问模型。看到工具日志正常、但回答为空或报 401优先查application.yml的 OpenAI 配置。6. Agent Loop 重复调用同一工具在ReactAgent或 Supervisor 执行循环里加硬上限和重复检测。例如连续 3 次调用同一工具同一参数时注入系统提示要求模型换方法或直接回答。否则长会话会反复消耗模型通道。7. ReviewAgent 不触发或解析失败如果 Supervisor 要求模型输出 JSON 计划但模型返回了额外解释文字JsonParser.parse会失败。可以在提示词里强调“只输出 JSON”或改用 Spring AI 的结构化输出能力。8. 长会话撑爆上下文多 Agent 编排加上 MCP 工具结果后上下文增长很快。使用MessageWindowChatMemory保留最近 N 条并在超过阈值时做摘要。不要把全部历史都塞进每一轮模型请求。9. MCP 子进程内存持续增长stdio 模式的 MCP Server 长时间运行后可能累积日志和文件句柄。可以在编排外层定期重启子进程或把 MCP Server 改成 HTTP 模式远程部署。排障时优先看两个地方API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspring_ai_multi_agent接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspring_ai_multi_agent语义一致 CTAAgent 长会话统一走 TaoToken这篇的语义很明确TaoToken 只承接模型请求RAG 管道、MCP 配置、SupervisorAgent 编排源码保持原样。你改的是application.yml里的spring.ai.openai.api-key和spring.ai.openai.base-url让 Supervisor 分解任务、MCP 工具结果回灌、KnowledgeAgent 检索、ReviewAgent 审校都共用同一把 Key。如果你已经跑通这个 Spring AI 多 Agent 工程准备把它用于长期编码、Agent 编排或日常多工具任务可以走 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspring_ai_multi_agent如果你需要重新创建 Key、管理接入配置或排查鉴权问题走 API Keys 和接入文档https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspring_ai_multi_agenthttps://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspring_ai_multi_agent如果你只是想先验证模型通道是否能通再决定是否接入完整多 Agent 工程可以先用模型对话做一次最小请求https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentspring_ai_multi_agent先把 Key、base-url、模型 ID 三件事对齐再跑 SupervisorAgent 调度 ResearchAgent、KnowledgeAgent、ReviewAgent 的长会话链路。这样排障时就能把问题定位在模型通道、MCP 工具还是 RAG 检索本身而不是在一堆 Agent 源码里来回猜。