简介：这是一份系统梳理美团大模型Agent落地经验的技术手册，面向大模型应用开发工程师、业务技术负责人及关注Agent工程化的读者。手册从基础认知到未来展望共分八章，既详解龙猫大模型（LongCat-Flash-Chat）核心架构、模型训练流程与能力评估矩阵，也覆盖外卖、到店、酒旅、共享单车四条业务线的实际案例，并完整拆解需求分析、数据准备、模型微调、Agent架构设计与测试优化等开发环节。工程化部分重点涉及工具链、监控运维、安全合规，并通过评估指标、A/B测试与避坑指南帮助读者规避常见问题。资料为单个PDF文件，大小753KB，已有179人学习下载，章节结构清晰、内容详实，便于按章节查阅，适合需要系统掌握大模型Agent从设计到落地全链路方法论的开发者与决策者，完整呈现从技术原理到业务落地的全貌。
1. 美团大模型 Agent 实践手册：为什么外卖场景比通用对话更考验 Agent
做过几年 LLM 应用落地的人都有个体会：通用聊天 Agent 跑通 demo 容易，真放进业务流里就开始翻车。美团这类业务的核心矛盾在于，Agent 要同时面对实时库存、骑手位置、用户情绪、商家出餐速度这些硬约束，而不是单纯比谁话接得漂亮。所谓大模型 Agent 实践手册，讲的正是怎么让模型在真实履约链路里做决策、调工具、背责任，而不是只当个会聊天的黑匣子。
这本手册的价值不是给你看几个提示词模板，而是把 Agent 从「模型 + 工具调用」的玩具组合，推向「目标管理 + 记忆分层 + 工具编排 + 失败兜底」的工程系统。适合已经在做企业级大模型应用、受限于单轮问答想往上走一层的人，也适合刚接触 Agent 架构、想搞清楚框架层和业务层边界的新手。下面按我自己的落地顺序展开：先立架构认知，再讲记忆与工具，接着是数据回流，最后给出踩坑清单。
2. Agent 架构选择：从 ReAct 到 Plan-and-Execute 的工程分界
2.1 ReAct 在小步快跑场景的适用边界
常见做法是先从 ReAct 范式起步。Reasoning 和 Acting 交替进行，模型每轮先想「我要查什么」再调工具，然后把工具结果拼回上下文继续推理。美团内部很多客服问答、售后处理类 Agent 早期都是这个结构，因为实现成本最低，一个循环、两个 Prompt、三五个工具就能跑通最小闭环。
但 ReAct 有个天然缺陷：它是局部最优的贪心搜索。模型每一步只根据当前上下文决定下一步，缺少全局任务视图。比如用户说「帮我取消订单并退款」，Agent 先调了取消接口，然后发现退款依赖支付渠道参数，这时上下文已经被取消结果占满，容易忘记补充询问用户原路退回还是退回卡包。这个小分支在 ReAct 里就是常见的丢上下文事故。
我一般在两种情况下仍然选 ReAct：一是任务步骤少且线性，二是工具数量不超过 5 个。超过这个规模，推理步数会指数级膨胀，模型每多一步就多一次判断失误的机会。这时候 Plan-and-Execute 更合适，也就是先拆解计划，再逐步执行，每步执行完毕后检查是否有条件分支要插入。
2.2 Plan-and-Execute 的主循环拆分
Plan-and-Execute 把 Agent 拆成两个模型调用层。第一层是 Planner，负责把用户意图转成有序子任务清单；第二层是 Executor，针对每个子任务调用相应工具并把结果返回给 Planner。美团这类业务场景里，Planner 还要多理解一层「渠道差异」——外卖、到店、闪购的用户意图和工具集并不完全一样。
一个简化版 Planner 提示词结构如下：
planner_prompt = """ 你是美团业务场景的任务规划器。将用户请求拆解为可执行的子任务列表。 每个子任务必须包含：任务ID、操作类型（query/update/confirm）、依赖的前置任务ID、所需工具名。 输出JSON数组，不要输出额外文字。 已知工具： - query_order(order_id) - query_refund_policy(order_type) - apply_refund(order_id, amount, channel) - notify_user(user_id, message) 用户请求：{user_input} 约束：退款金额不能超过订单实付金额；取消订单前必须先检查出餐状态。 """这里的关键不是让模型「想得更深」，而是把业务约束直接写进规划层。出餐状态检查、退款上限这类校验，如果放到 Executor 里做，每个工具都要重复判断；放在 Planner 里做，约束只维护一份，执行层只管调用。
参数上我通常把 temperature 压到 0.2 以下，因为规划任务需要确定性输出。top_p 保持 0.9 左右，没必要太激进。输出格式强制 JSON 也能省掉后续解析的容错代码。
2.3 单一模型还是多模型分工
做 Plan-and-Execute 时，一个常被问到的问题：Planner 和 Executor 用同一个模型还是分开？从成本角度，Planner 对推理要求高但调用频次低，Executor 对延迟敏感但逻辑简单。我见过美团系开源分享里提到，Planner 会用更大参数的模型，Executor 则可能用量化版小模型，因为工具调用只需要抽取参数和格式化请求体。
不过这个方案需要额外维护两套模型的上线与评测流程，对小团队来说负担偏重。我自己在早期版本里直接用同一个模型跑两个角色，只靠提示词区分，效果也不差——毕竟 Planner 的输出接下来还要被 Executor 校验，模型能力不足时 Executor 的失败率会反过来暴露 Planner 的问题。等到工具数量超过 10 个、任务类型拉开明显差距后，再拆模型也不迟。
3. Agent 记忆机制：会话记忆、长期记忆与业务侧写
3.1 上下文窗口不是记忆
很多刚接触 Agent 的人把记忆等同于上下文窗口。模型上下文能装多少 token，就以为 Agent 能记住多少事。这在简单的 QA Agent 里勉强成立，但落到业务型 Agent 就出问题：美团场景中，用户的历史订单、投诉记录、偏好口味、地址变化，这些信息如果全量塞进上下文，既浪费 token 又稀释注意力。
正确做法是把记忆分层。会话记忆负责当前轮对话中的临时信息，用滑动窗口管理；长期记忆负责跨会话的用户画像和业务事实，通常存向量库或 KV 库；工作记忆则指当前任务执行中的中间状态，比如退款审批流走到哪一步了。分层的关键是：哪层的信息需要被模型看到，由路由策略决定，而不是由长度决定。
3.2 长期记忆的写入与召回策略
长期记忆写入不能来一条存一条，那样噪音太多。我一般会给记忆打三个标签：事实型（用户地址、手机号）、偏好型（微辣、不要香菜）、事件型（上次投诉未解决）。召回时按任务类型筛选：订单类任务优先召回事实型和事件型，推荐类任务优先召回偏好型。
召回策略上值得注意的一点是：时间衰减要比相似度更重要。用户三个月前爱吃辣，最近两周订单全是清淡口味，向量相似度可能仍然跟「爱吃辣」接近，因为口味偏好文本本身变化不大。因此召回打分时我会加上时间半衰期权重，公式可以简单写成 score = sim * exp(-days / half_life)。half_life 按记忆类型不同取值，偏好型设 30 天，事件型设 7 天，事实型不做衰减。
3.3 写入时机与遗忘机制
记忆不是每轮都写。常见判断规则是：用户显式表达的需求变化必须写；Agent 推断出的偏好要等用户确认后再写；一次会话内重复出现两次以上的信息可以降级为候选记忆，不立即固化。这样可以避免模型胡说八道的内容污染长期记忆。
遗忘机制同样不能省。给每条记忆维护一个 last_access_time 和 access_count，定期离线任务把长期未命中的低价值记忆降级为冷存储，甚至删除。美团这类高频交易场景里，用户的地址会变、口味会变、甚至收货人姓名都会变。如果不做遗忘，旧记忆与新记忆冲突时，Agent 会陷入左右互搏。
def recall_memory(user_id, task_type, top_k=5): # 先按类型过滤 candidate = db.query( "WHERE user_id = ? AND memory_type = ? AND status = 'active'", user_id, task_type ) # 再按时间衰减加权 now = time.time() scored = [] for mem in candidate: age_days = (now - mem.last_updated) / 86400 decay = math.exp(-age_days / mem.half_life) sim = embed_similarity(mem.content, task_query) scored.append((mem, sim * decay)) scored.sort(key=lambda x: x[1], reverse=True) return [mem for mem, score in scored[:top_k]]这段代码里，task_query 是当前任务的语义表示，embed_similarity 用现成的 embedding 接口即可。注意 candidate 要先按类型过滤，否则全量记忆做相似度计算的成本会随用户历史线性增长，在线服务扛不住。
4. 工具调用的工程化：参数抽取、校验与失败重试
4.1 工具描述的结构化设计
Agent 的工具调用本质上是让模型输出一个结构化意图，后端再做参数映射。很多团队栽在第一步：工具描述写得太像人话。比如「query_order(id)」这种描述，模型知道这是查订单，但不知道 id 要从用户原话的哪个位置抽取。正确的做法是给每个参数写清楚来源、格式和示例。
{ "name": "query_order", "description": "根据订单ID查询订单详情，包括商品、金额、配送状态", "parameters": { "order_id": { "type": "string", "description": "用户提供的订单号，通常为数字串，可从用户消息中直接抽取", "example": "2025030112345678" } } }参数描述越具体，模型抽取的准确率越高。特别是枚举值，比如退款渠道参数只允许「original」和「balance」，一定要写进 description 里，否则模型可能自由发挥出第三种值。美团场景中订单号、门店 ID、商品 SKU 这类标识符本来就长，模型容易漏位或串位，因此还要在后端做格式校验。
4.2 工具调用的三重校验
模型输出的工具调用，不能直接拿去执行。至少要做三重校验：第一重是格式校验，参数是否齐全、类型是否正确；第二重是业务校验，比如退款金额是否小于等于实付金额、取消订单前订单状态是否允许；第三重是安全校验，比如目标用户是否有权限操作这笔订单。
安全这块容易被忽略。Agent 很容易被诱导修改他人订单，因为模型本身不理解「这个用户和这个订单的所有权关系」。我处理的办法是把所有权判断做成工具内部逻辑，而不是期望模型自己推理。工具函数先查订单归属，再决定是否继续，这样即使模型乱调参数，也执行不到越权操作。
def apply_refund(order_id, amount, user_id): # 校验订单归属 order = get_order(order_id) if order.user_id != user_id: return {"status": "denied", "reason": "order_ownership_mismatch"} # 校验金额上限 if amount > order.paid_amount: return {"status": "denied", "reason": "refund_exceeds_paid"} # 通过后再调真实退款接口 return refund_api(order_id, amount)这种带校验的封装层，是 Agent 落地和纯研究 demo 的分水岭。模型是否可靠，业务方不会只看工具调用的成功率，更看重「不该调的时候不会被调起来」。
4.3 失败重试与兜底策略
工具调用一定会失败：接口超时、参数错误、业务规则拦截。失败后是否重试、重试几次、重试后仍失败怎么办，这些策略直接影响用户体验。常见做法是分两类失败：一类是可重试的瞬时故障，比如网络超时、服务端 5xx；另一类是不可重试的业务拒绝，比如退款金额超限、订单已关闭。
可重试故障我一般加指数退避，初始延迟 1 秒，最多重试 2 次。不可重试的业务拒绝，应该让 Agent 把错误信息转译成用户能听懂的话，比如「您的订单已超过可退款时间，无法发起退款」。这里有个坑：模型容易把错误码原样抛给用户，用户看到「refund_exceeds_paid」一脸懵。所以工具的返回要带上用户可读的 message 字段，Agent 的输出策略里也加一条规则：优先使用工具返回的 message，不自行编造原因。
5. Agent 的数据回流与评测：没有真实样本的 Agent 走不远
5.1 每轮对话都值得留痕
做 Agent 和做传统模型一样，没有数据就没有迭代空间。很多团队上线 Agent 后只看日志里的报错，忽略了完整的会话轨迹。事实上，Agent 的每轮交互都应该记录下来：用户输入、规划结果、工具调用与返回值、模型最终回复、用户是否追问或投诉。这些数据不仅是事后排查的依据，更是后续微调或 few-shot 示例的原料库。
我习惯的存储结构是 JSONL，一行一个会话，内含 event 序列。关键字段包括事件类型、时间戳、输入输出、Token 消耗、延迟。这批数据经过脱敏后，可以定期产出三张统计表：工具调用成功率、规划步骤有效率、最终回复的用户满意度代理指标（如是否有追问、是否有投诉）。
5.2 评测集的三类样本构成
Agent 评测不能只看端到端成功率，因为端到端通过率高可能只是场景简单。我会把评测集分成三类：基础能力样本、边界条件样本、对抗性样本。基础能力样本来自正常用户请求，覆盖各业务线主流程；边界条件样本包含金额为零、订单已取消、库存不足这些异常分支；对抗性样本则是恶意诱导、角色扮演、参数混淆之类。
边界条件样本最能暴露 Agent 的工具校验是否扎实。比如用户说「帮我把 3 月 1 日的订单退款」，模型可能把 3 月 1 日解析成日期参数，但订单绑定在不同月份。评测时要把这类场景专门拎出来看，不能放进整体准确率里被稀释。
5.3 回归测试与 Prompt 版本管理
Agent 的迭代比传统模型快，因为改 Prompt 比重新训练容易得多。但改 Prompt 的副作用也大：可能解决了场景 A，却破坏了场景 B。所以每次调整 Prompt 或工具描述后，都要跑一遍完整评测集做回归。
版本管理方面，Prompt 和工具描述应该进 Git，每次改动关联对应的评测报告。很多团队把 Prompt 写在代码里，一改就上线，完全没有回滚依据。事实上，Prompt 就是 Agent 的「模型权重」，它和代码一样需要版本化和评审流程。
我一般会把评测集拆成当日快速回归集和全量周回归集。快速回归集选 30 条最高频场景，每次改动后跑一遍，十分钟内出结果；全量集每周跑一次，验证长尾场景没有劣化。这样既能快速响应业务侧的 Prompt 修改请求，又不会被回归成本拖垮。
6. 常见问题排查：Agent 翻车现场的 5 条血泪经验
6.1 工具调用成功的百分比不低，用户满意度却在掉
现象：后台统计工具调用成功率接近 95%，但用户投诉率上升，差评集中在「答非所问」。
原因：工具调用成功不等于任务目标达成。比如查到了订单状态，但用户真正问的是「为什么还没送到」，Agent 只回答了「订单配送中」，没有结合骑手位置和预计送达时间给出解释。这个差异是工具选择和回复组织层面的问题，不是工具执行的问题。
解决：给每个工具加一层「目标对齐检查」——模型在回复前，先判断工具返回结果是否回答了用户的隐含诉求。另外，回复生成时要把工具结果重写为用户关心的自然语言，而不是直接拼接字段。
6.2 模型反复调用同一个工具，陷入死循环
现象：Agent 在某个节点反复调用查询接口，每次返回都一样，但 Agent 仍然不结束任务。
原因：模型无法从工具结果中判定「任务已完成」。常见于工具返回缺少终态标记，或者 Planner 没有设定终止条件。查询类工具的返回结构里，如果没有明确的状态字段，模型会认为还需要继续确认。
解决：工具返回 JSON 中增加task_complete_hint字段，明确告诉模型「这个结果已经足够回答用户」。同时，在 Planner 提示词里写死终止条件：「当所有子任务均完成且无异常时，输出结束标记」。
6.3 新工具加入后，老场景开始说胡话
现象：一次新增发票查询工具之后，订单退款场景的准确率掉了一截。原因：模型的工具选择空间变大，在模糊用户意图时更倾向于多猜一步。比如用户说「这笔订单有问题」，以前 Agent 直接去查订单状态；现在可能先查发票，因为工具名里「发票」和「订单」在语义上关联度不低。这是候选工具增多导致的注意力分散。
解决：在工具描述里加大「适用场景」权重，明确写「仅当用户提到报销、发票时才使用」。更稳妥的做法是给工具分组，每组只暴露在当前业务路由下，而不是把所有工具一次性全给模型。
6.4 用户端看到的报错信息是乱码
现象：工具内部抛异常，Agent 把堆栈信息原样贴给用户。
原因：模型的默认行为是「忠实反映输入」，如果没有明确指令要求转译，它会把异常文本直接输出。这类问题在模型越狱或低质量回复中特别常见。
解决：在系统提示词里加一条硬性规则——工具返回中所有以error开头的字段，严禁直接一字不改地输出；必须转成一句用户能看懂的话。同时在工具封装层设计user_message字段，让后端来保证错误信息的人话质量。
6.5 本地测试正常，线上高并发时 Agent 超时
现象：测试环境一切正常，线上请求量上来后，Agent 频繁超时，用户重试率上升。
原因：Agent 是多轮模型调用叠加的，每一步之间的网络往返和排队时间都累加。高并发下模型推理本身排队变长，Plan-and-Execute 结构的整体时延是各步之和。一旦某一步加重试，整个链路雪崩。
解决：把非关键的中间步骤异步化。比如规划步骤只需要一次，但执行步骤里可能有多个工具调用可以并行。优先串行依赖链路最短化，无依赖的工具调用通过并发请求发出。此外，对超时场景做降级——如果规划结果超过阈值没返回，直接退回单轮工具调用模式，保证最基础的用户问题还能被应答。
最后说一个我自己的习惯：Agent 上线后别急着加新功能，先把失败日志和评测集打通。每次事故都值得沉淀成一条新的评测样本，三个月后你会发现评测集本身就是最好的产品需求文档。这条路上不存在放之四海皆准的参数，但数据和复盘永远是通用的后悔药。希望帮到你。
本文还有配套的精品资源，点击获取
