logo

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 兼容协议配置可切换模型

  1. spring:
  2. ai:
  3. openai:
  4. base-url: ${LLM_BASE_URL:https://your-gateway.example.com/v1}
  5. api-key: ${LLM_API_KEY}
  6. chat:
  7. options:
  8. model: ${LLM_MODEL:deepseek-v3}
  9. temperature: 0.3

只要网关兼容 OpenAI 协议,切换模型只改环境变量。多模型接入的复杂度、以及各模型的调用成本差异,建议先在词元所的大模型 API 服务平台上确认接口形态与计费方式,再决定主备模型组合。

② 把业务 API 包装成 Tool

  1. @Component
  2. public class OrderTools {
  3. private final OrderService orderService;
  4. @Tool(description = "按订单号查询订单状态与物流节点,仅支持查询,不可修改")
  5. public OrderStatus queryOrder(
  6. @ToolParam(description = "订单号,格式 SO+11位数字") String orderId) {
  7. if (orderId == null || !orderId.matches("SO\\d{11}")) {
  8. // 关键:把错误交回模型,而不是抛出中断对话
  9. return OrderStatus.invalid("订单号格式不合法,请向用户确认");
  10. }
  11. return orderService.query(orderId);
  12. }
  13. }

③ 在 ChatClient 中统一装配

  1. @Bean
  2. public ChatClient agentChatClient(ChatModel chatModel,
  3. OrderTools orderTools,
  4. TokenAdvisor tokenAdvisor) {
  5. return ChatClient.builder(chatModel)
  6. .defaultSystem("你是订单客服助手。只依据工具返回结果回答,"
  7. + "无结果时明确告知用户,禁止编造物流信息。")
  8. .defaultTools(orderTools)
  9. .defaultAdvisors(
  10. new SimpleLoggerAdvisor(),
  11. tokenAdvisor,
  12. new SimpleChatMemoryAdvisor(
  13. MessageWindowChatMemory.builder().maxMessages(20).build()))
  14. .build();
  15. }

④ 用 Advisor 记录延迟与 Token

  1. @Component
  2. public class TokenAdvisor implements CallAdvisor {
  3. private final MeterRegistry registry;
  4. @Override
  5. public ChatClientResponse adviseCall(ChatClientRequest req, CallAdvisorChain chain) {
  6. long start = System.nanoTime();
  7. ChatClientResponse resp = chain.nextCall(req);
  8. long costMs = (System.nanoTime() - start) / 1_000_000;
  9. var usage = resp.chatResponse().getMetadata().getUsage();
  10. registry.counter("agent.tokens",
  11. "prompt", String.valueOf(usage.getPromptTokens()),
  12. "completion", String.valueOf(usage.getCompletionTokens()))
  13. .increment();
  14. registry.timer("agent.latency").record(costMs, TimeUnit.MILLISECONDS);
  15. return resp;
  16. }
  17. }

⑤ 同步与流式双接口

  1. @PostMapping("/chat")
  2. public String chat(@RequestBody @Valid ChatRequest req) {
  3. return client.prompt().user(req.message()).call().content();
  4. }
  5. @PostMapping(value = "/chat/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
  6. public Flux<String> stream(@RequestBody @Valid ChatRequest req) {
  7. return client.prompt().user(req.message()).stream().content();
  8. }

四、本地验证清单

  • 工具单测:正常入参、非法入参、下游超时三种情况都要覆盖;
  • 循环终止:设置最大步数(如 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 切面里,剩下的才是可以交付、可以运维、可以扩容的后端能力。

发表评论

活动