1. 为什么能跑通 Demo离能上线还差着十个 Sprint今年做应用层的团队几乎都在聊 AI Agent框架也越出越多LangGraph、AutoGen、CrewAI、Spring AI甚至 Rust 社区已经有人拿 tokio 手搓 Agent 运行时。但一个特别典型的现状是教程收藏了一堆Demo 照着跑通了一说到我要把它做成一个能扛住真实用户请求的服务立刻卡壳。问题通常不在模型能力而在工程决策——上下文怎么管、状态放哪里、工具调用失败了怎么办、并发一上来为什么全乱了。这篇文章想把 AI Agent 从概念到工程实现这条路上的坑整理成一张检查表先把 Agent 拆成七个要素再把从原型到生产必须做的取舍收敛成七个决策点。对想从零搭 Agent、或者要在现有系统里集成 Agent 的工程师来说这份梳理应该能帮你省下不少试错时间。1.1 一张检查表七要素是什么七个决策点又是什么先直接给结论。七要素指的是一个完整 Agent 系统的七个组成部分大模型作为推理核心、任务规划目标拆解与步骤编排、记忆短期会话与长期知识、工具对外部能力的封装、行动真正执行某个操作、观察收集执行后的反馈、循环控制决定什么时候进入下一步、什么时候停下。七个决策点则是我把 Agent 从 Demo 推向生产时总结出的关键取舍编排模式、模型路由、上下文策略、记忆落点、工具契约、循环边界、可观测性。两者是不同维度的东西七要素回答它由什么构成七个决策点回答每一步具体怎么做。前者帮你理解 Agent后者帮你实现 Agent。我用一个生活化的类比帮你建立整体印象。Agent 就像一个刚入职的员工大模型是他的大脑负责思考和判断任务规划是他手上的工作清单记忆是便利贴加资料柜工具是他的双手用来操作电脑、调用系统、发邮件行动是真正把手伸出去干活观察是干完活之后检查结果循环控制则是项目经理定的规矩——最多干几轮、干到什么程度必须停下来问人。这个员工如果只有大脑没有规矩迟早会把公司折腾到预算爆炸。工程实现的核心就是把每个环节都变成有边界、可观测、能收敛的代码。2. 七要素拆解Agent 不是模型加提示词那么简单很多人第一次搭 Agent 时的想法是一个循环里反复调用大模型让它自己决定调用哪个函数。这个理解方向没错但过于粗糙。真正做工程时每一个要素都有独立的处理方式也有各自容易翻车的地方越早看清越少踩坑。2.1 大模型与任务规划谁来思考思考到什么粒度大模型是 Agent 的核心推理部件但很多团队会误以为所有环节都上最强模型就行。实际项目里我会把思考拆成两个层次第一层是规划层负责把用户目标拆成可执行的子任务第二层是执行层负责在具体步骤中推理该调什么工具、怎么理解工具返回的结果。规划不一定每轮都做。如果任务链条是固定的比如查天气、看建议、生成穿搭文案完全可以用工作流把流程写死只有任务高度开放例如帮我调研这个行业近一年的动态才需要模型在每个步骤之间自主规划。规划粒度也要克制。模型很容易把写周报拆成列出项目、收集 git 记录、总结变更、生成草稿、检查格式五步但每一步本身可能又是一个复杂任务。如果不给每一步限定输入输出边界整个 Agent 会在拆解上浪费大量 token。我的做法是有确定性流程的任务先人工梳理成步骤把规划权交还给代码只有真正开放的任务才让模型自由规划同时给它限定思考深度最多两层。规划结果出来后还应该做一层校验模型可能拆出当前系统里根本执行不了的步骤比如它规划了访问内部系统 A但你的 Tool 列表里根本没有这个能力这类情况要在规划阶段就拦截。2.2 记忆哪些该记住哪些该扔掉存在哪里记忆是 Agent 工程里最容易被轻视的环节。七要素里的记忆要拆成短期和长期两个层面短期记忆就是当前会话的上下文通常表现为 message 列表用户每次请求都要带着它长期记忆是跨会话的知识比如用户偏好、业务知识、历史决策一般落到向量库或普通数据库。关键教训是不是所有记忆都值得保留。日志型内容某次工具返回的网络耗时、某一步推理的中间草稿塞进上下文只会污染模型注意力。我会给记忆打上标签关键决策进入长期记忆过程细节只存在当前会话工具结果只留结论不保留原始返回。记忆读取长度也要控制长期记忆检索回来的内容要做重排序和抽取不能让模型对着二十条相似的旧记录推理。用通俗的说法短期记忆是手上便利贴长期记忆是办公室资料柜便利贴贴满整面墙就找不到真正有用的那张了。市面上常见的做法是把历史消息全部塞进 prompt早期 Demo 这么做没问题一旦会话超过 20 轮token 消耗和模型注意力都会告急这就是上下文策略要解决的矛盾后面讲决策点时再展开。2.3 工具与行动让模型安全地碰到真实世界工具是 Agent 和外部世界之间的握手协议。模型本身不执行任何操作它只能通过函数调用机制表达意图我要调用 get_order_status参数是 order_id12345真正执行动作的是你的代码。工具要被模型正确使用必须满足三件事名字足够说明用途、描述写明边界和前置条件、参数 Schema 严格定义。举个例子一个删除用户工具描述里必须注明仅限管理员且用户无未完成订单时可删除否则模型可能在用户抱怨想注销账号时真的调用删除接口。行动层的工程实现同样容易被低估。工具入参要做校验输出要做裁剪超时要单独设置调用失败要把错误信息整理成模型能理解的文本回传而不是直接抛异常。我见过大量 Agent 在工具报错后进入无意义自我解释原因就是错误信息没有结构化模型根本不知道发生了什么。工具返回的原始数据也需要控制体积比如一次数据库查询返回几百行直接塞进上下文既浪费 token 又干扰判断正确的做法是只给模型返回提炼后的结论和关键字段原始数据存到临时存储里供后续步骤检索。2.4 观察与循环控制闭环收敛的最后一道闸门观察是这个闭环的燃料。工具执行完结果必须经过解析、提炼、标准化再回到模型面前。观察层要做一次转译把原始结果转成任务相关结论 关键字段 可选原始数据引用。这一步不做Agent 就像一个人拿到了三百页的报告却不告诉他重点在第几页推理质量完全随机。循环控制则是整台机器的刹车系统。一个完整的 Agent 循环通常包括模型决定调用工具、执行工具、观察结果、再次调用模型、再执行……直到模型认为任务完成。这个循环必须有硬性边界最大迭代步数、单步超时、全局 token 预算、关键操作的人工审批节点。没有刹车Agent 遇到模糊指令或工具故障时会在循环里空转账单膨胀速度远超想象。我自己的习惯是所有会修改外部状态的动作发邮件、下单、转账、删除数据必须加人工确认只读类工具允许自动执行但同样要设步数上限。这条原则已经帮我挡住了很多次线上事故。3. 七个决策点从上线的角度重新审视 Agent 的每一步取舍七要素讲完你对 Agent 有了结构化认知。但真正构建 Agent 服务时难点在于每一项都有多种实现方式没有任何一种组合是万能的。我在项目里反复做过的七个决策点每一个都交过学费下面按实际决策顺序讲。3.1 决策点一二编排模式与模型路由先定骨架再定大脑编排模式是 Agent 的骨架决定它是走固定流程还是自由发挥。主流选择有三种纯工作流、自治 Agent、图编排。区别可以直接看对比编排模式适用场景优点风险纯工作流规则清晰的业务如工单分类后的固定处理稳定、便宜、易排查灵活性差场景一变就要改代码自治 Agent开放式问答、自由探索能应对未知情况不可控性强、成本高、难调试图编排大部分真实项目部分流程写死、部分交给模型平衡控制与灵活概念门槛较高需要理解图执行逻辑图编排是我在多数项目里的默认选择LangGraph 这类框架允许你把确定性步骤写成固定节点把需要判断的分支交给模型决策既保留了效率又不会完全失控。模型路由解决哪一步该用哪种模型的问题意图识别、实体抽取、标题分类这类高频小任务完全可以用便宜的轻量模型多步推理、复杂生成才需要上强模型。这两者的成本可能差一个数量级路由方式可以是规则、可以是一个便宜模型快速判断、也可以是对历史数据的统计。日常对话先分类再决定走哪个 Agent 分支这就是最基本的模型路由。3.2 决策点三四上下文策略与记忆落点管理好每一寸 Token上下文窗口不是无限可用的即使模型支持 200K token也不代表真的该把 200K 全塞进去。超过一定长度模型对中段内容的注意力会明显下降这就是常说的 lost in the middle。我常用的组合策略有三种截断保留最近 N 条消息、摘要每隔几轮把旧消息压缩成一段总结、压缩用一次轻量模型调用把冗长工具输出提炼成要点。注意上下文策略要在会话层面执行不是在单次请求层面执行所以你还需要一个地方保存会话的压缩后状态。这就引出了记忆落点选择。记忆落点是一个从简单到复杂的递进单机 Demo 用进程内字典就行正式服务至少把会话状态放到 Redis设置好 TTL跨用户共享的业务知识放数据库需要语义检索的放向量库。最容易翻车的是用一个全局变量存所有人的状态——并发一上来用户 A 的消息就出现在用户 B 的 Agent 里这是我真实踩过的坑。向量库负责长期记忆时还要考虑 embedding 成本和召回质量知识更新策略也很关键旧数据不清理会让召回结果越来越偏。记忆落点选型看起来只是存储问题实际决定了系统能否水平扩容所以值得在架构阶段多花点时间。3.3 决策点五六工具契约与循环边界别让 Agent 变成脱缰野马工具契约是 Agent 工程里最容易被低估的细节。模型通过函数调用选择工具本质上是在做结构化输出。工具的名字、描述、参数 Schema 若不清晰模型就会填错参数或选错工具。我给每个工具设计接口时都会做三件事参数严格校验类型、范围、枚举值工具返回统一数据结构status、data、error工具内部任何异常都要在进入模型上下文之前转换成一段模型能看懂的说明例如查询订单失败订单号不存在请确认后重试而不是抛一个堆栈。循环边界决定 Agent 的失控上限。我见过最贵的一次事故是测试环境里 Agent 在循环里连续调了 80 次搜索工具因为每次关键词都差一点几分钟烧掉数万 token。那次之后max_iterations、单步超时、总 token 预算成了所有 Agent 项目的强制配置。如果涉及交易类动作比如有人问能不能用个人 AI Agent 做期货交易边界和人工审批更是底线没有熔断机制和人工确认就上线那不是 Agent 项目是事故预告。循环边界的数值没有黄金标准按业务估算一个检索任务通常 3 到 5 步内能收敛超过就该怀疑 Agent 卡住了宁可主动询问用户也不要硬跑下去。3.4 决策点七可观测性没有追踪的 Agent 等于盲飞Agent 是黑盒中的黑盒模型为什么选了 A 工具而不是 B 工具中间经历了哪几步哪一步开始偏离预期只看最终输出完全判断不了。可观测性必须成为工程的一部分。我现在做 Agent 项目至少会做三件事第一每一轮 ReAct 的输入输出用户消息、模型思考、工具调用、工具结果完整记入日志第二记录每轮 token 消耗和累计消耗定位成本失控第三接入 OpenTelemetry 或 Langfuse 这类追踪工具把一次用户请求的完整链路串起来。评测集也要同步建。跑通不代表可用把 20 条典型用户请求固定下来每次改 Prompt、换模型、调工具描述之后都跑一遍回归能拦截掉大部分隐性劣化。可观测性的价值在于Agent 的能力边界是靠观察和评测磨出来的不是靠一次上线定出来的。你只有知道每一步实际发生了什么才有资格说这个 Agent 是可控的。4. 并发与生产化当AI Agent 怎么扛并发成为真问题时AI Agent 怎么扛并发这个问题很常见背后通常是三类情况Demo 只服务一个人稍微多人用就卡模型调用是秒级耗时同步框架明显撑不住状态管理没做隔离多个用户互相串台。先给结论Agent 的并发瓶颈通常不在模型 API 的裸调用而在状态管理和任务调度方式。4.1 瓶颈不在模型 API而在会话状态的管理方式Agent 的一次请求不是单次问答而是多轮循环中间可能有多次模型调用和工具调用。这意味着服务端必须为每个会话维护一份独立状态当前上下文、已执行步骤、剩余步数、临时中间结果。很多扛不住并发的现场其实是共享了同一个状态导致请求互相干扰表现为响应内容串味、工具参数张冠李戴。正确做法是按 session_id 隔离状态所有上下文变量从 session 维度存取Agent 的编排逻辑保持无状态以便水平扩容会话数据统一放 Redis。我上线第一个 Agent 服务时就在这个点翻过车用了模块级字典存上下文单用户测没问题压到 20 并发时用户之间开始互相看到对话历史。排查半天才锁定是共享变量改成 Redis 存储后立刻恢复。如果你用 FastAPI 这类异步框架请求处理本身不是瓶颈真正的压力在模型 API 的并发连接数和下游工具限流。状态存内存只适合单机开发多人协作或生产环境一定要能在独立存储里按会话维度恢复。4.2 限流、队列与异步分布式系统三板斧在 Agent 里的用法Agent 服务本质上是 IO 密集型瓶颈落在等待模型响应和工具响应上。我会做三层保护第一层异步化请求进来直接丢给异步任务处理不阻塞线程第二层信号量限流控制同一时刻打到模型 API 的请求数量超过阈值排队等待第三层任务队列对耗时长任务先落队由 Worker 消费前端通过轮询或 WebSocket 拿结果避免请求长期占用连接。并发量估算可以直接套公式并发槽位数 QPS × 平均处理时长。假如每个 Agent 任务平均耗时 10 秒目标是稳定承接 5 QPS那系统里同时存在的任务就有 5 × 10 50 个也就是至少需要 50 个并发处理插槽否则必然排队。很多 Demo 挂在同步线程模型下不是因为代码差而是没意识到 Agent 的一次请求相当于传统接口的好多次内部调用。模型 API 的限流也很重要如果不做保护一个用户的多轮循环就能把供应商的配额打满其他用户全部受影响。4.3 Python、Rust、Java框定并发问题的边界而不是争论语言围绕 Rust 写 Agent 还是 Java 的 Spring AI 这类讨论我的观察是选什么语言取决于你要解决哪一层的问题。做高并发的调度网关Rust 的 async 模型和低资源占用有优势但 Agent 编排生态相对早期在企业内部做 Agent 集成Java 技术栈加 Spring AI与内部系统做事务、权限、审计集成会很顺畅快速迭代 Agent 逻辑并最大化复用社区框架Python 仍是最稳的选择。工程上更务实的做法是分层变化快的 Agent 编排层用 Python、稳定且性能敏感的状态层和网关层用 Rust 或 Java 补齐两层间用标准协议通信。语言之争没有意义先跑起来再在瓶颈处局部替换即可。5. 从决策到代码一个几乎可以照抄的最小 Agent 骨架最后给一套我实际在用的最小落地组合以及能直接改的骨架代码。技术栈是 FastAPI LangGraph Redis 向量库可选项这套组合覆盖了前面几个关键决策FastAPI 提供异步 Web 入口LangGraph 提供带控制的编排能力Redis 存会话状态向量库存长期记忆。如果你团队已经选了 Rust 或 Java 生态决策逻辑完全一致换成对应语言的库就行。5.1 FastAPI LangGraph Redis 向量库为什么是这个组合选这套不是因为新而是每个组件都恰好解决一个问题。FastAPI 天然异步符合 Agent 请求的 IO 特性LangGraph 把流程描述成节点和边的图既能写死步骤也能在指定节点上让模型自主决策是当前少有的兼顾可控与灵活的编排层Redis 的 TTL 和数据结构能力适合短期会话状态向量库负责承接跨会话知识检索。比起动不动就引入整套框架我更建议只取需要的部分依赖越少升级时互相打架的概率越低。如果你刚开始可以不接向量库先用 Redis 存一段 JSON 当记忆跑通核心循环后再升级。5.2 一个最小 Agent 的骨架代码与关键注释下面这个骨架实现了一个简单的订单查询 Agent用户问订单状态Agent 判断需要调用 get_order_status拿到结果后生成回答。代码里对应了前面几个关键决策状态按 session 隔离、工具错误结构化回传、循环步数受限、每步记录日志。真实接入时把模型客户端和业务工具替换进去即可。# main.pyFastAPI 入口 LangGraph 编排的最小骨架 import json from typing import TypedDict from fastapi import FastAPI from langgraph.graph import StateGraph, END import redis app FastAPI() r redis.Redis(hostlocalhost, port6379, decode_responsesTrue) TOOLS { get_order_status: { description: 根据订单号查询订单当前状态适合回答物流、发货类问题, parameters: { order_id: { type: string, description: 用户提供的订单号 } } } } class AgentState(TypedDict): messages: list # 当前会话消息 order_id: str | None # 本轮提取出的订单号 remaining_steps: int # 剩余步数对应循环边界决策点 def route(state: AgentState): # 判断是否继续没有工具调用就收尾步数用尽强制结束 if state[remaining_steps] 0: return END last state[messages][-1] if last.get(tool_calls): return call_tool return respond def call_model(state: AgentState): # 这里调用 LLM按决策点二路由到合适的模型 # 响应格式需要包含是否有 tool_calls 参数 ... def call_tool(state: AgentState): # 执行 get_order_status异常转成结构化文本回传 ... def respond(state: AgentState): # 生成最终回答给用户 ... # 构建图call_model - (route) - call_tool 或 respond graph StateGraph(AgentState) graph.add_node(call_model, call_model) graph.add_node(call_tool, call_tool) graph.add_node(respond, respond) graph.set_entry_point(call_model) graph.add_conditional_edges(call_model, route) graph.add_edge(call_tool, call_model) graph.add_edge(respond, END) chain graph.compile() app.post(/chat) async def chat(session_id: str, user_message: str): # 按 session_id 从 Redis 恢复或初始化状态 raw r.get(fsession:{session_id}) if raw: messages json.loads(raw) else: messages [{role: user, content: user_message}] initial_state { messages: messages, order_id: None, remaining_steps: 5, } result chain.invoke(initial_state) r.setex(fsession:{session_id}, 3600, json.dumps(result[messages])) return {reply: result[messages][-1][content]}列出的 api 只是一个最小语义实际项目中你还需要接真实的模型客户端、工具执行逻辑和异常处理。但核心思想已经完整状态从 Redis 进出、工具错误不能裸抛、步数必须封顶。这三点保证了即使模型决策异常服务也不会被打穿。5.3 上线前按这份清单过一遍能省一半的线上事故最后是我每次上线 Agent 前都会过的检查清单不是全都要上但标记必选的别省循环边界max_iterations 是否设置单步是否有超时必选工具契约工具参数是否校验错误是否结构化回传返回是否裁剪必选上下文策略长会话是否走摘要或截断工具返回是否提炼必选记忆隔离会话状态是否按 session_id 隔离并存在 Redis 之类的外部存储必选成本控制每轮和累计 token 是否有日志与告警必选并发保护模型 API 是否限流长任务是否走队列强烈建议人工确认发邮件、下单、删除等敏感动作是否有审批节点按业务定回归测试是否有一组固定测试用例改 Prompt 或模型后自动跑一遍强烈建议这套清单是从我自己的事故里攒出来的尤其是循环边界和工具错误处理几乎九成线上事故都能归到这两类。先把骨架跑通再按清单过一遍再想功能扩展。Agent 工程实现这件事做到能收敛、能观测、可回溯就已经比大多数 Demo 级项目往前迈了一大步。