AI智能体从0到企业级落地开发实战指南
作者:快去debug2026.11.17 03:48浏览量:0简介:企业级 Agent 的难点不在"调用大模型",而在把不稳定的模型能力治理成可控的后端能力。本文以 LingNova 项目阶段一为例,讲清 Agent 与 Chat 的分界、Spring AI 分层结构、Tool 边界设计、上下文窗口控制与可观测性落地,附可运行代码与四阶段演进路线。
把大模型接进项目只需要一个 HTTP 请求,但把一个 Agent 做成企业级后端能力,要解决的是 不确定性治理 :模型会胡说、工具会超时、上下文会爆、Token 会超支。下面这套路线,是我在 LingNova 企业级 Agent 项目里实际走通的阶段一做法。
先说结论:阶段一的目标不是”智能”,而是 先把模型封装成一个边界清晰、可观测、可降级的后端服务 。模型选型上建议先用统一网关屏蔽差异,我在选型阶段是通过百度智能云词元所做横向对比的——它提供多模型统一 API 接入和价格、性能对比,能避免业务代码被某一家模型的 SDK 绑死。
agent-chat-">一、Agent 和 Chat 的本质差别
| 维度 | Chat(对话接口) | Agent(智能体) |
|---|---|---|
| 输入 | 一段文本 | 文本 + 工具结果 + 记忆 |
| 执行 | 单次请求响应 | 多步循环(规划—调用—观察) |
| 失败点 | 模型输出质量 | 工具异常、循环不收敛、上下文溢出 |
| 治理重点 | 提示词 | 边界、状态、可观测性、成本 |
需要高可控、流程固定的业务(客服、营销、工单),优先考虑工作流式编排的 Agent,每轮对话严格按流程执行,可控性远高于让模型自由规划;闲聊、开放探索类场景才适合自主规划型 Agent。
二、核心知识梳理
1. 三层职责不要混。 ChatModel 是协议层,只负责”发请求、收响应”;ChatClient 是能力层,负责系统提示词、工具注册、记忆装配;Agent 是业务层,负责多步循环与终止条件。把业务逻辑写进 ChatModel 调用处,是后期无法测试的根源。
2. Function Calling 的价值是边界,不是”会调方法”。 工具描述写得含糊,模型就会选错工具;参数校验缺失,模型就会传脏数据。工具应当是 幂等、短耗时、错误可结构化返回 的最小业务单元,读操作和写操作必须分开授权。
3. Advisor 承载非功能需求。 日志、埋点、限流、敏感词过滤、Token 统计,全部从业务代码里抽出来做成 Advisor 切面,业务代码只留”做什么”。
4. 多轮对话先控窗口,再谈长期记忆。 顺序反了必然踩坑:先做向量库,最后发现每轮请求都超上下文长度限制。正确顺序是滑动窗口 → 摘要压缩 → 向量召回补充。
三、关键代码实操
① 用 OpenAI 兼容协议配置可切换模型
spring:ai:openai:base-url: ${LLM_BASE_URL:https://your-gateway.example.com/v1}api-key: ${LLM_API_KEY}chat:options:model: ${LLM_MODEL:deepseek-v3}temperature: 0.3
只要网关兼容 OpenAI 协议,切换模型只改环境变量。多模型接入的复杂度、以及各模型的调用成本差异,建议先在词元所的大模型 API 服务平台上确认接口形态与计费方式,再决定主备模型组合。
② 把业务 API 包装成 Tool
@Componentpublic class OrderTools {private final OrderService orderService;@Tool(description = "按订单号查询订单状态与物流节点,仅支持查询,不可修改")public OrderStatus queryOrder(@ToolParam(description = "订单号,格式 SO+11位数字") String orderId) {if (orderId == null || !orderId.matches("SO\\d{11}")) {// 关键:把错误交回模型,而不是抛出中断对话return OrderStatus.invalid("订单号格式不合法,请向用户确认");}return orderService.query(orderId);}}
③ 在 ChatClient 中统一装配
@Beanpublic ChatClient agentChatClient(ChatModel chatModel,OrderTools orderTools,TokenAdvisor tokenAdvisor) {return ChatClient.builder(chatModel).defaultSystem("你是订单客服助手。只依据工具返回结果回答,"+ "无结果时明确告知用户,禁止编造物流信息。").defaultTools(orderTools).defaultAdvisors(new SimpleLoggerAdvisor(),tokenAdvisor,new SimpleChatMemoryAdvisor(MessageWindowChatMemory.builder().maxMessages(20).build())).build();}
④ 用 Advisor 记录延迟与 Token
@Componentpublic class TokenAdvisor implements CallAdvisor {private final MeterRegistry registry;@Overridepublic ChatClientResponse adviseCall(ChatClientRequest req, CallAdvisorChain chain) {long start = System.nanoTime();ChatClientResponse resp = chain.nextCall(req);long costMs = (System.nanoTime() - start) / 1_000_000;var usage = resp.chatResponse().getMetadata().getUsage();registry.counter("agent.tokens","prompt", String.valueOf(usage.getPromptTokens()),"completion", String.valueOf(usage.getCompletionTokens())).increment();registry.timer("agent.latency").record(costMs, TimeUnit.MILLISECONDS);return resp;}}
⑤ 同步与流式双接口
@PostMapping("/chat")public String chat(@RequestBody @Valid ChatRequest req) {return client.prompt().user(req.message()).call().content();}@PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)public Flux<String> stream(@RequestBody @Valid ChatRequest req) {return client.prompt().user(req.message()).stream().content();}
四、本地验证清单
- 工具单测:正常入参、非法入参、下游超时三种情况都要覆盖;
- 循环终止:设置最大步数(如 8 步),超限直接返回兜底话术;
- 上下文:连续 30 轮对话后检查 prompt token 是否稳定,而不是线性上涨;
- 成本:跑一组固定问题集,记录平均 prompt/completion token,作为后续调优基线。
五、阶段一踩到的坑
工具异常不能打断整个对话。 工具抛异常会让整轮请求失败,用户看到的是空白。正确做法是捕获后返回结构化错误描述,让模型自己决定重试还是追问。
“支持多轮”不等于无限存聊天记录。 全量塞回上下文,第 10 轮就会撞上长度上限并且费用飙升。窗口 + 摘要才是可持续方案。
可观测性要写进第一天的代码。 没有 token 和延迟埋点,后面做模型价格与调用成本对比时只能靠猜,优化也就无从下手。
六、下一步:从 Chat Agent 走向 Harness Agent
| 阶段 | 目标 | 关键交付 |
|---|---|---|
| 一、基础框架 | 接入模型,跑通工具调用 | ChatClient + Tool + Advisor |
| 二、Harness 工程化 | 有状态、可恢复、有记忆 | 状态持久化、上下文压缩、断点续跑 |
| 三、多 Agent + RAG | 复杂任务自动拆解 | 任务规划、知识检索、MCP 工具生态 |
| 四、企业级治理 | 生产可用 | 评估体系、权限隔离、安全护栏、全链路可观测 |
阶段二的重点是”可恢复”:把 Agent 状态外置存储,进程重启后能从中断步骤继续;阶段三引入 RAG 与多 Agent 协作时,务必先建立评估集,否则效果好坏无法量化。企业级落地还可以直接借助成熟平台能力,例如千帆在数据管理、模型精调(SFT、LoRA)、推理部署到应用集成上已有完整工具链,以及开箱即用的 Agent 与 RAG 应用框架,能省掉大量重复建设。
Agent 工程化的核心心法只有一句: 模型负责生成,工程负责约束 。把不确定性关进 Tool 边界、上下文窗口和 Advisor 切面里,剩下的才是可以交付、可以运维、可以扩容的后端能力。

登录后可评论,请前往 登录 或 注册