1. 从 Spring Boot 到 AI AgentJava 后端转型的真实起点如果你写了几年 Spring Boot日常是 Controller、Service、Mapper 三层结构突然要转 AI Agent 方向第一反应往往是我是不是得把 Java 全扔了答案是不用。但你必须承认一个现实——AI Agent 的上游生态Python 是绝对主场。LangChain、LangGraph、OpenAI SDK、MCP 官方示例几乎都是 Python 优先发布、文档最全、社区最活跃。Java 侧的 Spring AI、LangChain4j 在追赶但新特性通常晚几个月。所以更务实的路径是保留 Spring Boot 作为业务后端和网关用 Python 单独起一个 Agent 服务两者通过 HTTP 或消息队列通信。这样你不需要重写已有系统只需要新增一个 Python 模块。本文就按这个思路走先搭一个最小可运行的 Python LangChain Agent 骨架再把模型调用的 endpoint 和 Key 统一改到 TaoToken让你用一个 Key 就能切换不同模型不用在多个厂商控制台之间来回折腾。适合谁看有 Java 基础、能看懂 REST 接口和依赖管理、但 Python 只写过脚本的开发者。你不需要先学完 Python 语法再来边搭边补最快。接下来我会给出完整的环境配置、依赖清单、可复制的 Agent 代码以及一次真实的调用验证。踩过的坑我也会标出来比如 401 报错、local proxy failed、OAuth 配置这些高频问题。2. TaoToken 前置准备统一 Key 与 Base URL 的接入逻辑在写 Agent 之前先把模型调用的出口定下来。很多 Java 开发者习惯在 application.yml 里配一堆厂商的 keyOpenAI 一个、Claude 一个、国内厂商再一个切换模型就要改配置重启。TaoToken 的思路是提供一个统一的 OpenAI 兼容 endpoint你只需要一个 Key 和一个 Base URL就能调用不同模型。官网地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 。具体要准备三样东西Base URL、API Key、Model ID。Base URL 填 https://taotoken.net/api 注意末尾不要多加 /v1OpenAI SDK 会自己拼路径。API Key 在控制台的 API Keys 页面创建地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。Model ID 取决于你想用哪个模型比如 gpt-4o-mini、claude-3-5-sonnet 这类具体以控制台模型列表为准。这里有个 Java 开发者容易混淆的点Spring Boot 里你习惯用 Value 注入配置Python 里更常见的是环境变量加 python-dotenv。我建议你把 Key 放在 .env 文件里代码里用 os.getenv 读取这样既不会把密钥提交到 Git也方便本地和服务器用不同配置。下面是一个 .env 示例# .env TAOTOKEN_API_KEYsk-你的实际key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELgpt-4o-mini注意 .env 一定要加进 .gitignore。我见过有人把 Key 直接写进代码提交到公开仓库结果被扫号脚本几分钟内刷爆额度。另外如果你在 Java 侧也要调用同一个 endpointSpring AI 的 OpenAiApi 也支持自定义 base-url配置方式类似这里不展开。3. 可复制配置Python 环境、依赖清单与 Agent 骨架这一节是核心所有代码都可以直接复制运行。先建项目目录推荐用 uv 管理依赖比 pip 快很多。如果你还没装 uv可以用 pip install uv 先装上。uv init java2agent cd java2agent uv venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate uv add langchain langchain-openai python-dotenv依赖清单对应到 pyproject.toml 大致是这样你可以直接对照[project] name java2agent version 0.1.0 requires-python 3.11 dependencies [ langchain0.3, langchain-openai0.2, python-dotenv1.0, ]接下来是 Agent 骨架。我把它拆成两个文件config.py 负责读环境变量agent.py 负责构建 LangChain 的调用链。先看 config.py# config.py import os from dotenv import load_dotenv load_dotenv() TAOTOKEN_API_KEY os.getenv(TAOTOKEN_API_KEY) TAOTOKEN_BASE_URL os.getenv(TAOTOKEN_BASE_URL, https://taotoken.net/api) TAOTOKEN_MODEL os.getenv(TAOTOKEN_MODEL, gpt-4o-mini) if not TAOTOKEN_API_KEY: raise RuntimeError(TAOTOKEN_API_KEY 未设置请检查 .env 文件)然后是 agent.py用 LangChain 的 ChatOpenAI 指向 TaoToken 的 endpoint# agent.py from langchain_openai import ChatOpenAI from langchain_core.prompts import ChatPromptTemplate from langchain_core.output_parsers import StrOutputParser from config import TAOTOKEN_API_KEY, TAOTOKEN_BASE_URL, TAOTOKEN_MODEL llm ChatOpenAI( modelTAOTOKEN_MODEL, api_keyTAOTOKEN_API_KEY, base_urlTAOTOKEN_BASE_URL, temperature0.3, ) prompt ChatPromptTemplate.from_messages([ (system, 你是一个帮助 Java 开发者理解 AI Agent 的助手回答要简洁、可操作。), (user, {question}), ]) chain prompt | llm | StrOutputParser() if __name__ __main__: answer chain.invoke({question: 用一句话解释 LangChain 的 Runnable 是什么}) print(answer)这里的关键参数是 base_url 和 api_key。LangChain 的 ChatOpenAI 底层就是 OpenAI SDK所以只要 endpoint 兼容 OpenAI 协议就能直接指向 TaoToken。temperature 控制随机性做 Agent 决策时建议 0.2 到 0.4太高会导致工具调用不稳定。如果你更习惯用原生 OpenAI SDK也可以这样写效果一样from openai import OpenAI from config import TAOTOKEN_API_KEY, TAOTOKEN_BASE_URL, TAOTOKEN_MODEL client OpenAI(api_keyTAOTOKEN_API_KEY, base_urlTAOTOKEN_BASE_URL) resp client.chat.completions.create( modelTAOTOKEN_MODEL, messages[{role: user, content: 你好}], ) print(resp.choices[0].message.content)两种方式我都试过LangChain 的好处是后面接工具调用、记忆、工作流更顺原生 SDK 的好处是依赖少、调试直观。你可以先用原生 SDK 跑通再换成 LangChain。4. 验证请求一次完整的 Agent 调用与成功结果配置写完后先做最小验证。运行 python agent.py如果一切正常你会看到模型返回的一句话解释。这一步能跑通说明 Key、Base URL、Model ID 三件套都对。python agent.py # 输出示例Runnable 是 LangChain 中所有可调用组件的统一接口支持 invoke、stream、batch 等方法。如果这一步就报错先别急着往下走对照第 5 节的排查清单。跑通之后我们加一个带工具调用的 Agent验证它不只是聊天还能执行动作。新建 tools_agent.py# tools_agent.py from langchain_openai import ChatOpenAI from langchain_core.tools import tool from langchain_core.messages import HumanMessage from config import TAOTOKEN_API_KEY, TAOTOKEN_BASE_URL, TAOTOKEN_MODEL tool def word_count(text: str) - int: 统计一段文本的字符数 return len(text) llm ChatOpenAI( modelTAOTOKEN_MODEL, api_keyTAOTOKEN_API_KEY, base_urlTAOTOKEN_BASE_URL, temperature0.2, ) llm_with_tools llm.bind_tools([word_count]) messages [HumanMessage(帮我统计这句话有多少个字Java 程序员转型 AI Agent)] resp llm_with_tools.invoke(messages) print(tool_calls:, resp.tool_calls) if resp.tool_calls: for tc in resp.tool_calls: result word_count.invoke(tc[args]) print(f工具 {tc[name]} 返回: {result})运行后你应该看到类似输出tool_calls: [{name: word_count, args: {text: Java 程序员转型 AI Agent}, id: call_xxx}] 工具 word_count 返回: 18这说明模型正确识别了意图、生成了工具调用参数你的 Agent 骨架已经具备执行能力。接下来你可以把这个逻辑接到 FastAPI 上暴露成 HTTP 接口让 Spring Boot 通过 RestTemplate 或 WebClient 调用。FastAPI 的写法很简单# server.py from fastapi import FastAPI from pydantic import BaseModel from agent import chain app FastAPI() class ChatRequest(BaseModel): question: str app.post(/chat) async def chat(req: ChatRequest): answer chain.invoke({question: req.question}) return {answer: answer}启动命令是 uvicorn server:app --host 0.0.0.0 --port 8000。这样 Java 侧就能像调用普通微服务一样调用 Agent 服务职责清晰互不干扰。5. 本篇常见错排查401、local proxy failed 与 OAuth 配置这一节列的都是真实会遇到的报错按出现频率排序。第一个是 401 Unauthorized。最常见原因是 Key 没读到或者 .env 文件路径不对。python-dotenv 默认从当前工作目录找 .env如果你在子目录运行脚本就会读不到。解决办法是在 config.py 里显式指定路径load_dotenv(dotenv_pathPath(file).parent / .env)。另一个原因是 Key 复制时带了空格或换行建议用 print(repr(TAOTOKEN_API_KEY)) 检查一下。第二个是 local proxy failed 或 connection error。这通常是本地网络环境或代理配置导致的。如果你在终端里设过 HTTP_PROXY 或 HTTPS_PROXY 环境变量OpenAI SDK 会尝试走代理但代理不可用就会报这个错。排查方法是先 echo $HTTPS_PROXY 看看有没有值有的话临时 unset 掉再运行。另外确认 base_url 写的是 https://taotoken.net/api 不要写成 http 或漏掉 /api。第三个是 reading choices 相关的 KeyError 或 IndexError。这通常发生在你直接访问 resp.choices[0] 但返回结构不符合预期时。可能原因是模型名写错endpoint 返回了错误信息而不是正常响应。建议先打印完整 resp 对象确认结构。用 LangChain 的话StrOutputParser 会帮你处理但原生 SDK 要自己判断。第四个是 OAuth 或认证方式混淆。TaoToken 用的是 API Key 认证不是 OAuth。如果你在代码里配了 client_id、client_secret 这类参数会认证失败。正确做法就是 api_key 加 base_url不要混入其他认证字段。如果你用的是 Claude Code 这类工具它的配置方式不同需要单独看接入文档地址是 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。第五个是模型不存在或 model not found。Model ID 必须和控制台列表一致大小写敏感。建议先用 curl 测一下curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:gpt-4o-mini,messages:[{role:user,content:ping}]}如果 curl 能通而 Python 不通问题就在代码或环境变量如果 curl 也不通问题在 Key 或网络。6. 语义一致 CTA下一步怎么走跑通上面的 Agent 骨架后你已经有了一条从 Java 到 Python 的最小通路。接下来建议做三件事第一把工具调用扩展成真实业务工具比如查数据库、调内部 API第二加上记忆机制让 Agent 能记住多轮对话第三把服务部署起来让 Spring Boot 能稳定调用。如果你要长期做编码类 Agent比如自动改代码、跑测试、提交 PR建议了解一下 Coding Plan地址是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。如果你只是想先验证模型效果可以直接在模型对话页面试地址是 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 。需要管理多个 Key 或查看用量去控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 。最后说一个实用技巧Java 侧调用 Python Agent 服务时建议加超时和重试。LLM 调用延迟波动大默认超时可能不够。Spring 的 RestTemplate 可以配 SimpleClientHttpRequestFactory 设置 readTimeoutWebClient 则用 timeout(Duration.ofSeconds(60))。这样即使模型响应慢你的业务线程也不会被拖死。