这两年问 AI Agent 开发的人明显变多了。很多人以为 Agent 开发就是“写个 Prompt调一下大模型 API”等真正动手做才发现Demo 能跑通和生产可用完全是两回事。本文想给出一条从零基础到企业级项目实战的完整路径。文章会从核心概念讲起然后拆解 Agent 开发的关键环节用 Python 和 Java 两套技术栈做最小可运行示例最后落点到生产环境最容易踩的坑和工程化取舍。如果你正准备把 AI Agent 引入实际项目或者正在面试 Agent 相关岗位这篇文章可以帮你少走很多弯路。先说一个核心判断AI Agent 开发的门槛不在大模型 API 调用而在工程化能力。模型能力是底座但真正决定项目成败的是工具设计、状态管理、容错机制、评估方式和安全边界。2026 年的 Agent 开发已经过了“跑通 Demo 就算会”的阶段行业需要的是能交付、能维护、能评估的工程化能力。1. AI Agent 开发到底在解决什么问题先看传统软件开发的模式输入 → 固定逻辑 → 输出。这种模式下业务逻辑是预先写死的。用户提交订单就调订单接口用户查询就查数据库。问题在于很多企业场景并不是固定流程而是“需要一定推理和决策”的复杂任务。比如用户问“帮我对比这几家云厂商的价格然后给出一份选型建议”运营说“把上周的销售数据复盘一下找出下滑原因并生成日报”研发说“这个日志异常帮我定位一下可能的原因并给出排查命令”这些任务有几个共性输入是非结构化的执行路径不是固定的需要外部信息和内部系统协同。如果都靠人工处理效率极低如果靠传统代码写死又覆盖不了变化无穷的用户表达。AI Agent 的核心价值在于让大模型在“理解任务”的基础上通过工具调用、记忆管理和多轮规划替代人去完成一个相对复杂的业务动作。它解决的真正问题是“非固定流程任务的自动化”而不仅仅是“对话”。从这个角度理解Agent 和普通 ChatBot 的界限就很清晰了维度普通 ChatBotAI Agent任务范围单轮问答多轮复杂任务执行能力生成文字调用工具、查库、写文件、发请求状态管理无状态有上下文、有记忆、有任务状态决策方式固定回复自主规划、循环执行2026 年的分水岭在于行业已经不再满足于“能聊”而是要求 Agent“能干活”并且“干活的过程可追踪、结果可评估、出错可回滚”。2. AI Agent 核心概念模型、工具、记忆、规划与多 Agent 协作理解 Agent 开发先要把几个核心概念拆开。很多新手混淆概念导致架构设计一上来就是错的。2.1 大模型底座 LLM大模型是 Agent 的“大脑”负责理解用户的自然语言输入、推理任务拆解、决定调用哪个工具。你可以把 LLM 视为一个“推理引擎”它的输入是带历史消息的 Prompt输出是文本或者结构化的工具调用指令。在 Agent 架构里LLM 不是被直接使用的“最终答案生成器”而是“决策中枢”。这个定位变化很重要。2.2 Function Calling 工具调用这是 Agent 落地最关键的机制。大模型本身不能访问外部世界需要靠工具Functions拿到信息或者执行动作。工具调用机制可以分解为三步开发者在接口中向模型声明有哪些工具以及每个工具的入参 Schema。模型根据用户任务判断“该调用哪个工具”返回一个结构化的 tool_calls 请求。开发者的程序执行对应工具把结果回传给模型模型再决定下一步动作。工具设计直接决定了 Agent 的能力边界。一个只有“查天气”工具的 Agent 做不了业务一个有“查询订单”“余额变更”“用户信息”等丰富工具集的 Agent 才能服务真实业务。2.3 记忆 MemoryAgent 的记忆分为短期记忆和长期记忆。记忆类型存储内容生命周期典型实现短期记忆当前任务的上下文、工具调用结果一次会话对话消息列表长期记忆用户偏好、历史事实、领域知识跨会话向量数据库 知识库短期记忆主要靠把历史消息拼进 Prompt 实现简单但受上下文窗口限制。长期记忆则需要引入向量数据库、向量检索和知识切片等技术这也是 RAG检索增强生成在 Agent 架构中扮演记忆系统重要部分的原因。2.4 规划 Planning规划能力是 Agent 与普通 LLM 应用最大的区别之一。任务复杂时Agent 需要把大任务拆解成多个子步骤并决定执行顺序。常见实现方式有ReAct 模式推理 → 行动 → 观察 → 再推理循环推进。思维链 CoT让模型一步步推理提升复杂问题正确率。Plan-and-Execute先整体规划再逐步执行每步执行结果反馈到规划器。树状规划 Tree-of-Thought同时探索多个候选路径做权衡取舍。生产环境中纯靠模型自由规划的稳定性并不够所以越来越多的架构采用“固定工作流 节点内模型自主决策”的混合编排方式。2.5 多 Agent 协作 Multi-Agent单个 Agent 处理复杂任务容易上下文爆炸、职责混乱。多 Agent 架构是把不同职责拆成多个 Agent比如任务规划 Agent、工具执行 Agent、质检 Agent、兜底 Agent由协调器 Agent 进行调度。多 Agent 的优势是职责分离、便于维护和权限隔离劣势是调用次数增加、成本上升、排错复杂度提高。对于大部分业务场景单 Agent 高质量工具集才是第一选择多 Agent 是优化手段不是目的。3. 环境准备与技术选型手写一个 Agent 其实不需要很重的框架。从学习路径上看建议先“手写理解原理”再“用框架提升效率”。3.1 基础环境要求开发 Agent 建议准备以下环境Python 3.10 或 JDK 17取决于你选择的语言。一个 LLM API Key优先选择兼容 OpenAI 风格的接口服务。网络能正常访问模型服务接口。本地开发工具VS Code 或 IntelliJ IDEA建议安装 HTTP 调试插件。如果需要做记忆系统可以准备 Docker 用来跑向量数据库如 Milvus、Chroma 或 PostgreSQL pgvector。版本细节以实际项目使用为准本文重在演示通用思路。3.2 技术栈选型技术栈适合场景代表框架学习成本Python原型验证、数据分析类 Agent、算法研究LangChain、LlamaIndex、自实现较低Java/Spring企业级应用、与现有微服务体系集成Spring AI、LangChain4j中Node.js前端团队全栈开发、轻量服务LangChain.js中选型原则是跟着团队现有的工程体系走不要为了 Agent 引入一套新语言栈。Python 适合做快速验证和算法侧工作但很多企业的核心业务跑在 Java 体系里这时候 Spring AI 是更务实的接入方案。3.3 模型 API 的通用调用方式目前主流 LLM 服务大多兼容 OpenAI 的 Chat Completions 接口风格。即使你用的是国内模型、开源模型或中间层网关也基本都能通过统一 OpenAI 兼容端点接入。这意味着Agent 代码与具体模型服务解耦换模型只需要改 endpoint 和 api_key。下面是一段配置文件示例# 文件路径config.properties llm.api-basehttps://your-llm-endpoint.example.com/v1 llm.api-key${LLM_API_KEY} llm.modelyour-model-name llm.temperature0.2用环境变量注入 API Key不写死在代码里这是生产级项目的基本要求。4. 核心流程拆解从零到一的五个关键节点很多入门教程一上来就让读者复制代码结果代码能跑但换个任务就不会做了。原因是缺少了“从任务到 Agent 架构”的设计过程。这里梳理五个关键环节。4.1 第一步任务定义与边界划分做 Agent 前第一件事不是写代码而是明确任务边界。建议用一句话说清楚Agent 的输入是什么输出是什么哪些事它绝对不做做不了时怎么办。举个例子输入用户的文字问题或指令。输出结构化的分析报告、工具执行结果。不做不处理包含银行账号的敏感操作这类请求直接转人工。不做不执行任何没有二次确认的删除类操作。失败兜底连续两次工具调用失败后停止重试并向用户展示错误信息。没有边界定义的 Agent上线后就是一台不可控的“自动翻车机器”。4.2 第二步模型选型与参数配置模型选择直接影响 Agent 的工具调用准确率。需要考虑三个因素上下文窗口任务是否需要处理超长文本。工具调用能力模型是否稳定输出符合 Schema 的工具参数。成本与延迟企业场景要考虑单次任务平均消耗多少 token、响应多快。参数配置上temperature建议调低一般在 0.1 到 0.3 之间。工具调用场景需要的是确定性不是创造性。max_tokens要设置上限避免模型输出过长文本拖慢循环。4.3 第三步工具设计工具是 Agent 能力的边界也是工程质量最集中的体现。设计工具时注意三点单一职责每个工具只做一件事。不要设计一个“全能处理”的工具否则模型非常容易传错参数。参数描述具体工具的描述和参数 Schema 要写清楚让模型能准确理解工具该用于什么场景。容错返回工具执行失败时返回给模型的消息要包含错误原因而不是只抛异常。4.4 第四步记忆与上下文管理上下文管理是生产环境必踩的坑。模型上下文窗口有限不可能把全部历史都拼进 Prompt。常见策略滑动窗口只保留最近 N 轮对话。摘要压缩每多轮对话后用模型生成一次历史摘要。关键信息抽取把用户关键信息用户 ID、时间、偏好主动提取到结构化存储中。4.5 第五步工作流编排与异常兜底生产级 Agent 建议采用“流程编排 节点内自主调用”的混合模式。即整体任务拆成固定阶段每个阶段内模型可以自由调用工具但阶段切换由程序控制。这样既保留模型灵活性又避免失控。异常兜底至少要覆盖工具调用超时重试限制重试次数。模型输出的 JSON 解析失败时的降级策略。连续失败时主动终止任务并通知人工。用户打断时如何终止循环。5. 最小实例使用 Python 构建一个带工具调用的单 Agent 应用理解了原理后我们先用 Python 手写一个最小 Agent完整跑通“用户指令 → 模型决策 → 工具执行 → 结果回传 → 最终回答”的循环。不依赖任何 Agent 框架只用requests库这样你能清晰看到 Agent 运行的底层逻辑。5.1 工具函数定义先定义两个模拟工具一个查天气一个执行模拟数据库查询。真实项目中工具函数内部可以是 HTTP 调用、数据库查询或任何业务逻辑。# 文件路径agent_demo/tools.py import json import datetime def get_weather(city: str) - str: 模拟获取城市天气 data { city: city, weather: 晴, temperature: 24, humidity: 40, update_time: datetime.datetime.now().isoformat() } return json.dumps(data, ensure_asciiFalse) def query_daily_sales(date: str) - str: 模拟查询日销售额 if date 2026-01-15: data {date: date, total_orders: 3200, sales_amount: 89000.50} else: data {date: date, total_orders: 0, sales_amount: 0.0} return json.dumps(data, ensure_asciiFalse) TOOL_FUNCTIONS { get_weather: get_weather, query_daily_sales: query_daily_sales, } TOOL_SCHEMAS [ { type: function, function: { name: get_weather, description: 获取一个城市的实时天气信息, parameters: { type: object, properties: { city: {type: string, description: 城市名称例如北京} }, required: [city] } } }, { type: function, function: { name: query_daily_sales, description: 查询指定日期的日销售额数据, parameters: { type: object, properties: { date: {type: string, description: 日期格式为 YYYY-MM-DD} }, required: [date] } } } ]关键点TOOL_SCHEMAS是模型了解工具的入口Schema 写得好不好直接决定模型能不能正确传参。工具函数内部做了数据序列化把结构化结果返回给模型。5.2 Agent 主循环代码接下来实现 Agent 的核心循环逻辑调用模型、判断是否触发工具调用、执行工具、回传结果、继续循环或结束。# 文件路径agent_demo/agent.py import json import os import requests from tools import TOOL_FUNCTIONS, TOOL_SCHEMAS API_BASE os.getenv(LLM_API_BASE, https://your-llm-endpoint.example.com/v1) API_KEY os.getenv(LLM_API_KEY, your-api-key) MODEL os.getenv(LLM_MODEL, your-model-name) def call_llm(messages): resp requests.post( f{API_BASE}/chat/completions, headers{Authorization: fBearer {API_KEY}, Content-Type: application/json}, json{ model: MODEL, messages: messages, tools: TOOL_SCHEMAS, tool_choice: auto, temperature: 0.2 }, timeout60 ) resp.raise_for_status() return resp.json()[choices][0][message] def run_agent(user_input: str, max_steps: int 5): messages [{role: user, content: user_input}] step 0 while step max_steps: print(f\n Step {step 1} ) message call_llm(messages) messages.append(message) if message.get(tool_calls): for tool_call in message[tool_calls]: fn_name tool_call[function][name] fn_args json.loads(tool_call[function][arguments]) print(f调用工具: {fn_name}, 参数: {fn_args}) result TOOL_FUNCTIONS[fn_name](**fn_args) print(f工具结果: {result}) messages.append({ role: tool, tool_call_id: tool_call[id], content: result }) step 1 else: print(f\n最终回答: {message[content]}) break if __name__ __main__: run_agent(北京今天天气怎么样顺便看下 2026-01-15 的销售额)这段代码的核心逻辑是把用户输入放入messages。请求 LLM并携带工具 Schema模型收到后会根据任务决定是 “直接回答” 还是 “要求调用工具”。如果返回中有tool_calls程序解析工具名和参数执行本地工具函数把结果作为role: tool的消息追加到上下文。带着工具结果再次请求模型模型根据结果生成下一步决策或最终回答。设置了max_steps上限避免模型陷入无限循环。5.3 运行与验证方式# 设置环境变量 export LLM_API_BASEhttps://your-llm-endpoint.example.com/v1 export LLM_API_KEYyour-api-key export LLM_MODELyour-model-name # 运行 Agent python agent.py预期输出分两个阶段。第一次循环输出工具调用信息第二次循环输出最终回答回答内容包含工具返回的天气数据和销售数据。如果运行失败优先检查API 地址和 Key 是否正确。模型是否支持 Function Calling / Tools。工具 Schema 是否符合模型服务要求的格式。这个最小实现有意识省略了错误处理、重试、并发控制等工程细节但它们正是企业级项目和 Demo 的差距所在。6. 进阶实例Java 技术栈与 Spring AI 企业级集成很多读者的实际开发环境是 Java 体系。如果希望在 Spring Boot 项目里接入 Agent建议关注 Spring AI 项目。Spring AI 是 Spring 生态为 AI 应用提供的集成层支持聊天、结构化输出、工具调用并提供了与 Spring 配置体系无缝对接的能力。下面是基于 Spring AI 的 Agent 工具调用完整示例。6.1 Maven 依赖!-- 文件路径pom.xml -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-tool-calling/artifactId /dependency具体版本请参考 Spring AI 官方 Release Notes不同小版本的 API 略有差异但整体设计一致。6.2 application.yml 配置文件# 文件路径src/main/resources/application.yml spring: application: name: agent-demo ai: openai: base-url: ${LLM_API_BASE:https://your-llm-endpoint.example.com/v1} api-key: ${LLM_API_KEY:} chat: options: model: ${LLM_MODEL:your-model-name} temperature: 0.2使用${}占位符引用环境变量是个好习惯避免 API Key 出现在仓库里。生产环境甚至可以使用配置中心动态管理这些配置。6.3 声明 Agent 可用的工具Spring AI 支持用 Bean 方式声明工具类框架会在运行时把工具 Schema 自动关联到模型调用上。// 文件路径src/main/java/com/example/agentdemo/tool/OrderTools.java package com.example.agentdemo.tool; import com.example.agentdemo.dto.SalesData; import org.springframework.stereotype.Component; import java.util.Map; import java.util.function.Function; Component public class OrderTools { /** * 查询日销售额。 * Spring AI 会基于方法名、描述和参数自动生成工具 Schema。 */ public record QueryDailySalesRequest(String date) {} public FunctionQueryDailySalesRequest, String queryDailySales() { return request - { if (2026-01-15.equals(request.date())) { SalesData data new SalesData(request.date(), 3200, 89000.50); return data.toString(); } return new SalesData(request.date(), 0, 0.0).toString(); }; } }这段代码的关键是FunctionRequest, Response的注册方式。Spring AI 会把QueryDailySalesRequest的结构自动解析为工具参数 Schema。工具类只负责业务逻辑不关心 HTTP 层。6.4 Agent 服务层实现// 文件路径src/main/java/com/example/agentdemo/service/AgentDemoService.java package com.example.agentdemo.service; import org.springframework.ai.chat.model.ChatModel; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.tool.ToolCallback; import org.springframework.ai.chat.prompt.SystemPromptTemplate; import org.springframework.stereotype.Service; import java.util.List; import java.util.Map; Service public class AgentDemoService { private final ChatModel chatModel; private final ListToolCallback toolCallbacks; public AgentDemoService(ChatModel chatModel, ListToolCallback toolCallbacks) { this.chatModel chatModel; this.toolCallbacks toolCallbacks; } public String askAgent(String userQuestion) { SystemPromptTemplate systemPrompt new SystemPromptTemplate( 你是一个企业服务助手。请根据用户的问题选择合适的工具获取数据后回答。 ); Prompt prompt new Prompt( List.of(systemPrompt.createMessage(Map.of()), new UserMessage(userQuestion)), org.springframework.ai.chat.prompt.PromptOptions.builder() .toolCallbacks(toolCallbacks) .build() ); ChatResponse response chatModel.call(prompt); return response.getResult().getOutput().getText(); } }ChatModel是 Spring AI 的核心抽象toolCallbacks会自动注入所有实现 ToolCallback 接口的 Bean。服务层不需要手动判断该调哪个工具框架内部完成了工具选择的循环。6.5 对外提供 HTTP 接口// 文件路径src/main/java/com/example/agentdemo/controller/AgentController.java package com.example.agentdemo.controller; import com.example.agentdemo.service.AgentDemoService; import org.springframework.web.bind.annotation.*; import java.util.Map; RestController RequestMapping(/api/agent) public class AgentController { private final AgentDemoService agentDemoService; public AgentController(AgentDemoService agentDemoService) { this.agentDemoService agentDemoService; } PostMapping(/chat) public MapString, String chat(RequestBody MapString, String request) { String question request.get(question); String answer agentDemoService.askAgent(question); return Map.of(answer, answer); } }启动 Spring Boot 应用后发送 POST 请求即可测试curl -X POST http://localhost:8080/api/agent/chat \ -H Content-Type: application/json \ -d {question: 帮我查下 2026-01-15 的销售额}从工程角度看Spring AI 的价值在于配置管理、工具注册、模型调用被纳入了 Spring 的统一生命周期链路追踪、配置中心、限流熔断等企业级能力可以直接复用这是很多团队选它的真实原因。7. 运行结果与效果验证能跑通只是起点真正的挑战是如何证明 Agent “可用”。在企业里“演示成功一次”不叫成功“一百次调用有九十八次正确、失败有明确原因”才叫可用。7.1 功能验证的维度维度验证点通过标准功能正确性工具是否被正确调用、参数是否正确任务目标达成率不低于预设阈值稳定性连续多次运行是否结果一致重复运行结果差异在可接受范围内容错性模型返回格式异常、工具执行失败能给出降级响应不崩溃安全性是否尝试执行越权操作或注入指令高风险指令被拦截或提示确认性能单次任务耗时、token 消耗在预算范围内完成响应7.2 建议建立评测集不要靠“感觉”来判断 Agent 好坏。建议为你的 Agent 建立一个小型评测集包含至少 30 到 50 条典型问题覆盖常规任务用户用正常表达发起的任务。边界输入参数缺失、表达模糊、用户情绪化表达。敏感场景试图让 Agent 执行删除、转账、绕过权限的操作。失败场景工具不可用、服务超时、数据不存在。用自动化脚本每次改动后跑一遍评测集记录通过率。7.3 日志与追踪生产级 Agent 一定要做全链路日志。每一次 LLM 调用、工具调用、上下文截断、错误重试都应该有日志最好能关联一个 task_id。建议记录信息包括用户原始输入。模型返回的每一次 tool_calls。每个工具的执行耗时和结果摘要。上下文截断时丢弃了哪些消息。连续失败的步骤和终止原因。有了这些日志你才有能力定位“为什么这个 Agent 今天表现异常”。8. 常见问题与排查思路在实际开发中Agent 出问题的方式总是比预想的多。下表整理了生产环境中最常见的问题按出现频率排列。问题现象可能原因排查方式解决方案模型不调用工具直接回答工具 Schema 描述不清晰或模型不支持 tools 参数检查模型是否支持工具调用检查 Schema 中 description 是否精准优化工具描述必要时显式要求模型“必须使用工具”模型传错参数参数 Schema 设计不合理或缺少枚举约束查看请求日志中的 tool_calls 参数增加参数校验、枚举定义和默认值结果不稳定temperature 过高或没有系统提示检查参数配置用多个测试用例反复调用调低 temperature增强 system prompt循环调用停不下来缺少步骤上限或终止条件查看日志中连续工具调用次数设置 max_steps增加结果校验和终止逻辑上下文很快满了历史消息无清理策略检查每次请求的 token 消耗实现滑动窗口或摘要压缩策略工具执行超时下游服务慢或网络问题查看工具调用耗时指标设置超时与重试策略异步化耗时操作用户提示注入系统提示被用户输入覆盖检查 Prompt 中是否有越权指令增加安全提示词、敏感操作二次确认、输出校验API Key 泄露配置写死在代码或仓库扫描仓库和配置中心改用环境变量或密钥管理服务定期轮换 Key并发请求互相干扰共享了可变状态或同一个上下文对象检查内存态字段上下文改为每次请求独立创建使用无状态服务线上表现与测试不一致测试数据与真实数据分布差异大对比线上日志与评测集持续扩充评测集做灰度发布排查 Agent 问题有一个总原则先看日志再复现最后改配置。不要每次都从头跑一遍代码而是先确认模型收到了什么、返回了什么、工具执行了什么。9. 最佳实践与生产落地建议从开发到上线Agent 项目的工程化要求与传统后端服务相比有不少特殊之处。以下是几条经过实践检验的落地建议。9.1 先小后大先窄后宽第一个 Agent 项目不要做全功能助手。建议圈定一个高频、边界清晰、工具可控的场景比如“销售数据查询 日报生成”。跑通一个场景后再横向扩展。场景边界越窄评估和排错越容易。9.2 安全边界设计Agent 能调用工具本身就意味着它具备“执行能力”安全设计要前置最小权限原则Agent 工具访问数据库和接口的权限只放宽到最小必需范围。敏感操作二次确认任何删除、修改、转账、外发操作Agent 只能“发起”不能“直接执行”必须经过用户确认。输入输出校验对模型意图做校验时不能只靠 Prompt关键节点要有规则引擎确认。部署环境控制生产环境与测试环境的 API Key、模型配置彻底隔离。9.3 可观测性建设建议把 Agent 的调用链纳入公司已有的监控体系。核心指标包括工具调用成功率。任务整体完成率。平均耗时和 token 成本。用户中断和错误终止率。没有这些指标你无法判断“升级模型后到底是变好了还是变差了”。9.4 灰度发布策略Agent 上线不建议全量切换。更稳妥的方式是流量灰度先让 Agent 承接 5% 的流量记录日志和用户反馈同时保留人工处理通道。观察指标没有恶化再逐步放量。如果模型服务升级或工具逻辑调整同样采用灰度策略。对模型类改动尤其要谨慎因为模型版本更换带来的行为变化往往不可控。9.5 成本控制Agent 多轮工具调用比普通聊天消耗的 token 多很多。建议做一层简单的 token 预算机制在任务启动时评估预计消耗超出预算直接终止并转人工。对高频工具调用做结果缓存还可以显著节省成本。10. 总结与后续学习路径这篇文章没有停留在“什么是 AI Agent”的概念层面而是把 Agent 开发从原理到落地的完整链路拆了一遍包括Agent 与普通 ChatBot 的本质区别。模型、工具、记忆、规划、多 Agent 协作五个核心概念。用 Python 手写了一个最小 Agent理解 Function Calling 的底层循环。用 Spring AI 展示了 Java 企业级技术栈的接入方式。整理了验证指标、排查方法和生产落地建议。下一步的实践建议很直接找一个小场景定义两个工具实现一个最小 Agent然后跑 20 条测试用例看通过率。先把这条路走通再去研究向量数据库、多 Agent 编排、模型微调这些进阶方向。目前在 Agent 开发领域工程实践的重要性已经超过了模型本身。谁会封装工具、谁懂容错设计、谁能把模型能力稳稳交到业务方手里谁就能真正把 AI Agent 变成生产力。建议把文中 Python 最小 Demo 先跑通再对照 Spring AI 的代码看一遍最后做一个小场景的评测集。过程中遇到问题建议优先查日志和模型返回的原始响应多数问题都藏在这两样东西里。
AI Agent开发实战：从核心原理到企业级工程化落地
这两年问 AI Agent 开发的人明显变多了。很多人以为 Agent 开发就是“写个 Prompt调一下大模型 API”等真正动手做才发现Demo 能跑通和生产可用完全是两回事。本文想给出一条从零基础到企业级项目实战的完整路径。文章会从核心概念讲起然后拆解 Agent 开发的关键环节用 Python 和 Java 两套技术栈做最小可运行示例最后落点到生产环境最容易踩的坑和工程化取舍。如果你正准备把 AI Agent 引入实际项目或者正在面试 Agent 相关岗位这篇文章可以帮你少走很多弯路。先说一个核心判断AI Agent 开发的门槛不在大模型 API 调用而在工程化能力。模型能力是底座但真正决定项目成败的是工具设计、状态管理、容错机制、评估方式和安全边界。2026 年的 Agent 开发已经过了“跑通 Demo 就算会”的阶段行业需要的是能交付、能维护、能评估的工程化能力。1. AI Agent 开发到底在解决什么问题先看传统软件开发的模式输入 → 固定逻辑 → 输出。这种模式下业务逻辑是预先写死的。用户提交订单就调订单接口用户查询就查数据库。问题在于很多企业场景并不是固定流程而是“需要一定推理和决策”的复杂任务。比如用户问“帮我对比这几家云厂商的价格然后给出一份选型建议”运营说“把上周的销售数据复盘一下找出下滑原因并生成日报”研发说“这个日志异常帮我定位一下可能的原因并给出排查命令”这些任务有几个共性输入是非结构化的执行路径不是固定的需要外部信息和内部系统协同。如果都靠人工处理效率极低如果靠传统代码写死又覆盖不了变化无穷的用户表达。AI Agent 的核心价值在于让大模型在“理解任务”的基础上通过工具调用、记忆管理和多轮规划替代人去完成一个相对复杂的业务动作。它解决的真正问题是“非固定流程任务的自动化”而不仅仅是“对话”。从这个角度理解Agent 和普通 ChatBot 的界限就很清晰了维度普通 ChatBotAI Agent任务范围单轮问答多轮复杂任务执行能力生成文字调用工具、查库、写文件、发请求状态管理无状态有上下文、有记忆、有任务状态决策方式固定回复自主规划、循环执行2026 年的分水岭在于行业已经不再满足于“能聊”而是要求 Agent“能干活”并且“干活的过程可追踪、结果可评估、出错可回滚”。2. AI Agent 核心概念模型、工具、记忆、规划与多 Agent 协作理解 Agent 开发先要把几个核心概念拆开。很多新手混淆概念导致架构设计一上来就是错的。2.1 大模型底座 LLM大模型是 Agent 的“大脑”负责理解用户的自然语言输入、推理任务拆解、决定调用哪个工具。你可以把 LLM 视为一个“推理引擎”它的输入是带历史消息的 Prompt输出是文本或者结构化的工具调用指令。在 Agent 架构里LLM 不是被直接使用的“最终答案生成器”而是“决策中枢”。这个定位变化很重要。2.2 Function Calling 工具调用这是 Agent 落地最关键的机制。大模型本身不能访问外部世界需要靠工具Functions拿到信息或者执行动作。工具调用机制可以分解为三步开发者在接口中向模型声明有哪些工具以及每个工具的入参 Schema。模型根据用户任务判断“该调用哪个工具”返回一个结构化的 tool_calls 请求。开发者的程序执行对应工具把结果回传给模型模型再决定下一步动作。工具设计直接决定了 Agent 的能力边界。一个只有“查天气”工具的 Agent 做不了业务一个有“查询订单”“余额变更”“用户信息”等丰富工具集的 Agent 才能服务真实业务。2.3 记忆 MemoryAgent 的记忆分为短期记忆和长期记忆。记忆类型存储内容生命周期典型实现短期记忆当前任务的上下文、工具调用结果一次会话对话消息列表长期记忆用户偏好、历史事实、领域知识跨会话向量数据库 知识库短期记忆主要靠把历史消息拼进 Prompt 实现简单但受上下文窗口限制。长期记忆则需要引入向量数据库、向量检索和知识切片等技术这也是 RAG检索增强生成在 Agent 架构中扮演记忆系统重要部分的原因。2.4 规划 Planning规划能力是 Agent 与普通 LLM 应用最大的区别之一。任务复杂时Agent 需要把大任务拆解成多个子步骤并决定执行顺序。常见实现方式有ReAct 模式推理 → 行动 → 观察 → 再推理循环推进。思维链 CoT让模型一步步推理提升复杂问题正确率。Plan-and-Execute先整体规划再逐步执行每步执行结果反馈到规划器。树状规划 Tree-of-Thought同时探索多个候选路径做权衡取舍。生产环境中纯靠模型自由规划的稳定性并不够所以越来越多的架构采用“固定工作流 节点内模型自主决策”的混合编排方式。2.5 多 Agent 协作 Multi-Agent单个 Agent 处理复杂任务容易上下文爆炸、职责混乱。多 Agent 架构是把不同职责拆成多个 Agent比如任务规划 Agent、工具执行 Agent、质检 Agent、兜底 Agent由协调器 Agent 进行调度。多 Agent 的优势是职责分离、便于维护和权限隔离劣势是调用次数增加、成本上升、排错复杂度提高。对于大部分业务场景单 Agent 高质量工具集才是第一选择多 Agent 是优化手段不是目的。3. 环境准备与技术选型手写一个 Agent 其实不需要很重的框架。从学习路径上看建议先“手写理解原理”再“用框架提升效率”。3.1 基础环境要求开发 Agent 建议准备以下环境Python 3.10 或 JDK 17取决于你选择的语言。一个 LLM API Key优先选择兼容 OpenAI 风格的接口服务。网络能正常访问模型服务接口。本地开发工具VS Code 或 IntelliJ IDEA建议安装 HTTP 调试插件。如果需要做记忆系统可以准备 Docker 用来跑向量数据库如 Milvus、Chroma 或 PostgreSQL pgvector。版本细节以实际项目使用为准本文重在演示通用思路。3.2 技术栈选型技术栈适合场景代表框架学习成本Python原型验证、数据分析类 Agent、算法研究LangChain、LlamaIndex、自实现较低Java/Spring企业级应用、与现有微服务体系集成Spring AI、LangChain4j中Node.js前端团队全栈开发、轻量服务LangChain.js中选型原则是跟着团队现有的工程体系走不要为了 Agent 引入一套新语言栈。Python 适合做快速验证和算法侧工作但很多企业的核心业务跑在 Java 体系里这时候 Spring AI 是更务实的接入方案。3.3 模型 API 的通用调用方式目前主流 LLM 服务大多兼容 OpenAI 的 Chat Completions 接口风格。即使你用的是国内模型、开源模型或中间层网关也基本都能通过统一 OpenAI 兼容端点接入。这意味着Agent 代码与具体模型服务解耦换模型只需要改 endpoint 和 api_key。下面是一段配置文件示例# 文件路径config.properties llm.api-basehttps://your-llm-endpoint.example.com/v1 llm.api-key${LLM_API_KEY} llm.modelyour-model-name llm.temperature0.2用环境变量注入 API Key不写死在代码里这是生产级项目的基本要求。4. 核心流程拆解从零到一的五个关键节点很多入门教程一上来就让读者复制代码结果代码能跑但换个任务就不会做了。原因是缺少了“从任务到 Agent 架构”的设计过程。这里梳理五个关键环节。4.1 第一步任务定义与边界划分做 Agent 前第一件事不是写代码而是明确任务边界。建议用一句话说清楚Agent 的输入是什么输出是什么哪些事它绝对不做做不了时怎么办。举个例子输入用户的文字问题或指令。输出结构化的分析报告、工具执行结果。不做不处理包含银行账号的敏感操作这类请求直接转人工。不做不执行任何没有二次确认的删除类操作。失败兜底连续两次工具调用失败后停止重试并向用户展示错误信息。没有边界定义的 Agent上线后就是一台不可控的“自动翻车机器”。4.2 第二步模型选型与参数配置模型选择直接影响 Agent 的工具调用准确率。需要考虑三个因素上下文窗口任务是否需要处理超长文本。工具调用能力模型是否稳定输出符合 Schema 的工具参数。成本与延迟企业场景要考虑单次任务平均消耗多少 token、响应多快。参数配置上temperature建议调低一般在 0.1 到 0.3 之间。工具调用场景需要的是确定性不是创造性。max_tokens要设置上限避免模型输出过长文本拖慢循环。4.3 第三步工具设计工具是 Agent 能力的边界也是工程质量最集中的体现。设计工具时注意三点单一职责每个工具只做一件事。不要设计一个“全能处理”的工具否则模型非常容易传错参数。参数描述具体工具的描述和参数 Schema 要写清楚让模型能准确理解工具该用于什么场景。容错返回工具执行失败时返回给模型的消息要包含错误原因而不是只抛异常。4.4 第四步记忆与上下文管理上下文管理是生产环境必踩的坑。模型上下文窗口有限不可能把全部历史都拼进 Prompt。常见策略滑动窗口只保留最近 N 轮对话。摘要压缩每多轮对话后用模型生成一次历史摘要。关键信息抽取把用户关键信息用户 ID、时间、偏好主动提取到结构化存储中。4.5 第五步工作流编排与异常兜底生产级 Agent 建议采用“流程编排 节点内自主调用”的混合模式。即整体任务拆成固定阶段每个阶段内模型可以自由调用工具但阶段切换由程序控制。这样既保留模型灵活性又避免失控。异常兜底至少要覆盖工具调用超时重试限制重试次数。模型输出的 JSON 解析失败时的降级策略。连续失败时主动终止任务并通知人工。用户打断时如何终止循环。5. 最小实例使用 Python 构建一个带工具调用的单 Agent 应用理解了原理后我们先用 Python 手写一个最小 Agent完整跑通“用户指令 → 模型决策 → 工具执行 → 结果回传 → 最终回答”的循环。不依赖任何 Agent 框架只用requests库这样你能清晰看到 Agent 运行的底层逻辑。5.1 工具函数定义先定义两个模拟工具一个查天气一个执行模拟数据库查询。真实项目中工具函数内部可以是 HTTP 调用、数据库查询或任何业务逻辑。# 文件路径agent_demo/tools.py import json import datetime def get_weather(city: str) - str: 模拟获取城市天气 data { city: city, weather: 晴, temperature: 24, humidity: 40, update_time: datetime.datetime.now().isoformat() } return json.dumps(data, ensure_asciiFalse) def query_daily_sales(date: str) - str: 模拟查询日销售额 if date 2026-01-15: data {date: date, total_orders: 3200, sales_amount: 89000.50} else: data {date: date, total_orders: 0, sales_amount: 0.0} return json.dumps(data, ensure_asciiFalse) TOOL_FUNCTIONS { get_weather: get_weather, query_daily_sales: query_daily_sales, } TOOL_SCHEMAS [ { type: function, function: { name: get_weather, description: 获取一个城市的实时天气信息, parameters: { type: object, properties: { city: {type: string, description: 城市名称例如北京} }, required: [city] } } }, { type: function, function: { name: query_daily_sales, description: 查询指定日期的日销售额数据, parameters: { type: object, properties: { date: {type: string, description: 日期格式为 YYYY-MM-DD} }, required: [date] } } } ]关键点TOOL_SCHEMAS是模型了解工具的入口Schema 写得好不好直接决定模型能不能正确传参。工具函数内部做了数据序列化把结构化结果返回给模型。5.2 Agent 主循环代码接下来实现 Agent 的核心循环逻辑调用模型、判断是否触发工具调用、执行工具、回传结果、继续循环或结束。# 文件路径agent_demo/agent.py import json import os import requests from tools import TOOL_FUNCTIONS, TOOL_SCHEMAS API_BASE os.getenv(LLM_API_BASE, https://your-llm-endpoint.example.com/v1) API_KEY os.getenv(LLM_API_KEY, your-api-key) MODEL os.getenv(LLM_MODEL, your-model-name) def call_llm(messages): resp requests.post( f{API_BASE}/chat/completions, headers{Authorization: fBearer {API_KEY}, Content-Type: application/json}, json{ model: MODEL, messages: messages, tools: TOOL_SCHEMAS, tool_choice: auto, temperature: 0.2 }, timeout60 ) resp.raise_for_status() return resp.json()[choices][0][message] def run_agent(user_input: str, max_steps: int 5): messages [{role: user, content: user_input}] step 0 while step max_steps: print(f\n Step {step 1} ) message call_llm(messages) messages.append(message) if message.get(tool_calls): for tool_call in message[tool_calls]: fn_name tool_call[function][name] fn_args json.loads(tool_call[function][arguments]) print(f调用工具: {fn_name}, 参数: {fn_args}) result TOOL_FUNCTIONS[fn_name](**fn_args) print(f工具结果: {result}) messages.append({ role: tool, tool_call_id: tool_call[id], content: result }) step 1 else: print(f\n最终回答: {message[content]}) break if __name__ __main__: run_agent(北京今天天气怎么样顺便看下 2026-01-15 的销售额)这段代码的核心逻辑是把用户输入放入messages。请求 LLM并携带工具 Schema模型收到后会根据任务决定是 “直接回答” 还是 “要求调用工具”。如果返回中有tool_calls程序解析工具名和参数执行本地工具函数把结果作为role: tool的消息追加到上下文。带着工具结果再次请求模型模型根据结果生成下一步决策或最终回答。设置了max_steps上限避免模型陷入无限循环。5.3 运行与验证方式# 设置环境变量 export LLM_API_BASEhttps://your-llm-endpoint.example.com/v1 export LLM_API_KEYyour-api-key export LLM_MODELyour-model-name # 运行 Agent python agent.py预期输出分两个阶段。第一次循环输出工具调用信息第二次循环输出最终回答回答内容包含工具返回的天气数据和销售数据。如果运行失败优先检查API 地址和 Key 是否正确。模型是否支持 Function Calling / Tools。工具 Schema 是否符合模型服务要求的格式。这个最小实现有意识省略了错误处理、重试、并发控制等工程细节但它们正是企业级项目和 Demo 的差距所在。6. 进阶实例Java 技术栈与 Spring AI 企业级集成很多读者的实际开发环境是 Java 体系。如果希望在 Spring Boot 项目里接入 Agent建议关注 Spring AI 项目。Spring AI 是 Spring 生态为 AI 应用提供的集成层支持聊天、结构化输出、工具调用并提供了与 Spring 配置体系无缝对接的能力。下面是基于 Spring AI 的 Agent 工具调用完整示例。6.1 Maven 依赖!-- 文件路径pom.xml -- dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-model-openai/artifactId /dependency dependency groupIdorg.springframework.ai/groupId artifactIdspring-ai-starter-tool-calling/artifactId /dependency具体版本请参考 Spring AI 官方 Release Notes不同小版本的 API 略有差异但整体设计一致。6.2 application.yml 配置文件# 文件路径src/main/resources/application.yml spring: application: name: agent-demo ai: openai: base-url: ${LLM_API_BASE:https://your-llm-endpoint.example.com/v1} api-key: ${LLM_API_KEY:} chat: options: model: ${LLM_MODEL:your-model-name} temperature: 0.2使用${}占位符引用环境变量是个好习惯避免 API Key 出现在仓库里。生产环境甚至可以使用配置中心动态管理这些配置。6.3 声明 Agent 可用的工具Spring AI 支持用 Bean 方式声明工具类框架会在运行时把工具 Schema 自动关联到模型调用上。// 文件路径src/main/java/com/example/agentdemo/tool/OrderTools.java package com.example.agentdemo.tool; import com.example.agentdemo.dto.SalesData; import org.springframework.stereotype.Component; import java.util.Map; import java.util.function.Function; Component public class OrderTools { /** * 查询日销售额。 * Spring AI 会基于方法名、描述和参数自动生成工具 Schema。 */ public record QueryDailySalesRequest(String date) {} public FunctionQueryDailySalesRequest, String queryDailySales() { return request - { if (2026-01-15.equals(request.date())) { SalesData data new SalesData(request.date(), 3200, 89000.50); return data.toString(); } return new SalesData(request.date(), 0, 0.0).toString(); }; } }这段代码的关键是FunctionRequest, Response的注册方式。Spring AI 会把QueryDailySalesRequest的结构自动解析为工具参数 Schema。工具类只负责业务逻辑不关心 HTTP 层。6.4 Agent 服务层实现// 文件路径src/main/java/com/example/agentdemo/service/AgentDemoService.java package com.example.agentdemo.service; import org.springframework.ai.chat.model.ChatModel; import org.springframework.ai.chat.messages.UserMessage; import org.springframework.ai.chat.prompt.Prompt; import org.springframework.ai.chat.model.ChatResponse; import org.springframework.ai.tool.ToolCallback; import org.springframework.ai.chat.prompt.SystemPromptTemplate; import org.springframework.stereotype.Service; import java.util.List; import java.util.Map; Service public class AgentDemoService { private final ChatModel chatModel; private final ListToolCallback toolCallbacks; public AgentDemoService(ChatModel chatModel, ListToolCallback toolCallbacks) { this.chatModel chatModel; this.toolCallbacks toolCallbacks; } public String askAgent(String userQuestion) { SystemPromptTemplate systemPrompt new SystemPromptTemplate( 你是一个企业服务助手。请根据用户的问题选择合适的工具获取数据后回答。 ); Prompt prompt new Prompt( List.of(systemPrompt.createMessage(Map.of()), new UserMessage(userQuestion)), org.springframework.ai.chat.prompt.PromptOptions.builder() .toolCallbacks(toolCallbacks) .build() ); ChatResponse response chatModel.call(prompt); return response.getResult().getOutput().getText(); } }ChatModel是 Spring AI 的核心抽象toolCallbacks会自动注入所有实现 ToolCallback 接口的 Bean。服务层不需要手动判断该调哪个工具框架内部完成了工具选择的循环。6.5 对外提供 HTTP 接口// 文件路径src/main/java/com/example/agentdemo/controller/AgentController.java package com.example.agentdemo.controller; import com.example.agentdemo.service.AgentDemoService; import org.springframework.web.bind.annotation.*; import java.util.Map; RestController RequestMapping(/api/agent) public class AgentController { private final AgentDemoService agentDemoService; public AgentController(AgentDemoService agentDemoService) { this.agentDemoService agentDemoService; } PostMapping(/chat) public MapString, String chat(RequestBody MapString, String request) { String question request.get(question); String answer agentDemoService.askAgent(question); return Map.of(answer, answer); } }启动 Spring Boot 应用后发送 POST 请求即可测试curl -X POST http://localhost:8080/api/agent/chat \ -H Content-Type: application/json \ -d {question: 帮我查下 2026-01-15 的销售额}从工程角度看Spring AI 的价值在于配置管理、工具注册、模型调用被纳入了 Spring 的统一生命周期链路追踪、配置中心、限流熔断等企业级能力可以直接复用这是很多团队选它的真实原因。7. 运行结果与效果验证能跑通只是起点真正的挑战是如何证明 Agent “可用”。在企业里“演示成功一次”不叫成功“一百次调用有九十八次正确、失败有明确原因”才叫可用。7.1 功能验证的维度维度验证点通过标准功能正确性工具是否被正确调用、参数是否正确任务目标达成率不低于预设阈值稳定性连续多次运行是否结果一致重复运行结果差异在可接受范围内容错性模型返回格式异常、工具执行失败能给出降级响应不崩溃安全性是否尝试执行越权操作或注入指令高风险指令被拦截或提示确认性能单次任务耗时、token 消耗在预算范围内完成响应7.2 建议建立评测集不要靠“感觉”来判断 Agent 好坏。建议为你的 Agent 建立一个小型评测集包含至少 30 到 50 条典型问题覆盖常规任务用户用正常表达发起的任务。边界输入参数缺失、表达模糊、用户情绪化表达。敏感场景试图让 Agent 执行删除、转账、绕过权限的操作。失败场景工具不可用、服务超时、数据不存在。用自动化脚本每次改动后跑一遍评测集记录通过率。7.3 日志与追踪生产级 Agent 一定要做全链路日志。每一次 LLM 调用、工具调用、上下文截断、错误重试都应该有日志最好能关联一个 task_id。建议记录信息包括用户原始输入。模型返回的每一次 tool_calls。每个工具的执行耗时和结果摘要。上下文截断时丢弃了哪些消息。连续失败的步骤和终止原因。有了这些日志你才有能力定位“为什么这个 Agent 今天表现异常”。8. 常见问题与排查思路在实际开发中Agent 出问题的方式总是比预想的多。下表整理了生产环境中最常见的问题按出现频率排列。问题现象可能原因排查方式解决方案模型不调用工具直接回答工具 Schema 描述不清晰或模型不支持 tools 参数检查模型是否支持工具调用检查 Schema 中 description 是否精准优化工具描述必要时显式要求模型“必须使用工具”模型传错参数参数 Schema 设计不合理或缺少枚举约束查看请求日志中的 tool_calls 参数增加参数校验、枚举定义和默认值结果不稳定temperature 过高或没有系统提示检查参数配置用多个测试用例反复调用调低 temperature增强 system prompt循环调用停不下来缺少步骤上限或终止条件查看日志中连续工具调用次数设置 max_steps增加结果校验和终止逻辑上下文很快满了历史消息无清理策略检查每次请求的 token 消耗实现滑动窗口或摘要压缩策略工具执行超时下游服务慢或网络问题查看工具调用耗时指标设置超时与重试策略异步化耗时操作用户提示注入系统提示被用户输入覆盖检查 Prompt 中是否有越权指令增加安全提示词、敏感操作二次确认、输出校验API Key 泄露配置写死在代码或仓库扫描仓库和配置中心改用环境变量或密钥管理服务定期轮换 Key并发请求互相干扰共享了可变状态或同一个上下文对象检查内存态字段上下文改为每次请求独立创建使用无状态服务线上表现与测试不一致测试数据与真实数据分布差异大对比线上日志与评测集持续扩充评测集做灰度发布排查 Agent 问题有一个总原则先看日志再复现最后改配置。不要每次都从头跑一遍代码而是先确认模型收到了什么、返回了什么、工具执行了什么。9. 最佳实践与生产落地建议从开发到上线Agent 项目的工程化要求与传统后端服务相比有不少特殊之处。以下是几条经过实践检验的落地建议。9.1 先小后大先窄后宽第一个 Agent 项目不要做全功能助手。建议圈定一个高频、边界清晰、工具可控的场景比如“销售数据查询 日报生成”。跑通一个场景后再横向扩展。场景边界越窄评估和排错越容易。9.2 安全边界设计Agent 能调用工具本身就意味着它具备“执行能力”安全设计要前置最小权限原则Agent 工具访问数据库和接口的权限只放宽到最小必需范围。敏感操作二次确认任何删除、修改、转账、外发操作Agent 只能“发起”不能“直接执行”必须经过用户确认。输入输出校验对模型意图做校验时不能只靠 Prompt关键节点要有规则引擎确认。部署环境控制生产环境与测试环境的 API Key、模型配置彻底隔离。9.3 可观测性建设建议把 Agent 的调用链纳入公司已有的监控体系。核心指标包括工具调用成功率。任务整体完成率。平均耗时和 token 成本。用户中断和错误终止率。没有这些指标你无法判断“升级模型后到底是变好了还是变差了”。9.4 灰度发布策略Agent 上线不建议全量切换。更稳妥的方式是流量灰度先让 Agent 承接 5% 的流量记录日志和用户反馈同时保留人工处理通道。观察指标没有恶化再逐步放量。如果模型服务升级或工具逻辑调整同样采用灰度策略。对模型类改动尤其要谨慎因为模型版本更换带来的行为变化往往不可控。9.5 成本控制Agent 多轮工具调用比普通聊天消耗的 token 多很多。建议做一层简单的 token 预算机制在任务启动时评估预计消耗超出预算直接终止并转人工。对高频工具调用做结果缓存还可以显著节省成本。10. 总结与后续学习路径这篇文章没有停留在“什么是 AI Agent”的概念层面而是把 Agent 开发从原理到落地的完整链路拆了一遍包括Agent 与普通 ChatBot 的本质区别。模型、工具、记忆、规划、多 Agent 协作五个核心概念。用 Python 手写了一个最小 Agent理解 Function Calling 的底层循环。用 Spring AI 展示了 Java 企业级技术栈的接入方式。整理了验证指标、排查方法和生产落地建议。下一步的实践建议很直接找一个小场景定义两个工具实现一个最小 Agent然后跑 20 条测试用例看通过率。先把这条路走通再去研究向量数据库、多 Agent 编排、模型微调这些进阶方向。目前在 Agent 开发领域工程实践的重要性已经超过了模型本身。谁会封装工具、谁懂容错设计、谁能把模型能力稳稳交到业务方手里谁就能真正把 AI Agent 变成生产力。建议把文中 Python 最小 Demo 先跑通再对照 Spring AI 的代码看一遍最后做一个小场景的评测集。过程中遇到问题建议优先查日志和模型返回的原始响应多数问题都藏在这两样东西里。