这两年做应用开发绕不开 AI Agent。很多团队从聊天机器人做起跑通 Demo 很容易但真正进入工程实现阶段才发现问题一个接一个任务一多就失控、上下文一长就失忆、并发一上来就超时最后只能靠人肉盯着日志“陪跑”。这篇文章想把 AI Agent 的工程实现拆开讲清楚核心是两个框架七要素和七个决策点。七要素帮你理解 Agent 内部到底由哪些部分组成七个决策点帮你解决落地时真正要拍板的具体问题。适合正在做 Agent 项目、或者准备从零搭一套生产级智能体应用的开发者读完你至少能知道架构怎么搭、坑在哪、先做什么后做什么。1. 先拆骨架Agent 的七个要素少哪个都会翻车1.1 模型是大脑但别把宝全押在它身上模型是整个 Agent 的推理内核负责理解用户意图、拆解任务、决定用哪个工具。但工程实践里我最大的体会是模型能力只决定 Agent 的天花板工程框架决定它能不能稳定地站在地板上。你模型再强如果后面六个要素没跟上跑几个复杂任务就会开始胡言乱语。选模型时别只看基准测试分数。在 Agent 场景里我更关注三件事一是指令遵循能力也就是你能不能让它严格按照 JSON 格式输出二是工具调用能力模型能不能正确传参这直接决定了 function calling 的可靠性三是上下文利用能力给它 128K 的窗口它到底会用多少、会不会在长文档里迷失。小任务用便宜快速的小模型复杂任务才需要强推理的大模型这是最基础的成本策略。我见过不少团队所有请求都打到同一个旗舰模型上回答质量确实好账单也确实吓人。后面第七个决策点会专门讲成本但你现在就要有这个意识。1.2 指令和上下文提示词也要做工程化设计提示词在 Agent 里不是写一段“人话”告诉模型该干什么就完了它是一段需要结构化设计的代码。我的习惯是把它分成四块系统指令、任务说明、工具说明、输出约束。系统指令定义身份和边界任务说明描述当前要完成的目标工具说明告诉模型有哪些能力可以用输出约束规定回答的格式和参数。这里最容易犯的错是“什么都要写进提示词”。上下文越长模型注意力被稀释得越厉害关键指令往往被埋在无关信息里。我调试过很多失败的 Agent最后发现问题不是模型笨而是提示词里写了两百行“你可以这样做你也可以那样做”模型就真的随机发挥了。所以提示词工程化的第一步是做减法把不变的部分抽出来把每次变化的参数填进去。还要注意提示词的版本管理。代码有 git提示词更得有。我踩过最痛的一次坑是上线的 Agent 突然大面积返工排查半天才想起来前一天手改了一段输出格式说明。从那以后所有提示词的改动我都要求走评审加记录和代码变更同样对待。1.3 记忆短期会话与长期知识要分库管理记忆是 Agent 和普通问答最显著的区别。没有记忆的 Agent 是个失忆患者用户上一轮说的是什么它转头就忘更别提跨会话的个性化。但很多人的实现就是把所有聊天记录都塞给模型这样既贵又乱而且很快会触到上下文上限。合适的做法是把记忆分成短期和长期两层。短期记忆保存当前会话的对话历史和中间状态通常跟着会话存过期自动清理长期记忆保存用户的偏好、历史任务、领域知识一般抽成结构化数据或者向量入库需要时再检索出来喂给模型。做长期记忆要非常克制。不是所有信息都值得存存多了既占存储又污染检索。我在项目里常用的策略是设置“记忆写入门槛”只有模型判断为重要的事实或偏好才写入长期记忆其余的一律不落库。这听起来像多了一次模型调用但换来的检索精度和记忆质量是值得的。1.4 工具Agent 能干活的关键卡在协议如果说模型是大脑工具就是手脚。Agent 里的工具可以是查询库存的接口、发送邮件的服务、操作数据库的 SQL、甚至调用另一套系统的 API。工具让 Agent 从“会说”变成“能办”也是工程实现里最见功力的一部分。工具接入有两个层次的问题。第一层是协议层也就是模型如何决定调用哪个工具、参数怎么传目前业界的主流做法是 function calling模型按照你定义好的函数签名生成调用意图你的系统负责执行并返回结果。第二层是语义层模型的泛化能力意味着用户可能用一千种说法表达同一个意图你的工具描述写得越清楚模型选错工具的概率就越低。工具不是越多越好。工具一多模型选择的难度指数级上升还容易因为参数混淆调用错误。我在项目里做过一次工具收敛把二十多个零散函数合并成六个语义完整的工具集合调用准确率反而升了十来个点。工具数量的“少而精”比“大而全”重要得多。1.5 规划任务拆解的正确打开方式简单 Agent 可以只做一步比如用户问天气模型调用天气接口回答。但真正的业务场景往往需要多步操作比如“帮我把上周的销售数据整理成周报并发给团队”这里至少涉及查数据、汇总分析、生成报告、找收件人、发邮件五个步骤。模型自己决定动态执行每一步这就是规划能力。Agent 圈最常见的两种规划思路是 ReAct 和 Plan-and-Execute。ReAct 是边想边做模型每走一步都观察结果再决定下一步灵活但费 Token 且容易跑偏。Plan-and-Execute 是先让模型把任务拆成一串子任务然后按计划执行执行的过程中再根据结果微调计划。工程上我建议复杂任务走 Plan-and-Execute因为可预期、好调试子任务的执行结果可以单独追踪。规划还有一个关键工程点超时和循环检测。模型在规划时偶尔会陷入死循环同一个动作反复执行。我会在循环里加一个最大迭代次数的硬上限比如 15 次超过就强制中断并请求用户确认。这个上限在开发和上线阶段能救你很多次。1.6 执行与反馈最容易低估的一环规划得再好最终都要落到执行。执行层要处理的问题非常具体工具返回了错误码怎么办、第三方接口超时怎么办、执行结果不符合预期要不要重试。这一步做得好不好决定了 Agent 是“能用”还是“能看”。我见过很多团队把精力全放在提示词和模型调优上忽略了执行层的健壮性设计。结果就是 Demo 环境跑得飞起一接真实系统就各种失败。真实的工具调用有延迟、有错误、有返回格式不统一执行层必须把这些噪音消化掉。反馈机制是这里的关键。工具执行完成之后不能只拿一个“成功”就把结果抛给 AI而应该返回结构化的执行结果包括数据内容、状态标识、错误信息。模型拿到这些反馈才能判断下一步该怎么走。一套好的反馈机制要让 Agent 在失败时能够自我修复而不是直接崩溃给用户看。1.7 护栏上线前必须补的一课前面六个要素决定 Agent 能做什么护栏决定它不能做什么。护栏的核心是权限控制和输出校验。Agent 调用工具时要检查权限边界比如普通用户的会话是不是动不了管理员的删除接口回答用户之前要做一次输出校验比如模型生成的 JSON 格式是不是合法、内容有没有涉敏信息。我建议把护栏做成独立的判断层不要写死在业务代码里。原因很简单Agent 的行为空间太大你需要在它做出危险动作之前拦截。举个实际例子我们的客服 Agent 在跟用户闲聊时生成过一条修改订单状态的指令幸好权限校验层及时发现这个操作超出了当前会话权限直接拒绝了。没有这层护栏后果就是线上事故。护栏不只是拦截危险还包括优雅降级。模型调用失败的时候是直接报错还是告诉用户“系统繁忙请稍后再试”体验差别很大。我在系统里加了一个兜底响应模块检测到异常就切到预设话术至少不会让用户对着一个空白屏幕发呆。2. 七个决策点动手前想清楚能少走两个月弯路七个要素讲的是 Agent 的构成真正动工时你要在七个维度上做取舍。下面这张表是我给项目的检查清单每一项都对应一个必须明确的决策。决策点对应要素核心问题模型选型模型用哪个模型做主脑备用模型是谁Token 预算记忆、上下文一次任务最多能吃多少输入超出怎么办并发设计执行、反馈同时跑多少个 Agent 任务峰值怎么扛状态持久化记忆、规划任务状态放内存还是数据库重启后能不能恢复可观测性执行、反馈你看不看得到 Agent 每一步在干什么评估与安全护栏、规划用什么标准判断 Agent 做得好不好成本与迭代全部每次任务花多少钱模型升级怎么切换2.1 模型选型基准分数高不等于生产好用模型选型的第一个误区是唯排行榜论。排行榜上的分数测的是单轮问答能力跟生产环境里的 Agent 表现相关性有限。我实际使用下来有些开源模型在某些工具调用场景的成功率还不如少 20 个参数的商业模型这种差异要拿你自己的业务数据去测不能靠榜单拍板。我的建议是分任务选模型。做一个意图识别模块只要快速、便宜、准确率高小模型就够做复杂文档分析、多步推理才值得上大模型。还有一个容易忽略的点是模型切换的应急预案主模型供应商万一出了故障或者接口涨价你必须有可替代的无损切换方案。判断标准最好量化。我在每次模型选型测试里固定跑一套自己的评测集五十条真实业务问题统计最终任务成功率、平均轮数、工具调用准确性三个指标。这比五花八门的榜单分数有用得多你可以照这个思路建自己的 mini 评测集。2.2 Token 预算搞懂“AI Agent token 是什么意思”“AI Agent token 是什么意思”这个问题很多人问过。Token 是模型处理文本的最小单位你可以简单理解成一个词或者半个词模型按 Token 计费也按 Token 上限处理上下文。Agent 跑一个任务要多次调用模型每次调用都要把历史、提示词、工具输出重新算一遍 Token所以消耗会比想象中快很多。我在项目里给每个 Agent 任务设了明确的 Token 预算。举个例子假设上下文窗口是 8K我会这样分配系统指令和任务说明固定占 1.5K工具描述占 2K剩余 4.5K 留给对话历史和工具返回结果。历史太长就做摘要压缩工具结果太大就截断关键字段绝不让单次请求触顶。Token 管理的本质是成本管理和质量管理的双赢。你给模型的输入越精炼它越能把注意力放在当前任务上输出质量也越高。我见过一个生产事故就是没做 Token 预算长时间的会话把历史全量塞入模型直接“忘了”系统指令开始输出一些不受控的内容。从那以后Token 预算是我们所有 Agent 上线前的硬性检查项。2.3 并发AI Agent 怎么扛并发“AI Agent 怎么扛并发”是工程师问得最多的问题。这里头有个认知要纠正Agent 不是一次 HTTP 请求拿到最终结果那么简单它内部可能调了十几次模型和外部工具每一个动作都有延迟。如果用户请求一多直接用同步方式处理线程池一秒就被打满。正确的思路是异步化加任务化。用户的请求进来先创建一个任务返回 task_id后台用队列慢慢跑用户可以轮询任务状态。这样做的核心原因有两个一是把长耗时操作从 HTTP 请求里剥离出去服务不会被慢请求拖垮二是 Agent 任务天然适合并行调度多个用户任务可以并发消费队列。生产环境里我还会加两层保护信号量限流和模型调用排队。信号量限制同时最多跑多少个 Agent 实例防止瞬时大流量把下游和模型接口打爆。模型调用排队是为了防止超时雪崩所有并发请求先进队列按最大并发数出队宁可让任务慢几秒也不能让所有请求同时超时。2.4 状态持久化与编排框架选型Agent 的执行过程是一个多步状态机从“等待输入”到“规划中”“执行中”“完成”“失败”每一步都有中间结果。这些状态如果只放内存服务一重启全部消失。生产环境一定要做持久化最轻量的方案是把状态存 Redis重启后还能恢复任务量大的时候可以把历史步骤存数据库方便回溯和排查。编排框架的选择也在这里定。我个人的经验是简单 Agent 用代码自己写循环就够了别急着上框架多步任务和有条件分支的任务用 LangGraph 这类图编排框架很合适它把条件转移、循环、并行都变成了显式的图结构调试起来直观得多。技术栈上有人问基于 Rust 的 AI Agent 能不能用。Rust 社区已经有 Agent 框架在成长性能好、内存安全但生态成熟度和 LangChain、Spring AI 这类老牌框架比还有差距。如果你团队本来就是 Rust 技术栈可以尝试否则别为了性能换语言Agent 的瓶颈通常在模型响应时间和业务逻辑复杂度不在语言层。2.5 可观测性让 Agent 真的下地干活的前提让 AI Agent 从“能跑”变成“能干活”可观测性是我认为最重要的一件事。Agent 是个黑盒模型为什么做了这个决策、调了什么工具、拿到了什么结果你全都看不到的话出了问题就只能靠猜。调试 Agent 和调试普通代码不是一个难度普通代码是确定的Agent 是概率性的。我会在每次模型调用时记录完整链路输入 prompt、生成的中间输出、选择的工具、工具返回值、最终答案全部打点存日志。同时给每次任务生成一个 trace_id贯穿整个 Agent 执行过程。排查问题的时候按 trace_id 一查所有步骤一目了然比看业务日志效率高一倍不止。更进一步的方案是可视化回放。LangGraph 这类框架支持把状态图渲染出来你可以看到任务停在哪个节点、为什么走了这条分支。我调过一个失败的 Agent就是靠回放发现模型在某个条件下反复调用同一个工具根本没有进入终止分支。这个问题不看到状态图光靠日志很难发现。2.6 评估与安全没有评测上线等于裸奔很多团队把 Agent 上线当成普通功能发布跑通几个例子就上了这是最危险的做法。普通代码的行为是确定的Agent 的行为是概率性的你可能跑一百次都正常第一百零一次突然答非所问。所以没有一套评测体系Agent 上线就等于裸奔。我建议组一个业务评测集不求大但覆盖面要广。把典型场景、边界场景、危险场景各写几十条每次改动代码或提示词以后跑一遍完整回归。指标不要只盯着“回答正确率”还要看任务完成率、工具调用准确率、平均轮数、超时率这些工程指标。安全评测也要纳入流程。我会单独准备一组对抗样本专门测 Agent 会不会被诱导执行越权操作、会不会输出危险内容、会不会在工具调用时传错关键参数。这组样本每个版本都要跑把安全风险控制在发布之前。2.7 成本与迭代不只看一次推理多少钱Agent 的成本不能只看一次模型调用的单价要看完成一个任务的总成本。一个 Agent 任务可能触发五次模型调用每次调用还要带上历史记录Token 消耗翻倍是常有的事。我见过一个看似便宜的小模型因为任务失败率高、重试次数多实际成本反而比大模型还贵。控制成本的手段主要有三个缓存、降级、摘要。对重复的模型调用做缓存比如同样的问题和同样上下文就直接返回历史结果对不重要的任务降级到更小的模型对长时间会话做历史摘要压缩每次调用的输入 Token。这三板斧用下来我们的成本降了将近一半任务质量没有明显下降。成本决策还要和迭代绑定。模型迭代很快一个模型几个月就会出更强的新版本。我建议在系统里做一层模型适配层把模型调用封装成统一接口切换模型只改配置不动代码。这样每次模型升级你都能快速做 A/B 对比选产出更优的那一个而不是被供应商锁死。3. 实操用 FastAPI LangChain LangGraph 搭一个能下地干活的 Agent3.1 最小闭环设计计划、工具、执行、反馈讲完理论给一个能直接照抄思路的最小实现。我们假设场景是“客服工单助手”用户说“查询订单 10086 的物流状态”Agent 需要调用查单工具并返回结果。整个链路用 FastAPI 做服务入口LangChain 做工具封装LangGraph 做状态编排。第一步是设计状态图。状态里至少要有当前消息、历史消息、工具结果、最终回答。LangGraph 的典型写法是定义一个状态类型然后添加节点比如parse_intent节点解析意图call_tool节点调用查询工具generate_answer节点生成最终回答每个节点之间通过条件边连接形成一个循环结构。from langgraph.graph import StateGraph, END class AgentState(TypedDict): messages: list tool_result: str answer: str graph StateGraph(AgentState) graph.add_node(parse_intent, parse_intent) graph.add_node(call_tool, call_tool) graph.add_node(generate_answer, generate_answer) graph.add_edge(parse_intent, call_tool) graph.add_edge(call_tool, generate_answer) graph.add_edge(generate_answer, END)这个图简单到有点玩具但它已经具备最小闭环意图解析后调用工具拿到工具结果再生成回答。你要做的就是在这个骨架上加条件分支和循环控制。FastAPI 外层暴露一个异步接口收到请求后把任务丢给后台执行器立即返回 task_id客户端再通过另一个接口轮询结果这一步就把前面讲的并发问题解决了。3.2 Tool Schema 的写法与 function calling 坑点工具封装是这里最容易出错的地方。LangChain 里定义一个工具重点是写好函数签名和 docstring因为这些会直接转成模型能读到的 function schema。参数描述要写清楚含义、类型、取值范围比如“order_id 是字符串类型的订单号格式为数字长度为 5 到 10 位”描述越具体模型传参越准。from langchain.tools import tool tool def query_logistics(order_id: str) - str: 查询订单物流状态。 Args: order_id: 用户订单号字符串一般由数字组成。 Returns: 物流信息文本。 return logistics_api.query(order_id)我踩过的一个大坑是工具返回的数据结构太复杂。模型拿到一个几百行的 JSON判断“这单是否已签收”都费劲因为很难从一大段嵌套数据里精准抽取状态。后来我改成在工具内部做一次解析只返回精简结果比如{order_id: 10086, status: delivered, message: 已签收}。模型处理起来明显轻松回答也更准确。记住工具返回给模型的不是原始数据而是它决策需要的信息。另一个坑是工具描述写得太口语化。比如“查一下订单到哪了”模型可能理解成发一个搜索请求而不是调用查询工具。工具描述要用稳定的结构化语言同时多给一个典型示例比如“当用户询问物流状态时调用此工具”。这些细节直接决定工具调用的成功率。3.3 多 Agent 与协作什么时候拆子 Agent单 Agent 处理不了太复杂的任务时大家很自然会想拆成多 Agent。多 Agent 架构确实强大但也是过度设计的重灾区。我的判断标准很简单如果任务可以串行描述成一步接一步的流程就用单 Agent 加规划如果存在多个可以并行处理、彼此相对独立的子任务才拆多 Agent。比如一份报告要同时查销售数据和市场数据两个查数任务互不相关可以并行。拆多 Agent 的工程复杂度比单 Agent 高很多。每个子 Agent 都有自己的状态、上下文和工具集Agent 之间怎么通信、怎么共享记忆、怎么汇总结果都需要设计。LangGraph 里可以用子图的方式组织这些 Agent主 Agent 负责调度子 Agent 负责干活父级只传递必要信息。这里我想特别强调一点多 Agent 不是性能优化的手段。有人觉得多 Agent 能并行、速度快但每个 Agent 都是模型调用整体消耗反而更高。多 Agent 解决的是职责边界的问题不是速度问题并发提速应该靠任务队列和异步执行不要靠拆 Agent。3.4 部署层面的并发处理部署这一步很多人把 Demo 直接扔到线上结果一上线就出洋相。Agent 应用部署时要额外考虑三件事超时时间、任务队列、结果存储。HTTP 层不能同步等待 Agent 跑完再返回因为一个任务可能几十秒网关早超时了所以前面说的 task_id 模式是必须的。FastAPI 后台任务的实现可以用简单的线程池或者 Celery。线程池适合中小流量每个 Agent 实例本身是 I/O 密集型的因为大部分时间都在等模型响应线程池不会浪费太多资源。如果流量大、任务多再上 Celery 这类分布式队列把任务分发给多个 worker 消费。from fastapi import FastAPI, BackgroundTasks app FastAPI() app.post(/agent/task) async def create_task(request: TaskRequest, background_tasks: BackgroundTasks): task_id uuid4().hex background_tasks.add_task(run_agent, task_id, request) return {task_id: task_id} app.get(/agent/task/{task_id}) async def get_task(task_id: str): return get_task_result(task_id)结果存储建议用 Redis 的 KV 结构以 task_id 为 key 存任务状态和结果设置过期时间防止数据堆积。任务跑完以后前端轮询到这个状态就展示结果。这套模式简单、够用也是目前最常见的 Agent 服务架构。4. 高频问题与避坑实录从并发、Token 到技术栈4.1 个人使用 AI Agent 做自动化交易可行吗“个人使用 AI Agent 可以做期货交易吗”这个问题我经常看到有开发者在技术社区反复确认。从纯技术角度说完全可行Agent 能接行情、分析数据、生成交易信号、自动下单。但我要给你泼一盆冷水这不只是一个技术问题更是一个风险控制问题。Agent 的决策是概率性的它可能在 95% 的情况下表现正常但剩下的 5% 足以造成严重亏损。交易场景对延迟、安全性、可靠性的要求极高现在 Agent 的推理能力和稳定性还远不到能全天候自动交易的程度。我不建议任何人拿真金白银直接跑全自动交易 Agent至少也要设计人工确认环节每次交易信号都由人来决定要不要执行。如果你真的想实验建议先用模拟盘同时把 Agent 的所有决策全程记录。这样你可以验证它的策略和稳定性而不是拿模拟盘当游戏至少确保出了问题还能复盘。这个领域不是模型能力的问题而是你愿不愿意接受概率性失误带来的后果。4.2 用 AI Agent 自动发布内容合规与权限怎么处理“让小红书自动发消息”这种自动化需求核心不是技术而是权限和合规。技术层面Agent 完全可以做到定时生成内容、调用发布接口、自动回复私信。但从工程角度我要提醒你自动发布内容的 Agent 必须设计人工审核闸门不能让模型生成什么就发什么。我见过一个自动化运营系统的教训模型生成了一条促销文案里面引用了一个不存在的产品折扣“自动发布”功能直接把这条文案发出去了最后客户投诉、运营救火。从那以后所有对外内容的发布流程都加了一道人工确认步骤Agent 负责生成和拟稿人来负责最终点击发布。权限设计上还有一个隐藏问题Agent 自动操作的账号如果权限过大一旦被恶意提示词诱导就可能执行危险操作。比如用户对客服 Agent 说“帮我给我自己开个管理员权限”如果 Agent 背后的工具权限没有收紧这就是事故。自动发消息类的应用所有工具权限都要遵循最小化原则。4.3 Django、Spring AI、Rust 生态怎么选技术栈选择的问题很现实。用 Django 做 Agent 能不能行完全可以Django 的 ORM 和管理后台能力很强适合快速搭建业务系统Agent 只是其中的一个模块。FastAPI 的优势在异步和轻量跟 Agent 这种天然适合异步化的场景更搭所以我个人的习惯是 FastAPI 做服务层。Java 团队用 Spring AI 是个合理选择它跟 Spring Boot 生态无缝集成企业服务里的用户体系、数据库、消息队列都是现成的。我之前给一个老项目接入 Agent就是 Spring AI 起步的好处是企业内部已有的体系不用推倒重来学习成本主要集中在 Agent 的概念上。Rust 的 Agent 框架确实是未来可期的方向性能优势和内存安全很吃香但现阶段工具链和资料相对少。我的建议是如果你不是 Rust 技术栈的老手别为了 Agent 单独引进 Rust如果你的团队本来就靠 Rust 吃饭可以关注相关的 Agent 框架进展做点技术预研是值得的。4.4 从零开始的 AI Agent 学习路线经常有人问 AI Agent 学习路线我的建议是从“用”到“拆”再到“造”三段走。第一阶段先用现成的平台像扣子这类工具搭建一个简单 Agent不写代码理解规划、工具、知识库这些概念是怎么组合的。很多开发者跳过这一步直接写代码结果概念都没理顺代码写得再花也是空中楼阁。第二阶段用 LangChain 加一个模型 API 完成最小闭环实现一个带工具调用的 Agent。这一步的关键是理解 function calling 和状态流转你可以把前面客服工单的例子自己敲一遍改不同场景看错误日志是怎么产生的。不要一上来就追多 Agent、记忆、复杂图编排先把单 Agent 搞透。第三阶段深入研究 LangGraph 这类编排框架再逐步加上记忆、评测、可观测性。往后再去读云厂商发布的 AI Agent 白皮书、社区里的架构文章这时候你已经能分辨哪些内容是真实的工程经验哪些是在画饼。不需要收藏一堆教程把这一套路线走完你已经有能力写自己的生产级 Agent 了。我个人做 Agent 项目这几年最大的体会是卡住你的往往不是模型不够聪明而是你没有一个可靠的状态管理、反馈闭环和评测体系。先把一个简单任务跑通把每一步的日志和状态都记录下来然后再往里面加复杂功能。最后再分享一个小技巧动手前先固定工具的输入输出格式再去调提示词。工具协议没定下来就反复调 prompt后面大概率要返工重来。Agent 工程化是一场持久战但把七个要素和七个决策点想清楚路会好走很多。