这两年聊 AI Agent 的人不少但真正把它当工程系统来搭的人很少。GitHub 上一搜一大把 demo跑起来能聊天、能调几个工具可一聊到并发、可观测、降级、评估和人工复核很多人就沉默了。AI Agent 的工程实现不是“写个 prompt 再调几个 function”它是一套由目标、模型、上下文、工具、规划、记忆、反馈组成的结构化系统同时还要在框架选型、状态管理、并发承载这些决策点上做出取舍。这篇文章就按“七要素 七个决策点”的框架把这些东西掰开揉碎讲清楚适合那些已经跑通过 Agent demo、正准备往生产环境推的开发者也适合刚接手 Agent 项目的后端工程师看完至少能知道下一步该做什么。1. 先说清楚Agent 工程化到底在解决什么问题1.1 为什么“会写 Prompt”不等于“会做 Agent”很多人第一次接触 Agent 的时候都会觉得它无非就是“Prompt 工具调用”。但只要你把 Agent 部署到线上问题立刻会换一副面孔模型偶尔不按格式输出工具调用偶尔超时用户的一句话能被理解成三种意图长会话聊到一半突然“失忆”更高并发一来推理服务和外部接口一起开始超时。这个时候你会发现过去那套“调 API 写提示词”的打法根本撑不住。原因在于Agent 本质上是一个有状态、有分支、有外部依赖的分布式系统而不只是一个函数调用链。它需要自己做意图判断、任务拆解、工具选择、结果校验、上下文维护并且所有行为都发生在不可控的网络环境里。生产级的 Agent 工程化目标就是把这种不可控收敛到可控范围内方式就是把运行过程拆成模块、把模块之间的流转做成显式状态机、把每一步的输入输出全部记录下来。这也正是“七要素”和“七个决策点”要解决的核心问题。1.2 一张心法图七要素决定上限七个决策点决定下限从业几年我带过不少 Agent 项目也逐渐形成了一套自己的拆解方式**看一个 Agent 是否成熟先看七要素是否完整把七要素从 Demo 推上生产再走一遍七个决策点。**七要素分别是目标、模型、上下文、工具、规划、记忆、反馈它回答的是“一个 Agent 由什么组成”七个决策点则是框架选型、模型接入、状态管理、工具治理、并发承载、可观测性、评估护栏它回答的是“工程上怎么落地”。这两套东西的关系可以理解成一张表要素是骨架决策点是血肉。骨架决定 Agent 的能力上限比如规划能力弱复杂任务就搞不定决策点决定系统的生产下限比如没有超时控制和降级高峰期一个模型报错整个服务就雪崩。维度七要素能力侧七个决策点工程侧关注点Agent 能不能做好事情Agent 能不能稳定安全地跑在生产环境核心问题模型、上下文、工具之间怎么协作并发、故障、安全、迭代怎么处理典型产出意图识别、任务规划、工具调用模型网关、状态图、链路追踪、人工复核上线失败表现答非所问、不调工具、编造结果超时、死循环、状态错乱、不可追踪我做项目时习惯先用一周把七要素梳理完画出一张“哪些模块是核心、哪些可以复用”的草图再进入七个决策点的选型。顺序很重要先想清楚能力再谈工程否则很容易出现“框架选了半天最后发现业务意图都没定义好”的局面。2. 七要素拆开一个成熟 Agent 的骨架2.1 目标定义Agent 的北极星目标这个词听起来很虚但它是整个 Agent 的出发点。一个没有明确目标的 Agent就像一个没有绩效指标的新员工干起活来全凭感觉。这里的“目标”不只是一句 system prompt而是拆成三个层面一是任务意图也就是 Agent 到底要处理哪些用户问题二是约束条件比如“只能回答订单相关的咨询”“禁止编造物流信息”“涉及金额操作必须转人工”三是验收标准也就是什么情况下算回答正确、什么情况下必须上报。举个例子一个售后客服 Agent目标不是“帮用户解决问题”而应该写成“识别用户的售后诉求基于订单数据和售后政策给出准确答复无法确认时转人工”。如果你只写“帮用户解决问题”模型很可能在拿不到数据的情况下编一个“快递预计明天送达”的答案看起来在帮忙实际是闯祸。工程实现上我建议大家把目标做成结构化配置不放在 Prompt 里硬编码而是作为一条独立的“目标元数据”传给调度层方便后续评估和调整。2.2 模型接入别把模型当常量很多团队对模型的认知停留在“选一个厉害的模型一直用下去”但真实情况是同一套 Prompt、同一个工具集换个模型Agent 的表现可能完全不同。有的模型擅长指令遵循工具调用格式稳定有的模型推理强但输出慢有的模型便宜但分类准确率差。所以模型不是常量而是需要管理的资源。工程上我的习惯是做模型抽象层也就是常说的 ModelGateway。它统一封装模型调用让上层业务不直接依赖某一个具体厂商或模型版本。这样做的直接好处是降级容易主模型超时了可以降级到备用模型复杂任务用强模型意图识别这种高频简单任务用便宜模型还可以在网关层统一处理限流、重试、Token 统计。很多踩坑事故根本不是 Agent 逻辑写错了而是模型 API 抖动导致整条链路中断而团队只能干等。2.3 上下文管理Token 预算就是你的工作台面上下文管理是我觉得入门 Agent 最容易忽视、但越做越重要的一环。可以把上下文窗口理解成一张工作台你不能把仓库里所有货都堆到台面上只能放当前任务最需要的几样东西。用户的问题、历史对话、订单数据、企业知识库、工具返回结果如果一股脑全塞给模型几个回合之后 Token 就爆了更麻烦的是关键信息反而被淹没。实操上我建议做三级上下文第一级是核心上下文包含用户当前输入和经过抽取的实体比如订单号、用户名、问题类型第二级是记忆上下文包含最近几轮摘要和用户长期偏好第三级是检索上下文只有当问题涉及知识库内容时才追加检索结果。工程上可以用一个 context_builder 模块统一组装而不是在每一个节点里自己拼字符串。这样做的目的是让模型永远在“最相关的信息”上做决策而不是在“最全的信息”上碰运气。2.4 工具定义Agent 的双手和边界Agent 的能力边界基本是由工具决定的。模型再聪明没有查询订单的工具、没有发送工单的工具它也只能空口白话。但工具也不是越多越好工具过多会让模型选择困难尤其是一些命名模糊、描述不准确的工具很容易被模型误调用。工具定义的核心有三点第一工具入参和出参要有严格的 Schema并且用清晰的描述说明“什么时候该用、怎么用”第二工具执行必须具备完善的异常处理超时、返回空值、业务报错都要能转化成模型可以理解的结果第三权限边界要在工具层控制不能让模型直接拿着裸 SQL 去查数据库而是把它封装成“查询订单状态”这种业务动作。我把工具层也当作一道安全边界所有敏感操作都在这一层拦截和审计后面讲决策点的时候还会再展开。2.5 规划编排不要指望模型一镜到底简单任务模型一个来回就能解决复杂任务比如“用户要退货但订单已超过退货期”模型必须先查订单、再查售后政策、再判断是否满足条件最后才会生成答复。这类多步推理不能靠模型自由发挥否则很容易出现中途跑偏、重复调用、自说自话的问题。所以我把规划也当作一个独立要素来对待。可行的做法是用 LangGraph 这类图编排框架把任务流程显式建模先判断意图再决定走哪个子流程每一步有明确的输入输出和分支条件。这样即使某一步模型判断失误至少工程链路是可回退、可追踪、可人工介入的。另外一定不要忘记给 Agent 设置最大步数否则模型在工具调用里绕圈几分钟都出不来这在生产环境是不可接受的。2.6 记忆管理会话之外还要有业务记忆记忆这个要素经常被误解成“把聊天记录全保存下来”。真正生产可用的记忆分为短期记忆和长期记忆两类。短期记忆是当前会话的上下文存 Redis 这类带过期时间的存储里就好长期记忆是用户的历史偏好、身份信息、业务标签比如“这个用户上次投诉过物流慢”需要结构化和向量化之后长期保存。在工程实现上我建议不要让每个 Agent 节点直接去读写数据库而是通过 memory_service 统一访问。记忆的写入要讲策略不是每句话都值得记只记录影响后续决策的关键事实。比如用户说“我要退货”这个必须记用户说“今天天气不错”记了也白记。记忆的召回也要讲策略检索跟当前问题最相关的记忆片段而不是把用户三个月内的所有行为全部倒给模型。2.7 反馈闭环没有评估就没有迭代一直没把评估当成“要素”的人做 Agent 基本靠感觉。改了一版 Prompt感觉回答顺了一点换了个模型感觉好像更快了但这些感觉既不能量化也无法沉淀成团队经验。反馈闭环要解决的就是“这次改动到底有没有变好”的问题。我的建议是给 Agent 建立两个层面的反馈。离线层准备一个覆盖典型场景的回归测试集每次改 Prompt、改工具、换模型都跑一遍测试集看任务完成率、工具调用正确率、幻觉率有没有变化在线层记录真实用户的反馈、任务成功率和工具执行成功率把这些指标汇总成一个可观测的看板。没有这套东西Agent 项目越到后期越不敢改因为不知道改了会出什么乱子。3. 七个决策点从 Demo 到能扛并发的生产系统3.1 决策点一框架选型LangGraph、自研还是低代码第一个决策点就劝退不少人。LangChain 全家桶、LangGraph、自研状态机、Spring AI、Rust 自研还有扣子这样的低代码平台选择多争议也多。我的选择逻辑很直接看团队技术栈和项目复杂度而不是跟风。如果团队是 Python 栈、要做多步规划型 AgentLangGraph 是当前性价比最高的选择它把图执行、状态传递、条件分支这些基础能力都封装好了你只需要专注业务节点。如果团队以 Java 为主可以重点看 Spring AI它跟 Spring Boot 的集成度很高也能支持 ChatModel、Tool Calling 这类抽象适合 Java 生态快速接入。Rust 当然也能写 Agent但更好的定位是用在网关、旁路处理、高吞吐日志收集这些对性能敏感的位置而不是把整个业务编排都用 Rust 硬写成本会高很多。至于扣子这类低代码平台适合快速验证产品逻辑和给运营同学自助搭机器人到后期需要深度定制和精细权限控制时还是要把核心链路切到代码工程里。3.2 决策点二模型接入与统一降级把模型接入拎出来单独作为一个决策点是因为我见过太多项目把“调模型 SDK”直接写死在代码里。这样做的后果是模型供应商一抖动、一个接口版本升级整个 Agent 就要跟着改代码。正确做法是在模型之上包一层网关并且把降级策略想清楚。我常用的一套降级设计是“三档模型”主模型负责复杂规划和最终回答要求质量高、推理强辅助模型负责意图识别、实体抽取、摘要这类简单任务可以选响应快、便宜的兜底模型在服务异常时撑住基础体验哪怕效果差一些也不能让用户干等。网关层还要统一处理超时、重试、限流和 Token 成本统计。这里有个细节值得注意重试不是无限重试一般设 2 到 3 次、指数退避超过阈值直接走降级否则并发一高光是重试流量就能把模型服务打挂。3.3 决策点三状态管理与图编排Agent 是有状态的用户当前在哪个环节、已经查到了什么数据、还需要调用什么工具这些都必须被管理起来。用 LangGraph 时这部分对应的是 StateGraph 里的 State、Node、Edge。State 是全局状态对象每个 Node 都能读取和更新Edge 定义流转方向条件边则根据当前状态决定下一步走哪条分支。为什么一定要用图而不是朴素的 Chain因为 Agent 的调用路径是动态的。同一个用户问题可能走“查订单直接回复”也可能走“查订单发现异常转人工”写死成线性链根本处理不了这种分支。但引入图之后你必须把每个节点写成一个纯函数式操作输入 State 的一部分输出 State 的更新。这样做最大的好处是每个环节都可以单独测试也可以在任何节点之间插入人工审核、日志记录和超时控制这在生产环境里是救命的能力。3.4 决策点四工具注册与执行沙箱工具是 Agent 的双手同时也是安全风险的主要入口。工程上我不建议让每个业务方直接写一个函数然后到处 import而是做一个统一的工具注册中心每个工具都有唯一的名称、描述、入参 Schema、执行超时、权限等级和审计策略。Agent 在启动或热更新时从注册中心拉取可用工具列表模型根据描述决定调用哪个工具真正执行时由工具中心统一代理。安全方面有几个底线。第一不可逆操作比如直接打款、直接修改订单不允许 Agent 单方面执行必须走人工复核第二工具的所有调用都要有审计日志谁在什么时间调了什么工具、传了什么参数、返回了什么结果全部可追溯第三涉及外部平台的自动化操作比如自动在内容平台发消息、辅助交易除了技术实现之外更重要的是合规和平台规则。技术上 Agent 很容易做到这些动作但如果没有审批链路和风险控制建议不要裸奔上线。我常跟团队说的一句话是模型负责聪明工程负责保险。3.5 决策点五并发与流式响应“AI Agent 怎么扛并发”是最近被问得特别多的问题。很多人以为并发瓶颈在 HTTP 接入层实际上完整跑一次 Agent 任务往往要好几秒甚至十几秒这里面有大模型推理的延迟、有多步工具调用的网络开销所以真正挤压系统的是“每个任务占用的时间片”。实践中我给的方案是一套组合拳。首先接入层用 FastAPI 这类异步框架配合 asyncio 处理 IO 密集型等待不要让进程阻塞在模型调用上其次会话状态必须外置用 Redis 保存对话状态和图执行进度不能把状态放在某个 worker 的内存里否则水平扩容时状态丢失第三长耗时的 Agent 任务尽量不要求接口同步返回完整结果而是通过 SSE 流式返回中间事件或者先投递到任务队列、再由前端轮询结果。最后一定要在应用层做并发控制比如限制同时进行的 Agent 任务数超过阈值直接返回“系统繁忙”这比无限堆积任务让所有请求一起超时优雅得多。至于 Rust 在这里的角色我更推荐用在流量入口或旁路处理上比如写一个高性能的请求网关或日志采集器让 Python 的 Agent 调度层专注业务逻辑。它不负责“思考”但能让你在扛并发时少一些资源焦虑。3.6 决策点六可观测性与链路追踪Agent 的排查难度比传统接口高一个量级。传统接口就是“请求进来、响应出去”中间逻辑固定出问题顺着调用链查就行。Agent 则是一个多轮决策系统同一个用户问题可能走完全不同的分支模型每一步的输出都带有随机性没有链路追踪你基本无法复现问题。我的实践是两种方案并行一是用 LangSmith 这类专门追踪 LLM 调用的工具把每个节点的 Prompt、模型输出、Token 消耗、工具调用参数都记录下来二是用 OpenTelemetry 把 Agent 执行链路接入公司已有的监控体系按 trace_id 串起从用户请求到最终响应的全过程。追踪里最关注的几个点模型调用耗时和返回内容、工具执行成功还是失败、状态转移是否符合预期、用户最终是否得到满意答复。有了这些你才能回答“这个 Agent 为什么答错了”这种灵魂问题而不是靠用户截图反复推测。3.7 决策点七评估与安全护栏最后一个决策点也是决定 Agent 能不能长期跑下去的关键评估和安全。我看过一个项目Agent 在测试环境表现优秀上线一周后频繁出事故原因就是没有评估体系和护栏模型在真实数据上的表现和测试集完全是两回事。评估维度和传统模型评测也不一样我常用这几项任务完成率、工具调用准确率、幻觉率、平均步数、端到端耗时。每一步改动前先跑回归集上线后用真实流量观察指标变化。安全护栏方面按操作影响面分等级只读类操作比如查订单、查政策可以给 Agent 白名单权限可逆但影响较大的操作比如发送回复、创建工单需要有默认确认机制不可逆操作严格走人工复核。之前有人问我能不能用来做交易决策我给出的建议是拿回测和历史数据做研究可以直接接实盘绝对不建议这类场景一定要先把风控和人工确认链路做扎实再谈自动化。4. 工程实例一个售后客服 Agent 的落地拆解4.1 整体架构与模块划分聊完理论和决策用一个我实际搭过的售后客服 Agent 来做完整拆解。这个 Agent 要处理的需求很典型用户查订单状态、问物流、申请售后以及处理复杂投诉时转人工。整体架构分五层。第一层是接入层用 FastAPI 提供聊天接口和流式响应第二层是 Agent 调度层用 LangGraph 定义状态图和节点第三层是工具层封装订单查询、物流查询、售后政策查询等工具独立部署成内部 API第四层是状态层用 Redis 保存会话状态和执行进度第五层是追踪评估层把每一轮模型调用和工具调用都打到日志和监控平台。这种分层的好处是每一层都能独立扩展比如工具层后续如果换了底层业务系统Agent 调度层可以不用改。4.2 核心代码结构与关键实现用一个简化的 LangGraph 代码来说明核心链路。注意这里以 LangGraph 常见版本的 API 为参考不同小版本可能略有差异但整体思路是通用的。from typing import TypedDict, Optional from langgraph.graph import StateGraph, START, END class AgentState(TypedDict): user_input: str intent: str need_human: bool order_result: Optional[dict] final_answer: str async def intent_node(state: AgentState): # 通过模型网关做意图识别而不是直接调模型 SDK intent await model_gateway.classify( user_inputstate[user_input], candidates[order_query, after_sale, human] ) return {intent: intent} async def order_query_node(state: AgentState): # 此处调用内部订单服务而不是让模型直接摸数据库 order_result await order_tool.query(user_inputstate[user_input]) return {order_result: order_result} def route_after_intent(state: AgentState): if state[intent] order_query: return order_query if state[intent] human: return human return common_answer async def common_answer_node(state: AgentState): # 一般售后问题基于知识库直接回答 answer await model_gateway.complete( system_prompt你是售后客服助手回答要简洁、准确, user_inputstate[user_input] ) return {final_answer: answer} async def human_node(state: AgentState): # 转人工并标记本次会话需要人工介入 await ticket_tool.create(user_inputstate[user_input]) return {need_human: True, final_answer: 已为您转接人工客服请稍候。} graph StateGraph(AgentState) graph.add_node(intent, intent_node) graph.add_node(order_query, order_query_node) graph.add_node(human, human_node) graph.add_node(common_answer, common_answer_node) graph.add_edge(START, intent) graph.add_conditional_edges( intent, route_after_intent, { order_query: order_query, human: human, common_answer: common_answer, }, ) graph.add_edge(order_query, common_answer) graph.add_edge(common_answer, END) graph.add_edge(human, END) agent_graph graph.compile()这段代码看起来很简短但工程化之后每个节点内部都会做大量细节处理。比如 intent_node 里不只是分类而是会做实体抽取把订单号、用户名这些关键字段抽出来存到 State 里order_query_node 会处理订单服务超时、返回空数据等异常情况common_answer_node 在生成回答前会检查 order_result 是否存在避免模型在查单失败后仍然编造物流信息。所有这些细节才是生产系统和 demo 之间的差距。接入层用 FastAPI 暴露流式接口时我会用 SSE 把中间状态推给前端from fastapi import FastAPI from fastapi.responses import StreamingResponse app FastAPI() app.post(/agent/chat) async def agent_chat(user_input: str, thread_id: str): # 用 thread_id 隔离多用户会话状态 async def event_stream(): async for chunk in agent_graph.astream( {user_input: user_input}, config{configurable: {thread_id: thread_id}}, ): yield fdata: {chunk}\n\n return StreamingResponse(event_stream(), media_typetext/event-stream)如果并发压力上来了建议把 agent_graph.astream 里的任务从 HTTP 请求里解耦出去投递到队列里异步执行再通过 WebSocket 或 SSE 把结果推给用户而不是让所有用户都怼在模型网关前面等待响应。4.3 从单机到集群并发改造实录这个项目最开始是单机部署状态放在进程内同步调用模型接口压测几轮就发现问题8C16G 的实例单其实并发跑到 5 个任务以上就开始排队模型接口 RT 经常超过 3 秒业务查询再一叠加一个简单客服问答要等十几秒才出结果。后来我做了三件事。第一把 FastAPI 接口层改成全异步模型调用、订单查询全部走 asyncio接入层不再阻塞线程第二把 Redis 作为统一状态存储LangGraph 的 checkpointer 也切到 Redis保证任何一个 worker 都能继续上一个 worker 留下的任务第三给 Agent 整体加信号量并发控制设定同时最多 6 个完整 Agent 任务超过的直接缓冲到队列并提示用户排队。改造之后在同样的实例上用户体验从“长时间无响应”变成“快速收到排队提示 异步出结果”整体稳定度提升明显。这也是我认为 Agent 扛并发最核心的思路不要让所有请求都急切地抢模型资源该排队就排队该降级就降级。5. 常见问题与排障实录5.1 六个高频问题速查做 Agent 工程化这些年有一个很有意思的现象每个团队遇到的问题高度相似几乎都是模型行为不稳定、链路出鬼、并发扛不住这三大类。我把高频问题整理成一个速查表方便遇到类似情况的朋友按图索骥。症状可能原因排查与解决思路模型死活不调用工具工具描述不清晰、模型不知道何时该用检查工具描述补充“当用户询问订单状态时调用”这类触发条件模型乱调用工具工具 Schema 不严格、入参填写随意细化入参校验增加“实体抽取 工具匹配”前置环节长对话后答非所问上下文过长、关键信息被淹没做上下文压缩和实体记忆只保留与当前任务相关的信息并发一高就超时每个 Agent 任务耗时太长请求堆积接入层异步化、状态外置 Redis、任务队列 SSE 推送Agent 无限循环调用工具缺少 max_steps 和循环检测给图执行加步数上限单步超时循环分支自动降级工具返回后不读取结果输出 Prompt 没有约束在结果进入最终回答前增加“基于工具结果生成答复”的中间节点这张表基本覆盖了我过去几个月被问到最多的六个问题。每个问题背后都对应着一个工程机制的缺失所以排查的时候别只想着调 Prompt先看看链路结构本身是否够稳。5.2 我在实战中踩过的三个坑最后分享几个我自己踩过的坑都是花钱买来的教训。第一个坑是把所有业务规则全部写进 Prompt。早期做 Agent 时图省事把退货规则、物流规则、客服话术全塞进 system prompt结果后面规则一改Prompt 一长模型行为立刻变得不可控。后来我把规则拆出来一部分变成代码里的分支逻辑一部分放进工具返回结果让模型基于结构化的规则数据做判断而不是背诵一段冗长的文字。第二个坑是没有限步数。有一次压测一个简单任务因为工具调用出了问题Agent 在“查订单失败 - 换个方式再查 - 再失败”的循环里转了 20 多次把模型调用费用和日志量都拉高了。从那以后我所有 Agent 图都会硬性设置 max_steps并在状态里维护一个 step 计数超过阈值直接走兜底回复或转人工。第三个坑是让模型直接拿 API 返回的字段名回答用户。工具返回里明明写的是 status_code 2、delivery_status “in_transit”模型却原样念给用户用户根本听不懂。这个问题的解法是在工具结果转成用户可见内容时增加一个“结果翻译层”把内部字段转成“您的商品正在运输中”这种自然语言再交给模型做最终润色。这类细节看似小但它直接影响真实用户的体感。Agent 工程化走到最后拼的不是谁用了更新的框架而是谁能把目标定义得更清楚、把状态管理得更稳、把工具边界划得更安全、把每次失败追踪得更彻底。我个人最近一年比较坚定的一个判断是如果公司里多条业务线都要上 Agent不如优先搭一个“Agent 中台”把模型网关、工具注册、状态存储、链路追踪、评估护栏这些通用能力抽出来共享业务线只维护自己的技能包和话术策略。这样既不重复造轮子也能在失控之前有一道统一的闸门。如果你也在做 Agent 工程化建议先选一个高频业务场景把七要素补全、七个决策点至少过一遍比单纯追着新框架跑有用得多。