1. 为什么第 1 周最容易卡在“模型通道”这一步如果你是从 Java 后端转 AI Agent第 1 周的目标其实特别朴素用 Spring AI 写一个能调用工具的最小 Agent问一句“北京今天天气怎么样”它能自己决定去调天气工具然后把结果组织成人话返回。就这么点事。但真正动手你会发现卡住你的往往不是 Agent 的工具编排逻辑而是模型客户端那一步官方 Key 怎么申请、Base URL 到底填哪个、要不要带/v1、环境变量怎么注入、Spring AI 的OpenAiApi和OpenAiChatModel到底该配哪几个参数。这些琐事能把一个本来 30 分钟能跑通的例子拖成两三天。我试过最省事的做法是把模型通道这一层单独拎出来解决用 TaoToken 拿一个 Key把 Spring AI 里原本填官方 Base URL 的位置换成 TaoToken 的 API 地址其余代码一行不动。TaoToken 只出现在“模型通道”这一层它不参与你的 Agent 工具编排也不碰你的业务逻辑——你的Tool、你的ChatClient、你的工具回调全都还是 Spring AI 原生的写法。这篇就按“接入配置”的视角把第 1 周最小 Agent 跑通的全过程拆开从拿 Key、配application.yml、写天气工具到启动验证、看请求是否真的打出去、再到几个我踩过的报错。目标只有一个让你今天就能看到那句天气回答然后安心进入第 2 周把例子换成供应链金融网关里的日志分析或报文校验。适合谁看写过 Spring Boot、知道Bean和ConfigurationProperties是怎么回事、但还没真正跑通过一个 Agent 的 Java 程序员。不需要你懂 Python也不需要你先啃完 LangChain 文档。2. 前置准备拿一个 TaoToken Key认清它只干一件事在动 Spring AI 代码之前先把模型通道这层准备好。打开https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end注册账号进控制台创建一个 API Key。这个 Key 就是你后面填进 Spring AI 配置里的那个api-key用法和你以前填官方 Key 完全一样。这里要把边界说清楚避免后面概念混乱TaoToken 负责的是“模型通道”这一层——你的 Spring AI 客户端把请求发出去它帮你把请求转到对应模型再把结果返回。它不参与 Agent 的工具编排不参与你的Tool方法调用也不参与业务逻辑。换句话说你的 Agent 还是那个 Agent只是它调用 LLM 的那条网络链路换了个入口。所以你在 Spring AI 里要改的只有两个值配置项原来填什么现在填什么base-url官方 API 地址https://taotoken.net/apiapi-key官方申请的 KeyTaoToken 控制台生成的 Key注意 Base URL 这里有个高频坑填https://taotoken.net/api不要在后面加/v1。Spring AI 的 OpenAI 兼容客户端会自己在路径上拼接/v1/chat/completions这类后缀你手动再加一层/v1请求路径就变成/api/v1/v1/...直接 404。这个坑我在第一次配的时候踩得结结实实日志里一堆 404 还以为是 Key 没生效。另外Key 不要硬编码进代码提交到仓库。用环境变量或者本地application-local.yml注入后面第 5 节会给具体写法。3. 可复制配置Spring AI 模型客户端怎么填下面这套配置基于 Spring Boot 3.x Spring AI 的 OpenAI 兼容 starter。版本上建议用 Spring AI 1.0.x 之后的稳定版早期 milestone 的包名和配置前缀变过几次容易对不上。3.1 Maven 依赖dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-openai-spring-boot-starter/artifactId version1.0.0/version /dependency如果你用的是 Spring AI 的 BOM 管理版本把version交给 BOM 即可。仓库方面稳定版已经进 Maven Central不需要额外加 snapshot 仓库。3.2 application.yml 配置spring: ai: openai: base-url: https://taotoken.net/api api-key: ${TAOTOKEN_API_KEY} chat: options: model: gpt-4o-mini temperature: 0.7三个关键点base-url就是 TaoToken 的 API 地址结尾不带/v1。api-key用占位符从环境变量读本地启动前export TAOTOKEN_API_KEY你的Key就行。model填你要用的模型名具体支持哪些模型以 TaoToken 控制台或文档里列的为准别照抄我这里的名字。3.3 模型客户端 Bean大多数情况下 starter 会自动装配OpenAiChatModel你直接注入就能用。但如果你想显式控制可以自己声明Configuration public class ModelConfig { Bean public OpenAiChatModel chatModel(OpenAiApi openAiApi) { return OpenAiChatModel.builder() .openAiApi(openAiApi) .build(); } }OpenAiApi同样由 starter 根据base-url和api-key自动构建。你不需要手动 new也不需要去改它的路径拼接逻辑——这正是把 Base URL 填对之后最省心的地方。3.4 最小 Agent一个天气工具 ChatClientAgent 的“最小”形态就是一个能调用工具的ChatClient。先定义工具Component public class WeatherTools { Tool(description 查询指定城市的当前天气) public String getWeather(ToolParam(description 城市名称例如 北京) String city) { // 真实项目里这里调天气 API示例先返回模拟数据 return city 今天晴气温 18 到 26 摄氏度微风。; } }再写 Agent 入口Service public class MiniAgent { private final ChatClient chatClient; public MiniAgent(ChatClient.Builder builder, WeatherTools weatherTools) { this.chatClient builder .defaultTools(weatherTools) .build(); } public String ask(String question) { return chatClient.prompt() .user(question) .call() .content(); } }注意defaultTools(weatherTools)这一步——它把工具注册给模型模型在收到“天气”相关问题时会自己决定调用getWeather。这就是 Agent 和普通聊天机器人的区别工具编排由模型驱动你只负责把工具挂上去。4. 验证请求启动后问一句天气确认真的跑通配置写完启动 Spring Boot 应用。如果启动阶段没报OpenAiApi相关的 Bean 创建失败说明 Base URL 和 Key 至少被正确读进去了。写一个简单的 CommandLineRunner 或者测试类来触发Component public class AgentRunner implements CommandLineRunner { private final MiniAgent miniAgent; public AgentRunner(MiniAgent miniAgent) { this.miniAgent miniAgent; } Override public void run(String... args) { String answer miniAgent.ask(北京今天天气怎么样); System.out.println(Agent 回答: answer); } }启动后控制台应该能看到类似输出Agent 回答: 北京今天晴气温 18 到 26 摄氏度微风。看到这句话说明整条链路通了Spring AI 把请求发到 TaoToken 的 API 地址模型返回了工具调用意图Spring AI 执行了你的getWeather再把结果交回模型组织成自然语言。怎么确认“调用是否成功”而不只是“有输出”两个办法。一是在getWeather里打一行日志看到日志说明工具真的被执行了而不是模型凭空编了个天气。二是打开 Spring AI 的请求日志logging: level: org.springframework.ai: DEBUGDEBUG 日志里能看到实际发出的请求 URL 和响应体。如果 URL 是https://taotoken.net/api/v1/chat/completions这种形态说明 Base URL 拼接正确如果出现重复的/v1回到第 2 节检查配置。这一步跑通之后第 1 周的任务就算完成了。你可以把ask的入参换成任意问题观察模型什么时候调工具、什么时候直接回答——这个体感比看十篇 Agent 原理文章都管用。5. 本篇常见错排查下面这几个是我和身边朋友在配 Spring AI TaoToken 时真实撞到过的按出现频率排。报错一404 Not Found路径里出现重复的/v1。原因基本是base-url填成了https://taotoken.net/api/v1。Spring AI 会自己拼/v1/chat/completions你再加一层就重复了。改成https://taotoken.net/api即可。报错二401 Unauthorized。Key 没读到。检查环境变量名是否和application.yml里的占位符一致注意大小写。用 IDE 启动时环境变量要在 Run Configuration 里配光在终端export对 IDE 里的进程不一定生效。报错三模型名不存在或 400。chat.options.model填的模型名不在可用列表里。以 TaoToken 控制台或文档里列出的模型名为准别凭记忆填。报错四工具没被调用模型直接编了个答案。先确认defaultTools真的挂上了再确认工具方法的description写得够清楚。模型是靠 description 判断要不要调工具的描述太模糊它就会选择直接回答。另外ToolParam的参数说明也建议写全。报错五启动时报OpenAiApiBean 找不到。多半是 starter 依赖没引对或者版本和 Spring Boot 不匹配。确认spring-ai-openai-spring-boot-starter的版本与你的 Spring Boot 3.x 兼容必要时用 Spring AI BOM 统一版本。报错六请求超时。网络链路问题先确认本机能正常访问https://taotoken.net/api这个地址。如果公司网络有出口限制找运维确认放行。6. 跑通之后把通道配置和 Agent 逻辑分开看第 1 周跑通最小 Agent 之后我最大的收获不是“会写 Agent 了”而是把两件事彻底分开了模型通道是一层Agent 的工具编排和业务逻辑是另一层。前者用 TaoToken 的 Key 和 Base URL 一次性配好后面几周基本不用再动后者才是你真正要花时间打磨的东西。第 2 周你可以把天气工具换成供应链金融网关里的真实场景——比如日志分析工具、报文校验工具。工具的实现逻辑换成你的业务代码ChatClient和模型配置那部分原封不动。这就是把通道层和业务层解耦的好处换场景不用重新折腾 Key 和 Base URL。如果你后面要长期跑编码类或 Agent 类任务可以了解下 Coding Plan 这类方案适合高频调用场景想先验证模型对话效果直接进模型对话页面试几句也行。接入过程中遇到配置问题接入文档和 API Keys 管理页面能帮你对照排查。地址统一从https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end进控制台里创建和管理 Key 都在同一个地方。最后给一个实用建议把TAOTOKEN_API_KEY写进你本地的.env或者 IDE 的启动配置模板里别每次手动 export。第 2 周开始你会频繁重启应用调工具省下这一步能少很多烦躁。