★ FEATURED ARTICLE 1. 为什么“七要素”不是设计清单而是故障排查地图我第一次在团队里讲 AI Agent 架构时画了张漂亮的七要素图Memory、Planning、Action、Observation、Tool Use、Reasoning、Self-Correction——每个框都配了图标还标了箭头循环。结果上线第三天用户反馈“智能体卡在‘思考中’不动了”运维查日志只看到一串重复的LLM call timeout第五天另一个任务跑着跑着开始反复调用同一个天气 API直到被限频熔断第七天客户问“你们说的‘自主容错’在哪怎么连输入里多打了个句号都直接崩”那一刻我才意识到市面上几乎所有讲“Agent 七要素”的文章都在教你怎么画一张正确但无用的架构图而不是告诉你——当真实请求涌进来、模型开始胡说、工具突然失联、内存溢出、token 耗尽、网络抖动、用户中途改指令……这七个模块里哪个环节最先扛不住它为什么会扛不住你该先看哪行日志该加什么 guardrail 而不是加个 retry“七要素”真正的价值根本不是教学大纲而是一张工程级故障定位地图。它对应的是七个必须被显式设计、独立压测、单独监控、可开关降级的决策点。比如“Planning” 不是“让模型写个 step-by-step plan”而是决策点1是否启动规划→ 输入长度超 8k跳过规划直奔 Action→ 用户指令含“马上”“立刻”“别想太多”强制 bypass planning loop→ 上一轮规划失败超2次切换到 fallback planner比如规则引擎。“Memory” 不是“存点聊天记录”而是决策点2本次推理该读哪段记忆读多少以什么格式注入→ 不是“把全部历史喂给 LLM”而是▪️ 近3轮对话摘要用轻量 summarizer 提取 action intent▪️ 本次任务相关的知识片段从向量库 top-3 检索带 score threshold▪️ 上一轮失败的 error trace只保留 error code failed tool name input hash▪️ 全部不塞进 prompt而是分层注入摘要放 system prompt知识片段放 user message 前置块error trace 放最后 special instruction。这才是“工程实现”的起点把抽象概念翻译成可配置、可拦截、可熔断、可灰度的代码决策点。后面所有环节——从 token 预估、tool schema 校验、observation 解析容错到 self-correction 的触发阈值——全建立在这个基础上。没把这个想透后面堆再多 LangChain、LangGraph、LlamaIndex也只是在沙上建塔。提示别急着选框架。先拿纸笔对着你手头一个真实业务场景比如“帮用户订会议室同步日历发提醒邮件”逐个问自己如果 Planning 模块返回空数组系统该沉默失败还是 fallback 到单步执行如果 Memory 检索返回 5 条相似度 0.62 的结果该全用还是只取最高那条并加 confidence flag如果 Observation 解析出“{status: success, data: null}”算成功还是失败要不要重试重试几次把这七个问题的答案写下来比读十篇架构图都有用。2. 决策点3Tool Calling 不是函数调用是协议协商与契约管理绝大多数 Agent 教程把 Tool Calling 讲成“LLM 输出 JSON程序 parse 后执行函数”。这在 demo 里能跑通在生产环境里是定时炸弹。我见过三个最典型的崩塌现场Schema 漂移LLM 调用search_weather(city: str)但实际传入{city: 上海,中国}—— 后端服务要求 city 必须是 ISO 国家码城市名如CN-Shanghai结果返回 400Agent 却当成“天气查询成功”继续往下走语义歧义LLM 调用book_meeting(start_time: str, duration: int)传入{start_time: 3pm, duration: 30}—— 后端解析为“今天下午3点”但用户本意是“明天下午3点”没人校验时间上下文副作用失控LLM 调用send_email(to: str, subject: str, body: str)body 里含未过滤的用户原始输入结果一封带 XSS payload 的邮件发给了全组。根本原因在于Tool 不是函数是微服务接口LLM 不是程序员是不可靠的协作者。工程上必须建立三层契约2.1 协议层Tool Description 必须带机器可读的约束声明不能只写Get current weather for a city而要像 OpenAPI 一样声明name: search_weather description: Get current weather for a city. City must be in format COUNTRY-CODE-CITY_NAME (e.g., US-NewYork). parameters: city: type: string pattern: ^[A-Z]{2}-[A-Za-z]$ required: true description: ISO country code city name, dash-separated.→ 实际落地时我们用 Pydantic Model 自动生成此描述并在 LLM 调用前做 runtime schema check不是 parse 失败才报错而是提前 reject 不合规的 candidate。2.2 执行层Call Wrapper 必须封装重试、降级、熔断逻辑我们不用tool(**args)直接调用而是统一走ToolExecutor.execute(tool_name, args, context)第一次失败network timeout→ 自动重试 1 次间隔 200ms第二次失败4xx→ 触发validate_input钩子检查 args 是否符合 pattern若不符则返回 structured error 给 LLM 修正第三次失败5xx 或连续 timeout→ 熔断 60 秒返回 fallback response如天气服务暂不可用已为您记录需求稍后重试若 fallback 也失败 → 触发全局降级跳过此 tool进入 human-in-the-loop 流程。2.3 结果层Observation Parsing 必须定义 success/failure 的明确边界不是“有 response 就算成功”。我们定义HTTP StatusResponse Body Schema判定结果后续动作200{temp_c: float, condition: str}✅ Success注入 memory进入 next step200{error: invalid_city_format}❌ Failure返回 error code suggestion to LLM400any❌ Failure记录 schema violation触发告警503any⚠️ Degraded返回 fallback不计入 token cost注意failure 的返回值不是字符串call failed而是结构化对象{tool: search_weather, error_code: INVALID_INPUT, suggestion: 请确认城市格式为 CN-Shanghai}这样 LLM 才能真正理解问题而不是瞎猜。我们实测发现加了这个结构化 error 后LLM 自我修正成功率从 37% 提升到 89%。3. 决策点4Observation 解析不是文本提取是语义归一化与可信度标注LLM 的输出是“自然语言”Tool 的返回是“结构化数据”但中间的 Observation 环节常被当成透明管道——把 JSON 字符串原样塞回 prompt。这是高危操作。真实场景中Observation 有三大陷阱格式污染API 返回{data: {temp: 25.3, unit: °C}}LLM 却在 prompt 里看到data: {temp: 25.3, unit: °C}—— 引号、冒号、换行全在token 消耗暴增且 LLM 容易把°C当成乱码忽略语义失真天气 API 返回condition: Partly cloudyLLM 却理解成“多云”而实际业务要求区分“晴/多云/阴/雨”必须映射为标准枚举可信度缺失搜索 API 返回 10 条结果但其中 3 条来自低权重源2 条是广告LLM 却一视同仁地引用。我们的解法是Observation 层必须做三件事——清洗、归一、打标。3.1 清洗从 raw response 到 minimal semantic payload不传整个 response body只提取关键字段并标准化格式# 原始 response { code: 0, message: success, data: { temperature: 25.3, weather: Partly cloudy, humidity: 65%, wind_speed: 12 km/h } } # 清洗后注入 prompt 的 observation { weather: partly_cloudy, # 归一为 snake_case 枚举 temperature_celsius: 25.3, # 单位显式标注数值转 float humidity_percent: 65.0, # 去掉 % 符号转数字 wind_speed_kmh: 12.0 # 同上 }→ 这步由ObservationNormalizer统一处理每个 tool 对应一个 normalizer class确保 LLM 看到的永远是干净、一致、无歧义的字段。3.2 归一将 domain-specific value 映射为通用语义比如会议系统返回{status: confirmed}CRM 系统返回{state: booked}邮件系统返回{result: sent}—— 在 Observation 层全部归一为{booking_status: confirmed}。这样 LLM 无需学习不同系统的术语只需理解统一语义。3.3 打标为每条 observation 附加可信度分数confidence score不是简单标记“可信/不可信”而是量化数据源类型可信度算法示例官方 API如天气局1.0硬编码weather: {value: partly_cloudy, confidence: 1.0}向量检索 top-1cosine similarity * 0.8similarity0.92 → confidence0.736规则引擎输出规则匹配数 / 总规则数匹配3/5条规则 → confidence0.6LLM 自我生成fallback0.3人工设定下限fallback_reasoning: ..., confidence: 0.3}→ LLM 在后续推理中会优先采信 confidence 0.7 的 observation若所有 observation confidence 0.5则自动触发 human escalation。实操心得别让 LLM 自己判断“这条信息可靠吗”。人类定义规则机器执行规则。我们曾让 LLM 给 observation 打分结果它给一条明显错误的天气数据打了 0.95 分——因为 response 里有“权威”“实时”“官方”三个词。信任必须来自可验证的来源而非文字修饰。4. 决策点5Self-Correction 不是重试是状态机驱动的主动干预“Self-Correction” 是最被神化的概念。很多教程说“让 Agent 发现错误就重试”。但真实世界里重试是最廉价的错误处理也是最危险的默认行为。我们线上一个订餐 Agent 曾因重试逻辑失控30 秒内向餐厅 API 发了 17 次下单请求导致用户被扣 17 笔钱。真正的 Self-Correction是基于当前 execution state 的主动决策它必须回答三个问题这次失败是偶发network glitch还是必然逻辑缺陷重试能否解决如果不能该降级到什么方案用户是否需要知情以什么方式告知我们用状态机实现而非 if-else 堆砌graph TD A[Start] -- B{Error Type?} B --|Timeout/5xx| C[Retry once with jitter] B --|4xx/Schema Error| D[Validate Correct Input] B --|LLM Output Invalid| E[Re-prompt with stricter constraints] B --|Tool Result Inconsistent| F[Cross-check with fallback source] C -- G{Success?} G --|Yes| H[Continue] G --|No| I[Trigger fallback] D -- J{Input fixable?} J --|Yes| K[Auto-correct retry] J --|No| L[Ask user clarify]关键细节Error Type 分类必须细粒度不是“HTTP error”而是TOOL_TIMEOUT,TOOL_SCHEMA_VIOLATION,LLM_OUTPUT_MALFORMED,OBSERVATION_INCONSISTENT—— 每种对应不同 handlerRetry 有严格条件仅对TOOL_TIMEOUT且retry_count 1允许每次 retry 加 jitter100ms~500ms 随机避免雪崩Auto-correct 有安全边界比如 LLM 传{city: shanghai}normalizer 可 auto-correct 为CN-Shanghai但若传{city: 火星}则拒绝修正直接报错Fallback 不是兜底是预案每个 tool 必须配 fallback▪️search_weatherfallback → 本地缓存last 1h 数据▪️book_meetingfallback → 日历空闲时段 API不依赖具体会议室系统▪️send_emailfallback → 企业微信消息降级通道。踩坑实录我们最初用 LLM 自我反思做 correctionprompt 是 “请检查上一步是否有错误如有请修正”。结果 LLM 在 82% 的 case 里都说“没有错误”哪怕 observation 明显是{error: not_found}。后来改成 rule-based detection当 observation 包含errorkey或 LLM output 中出现I dont know、unable to等 trigger phrase立即进入 correction flow。准确率从 18% 跃升至 99.2%。5. 决策点6Token 管控不是预算分配是动态流控与成本感知路由“AI Agent 怎么扛并发”——热搜第一的问题本质是 token 管控失效。很多人以为加个 Redis 计数器、设个 rate limit 就行。但真实瓶颈不在 QPS而在token throughput。一个复杂 Agent 流程Plan → Tool1 → Obs1 → Tool2 → Obs2 → …可能消耗 3000 tokens而一个简单问答只用 200 tokens。如果按请求计费高 token 请求会饿死低 token 请求。我们的方案是Token-aware Request Router Per-Step Budgeting。5.1 Token 预估不是 guess是 model-driven estimation不用len(prompt)粗略算而是训练轻量 regressor输入prompt template variable length如 history turns, tool result size输出预测 token countMAE 15 tokens模型XGBoost训练快、解释性强特征包括▪️ history turn count▪️ tool result JSON depth▪️ 最长字符串字段长度▪️ 是否启用 memory retrieval是/否▪️ 当前 LLM temperature影响输出长度。→ 每个请求进来先 run estimator得到predicted_tokens。5.2 动态流控按 token 而非请求数限流用令牌桶token bucket但桶容量单位是token-secondstoken × time桶容量10000 token-seconds / minute每个请求消耗predicted_tokens × response_time_seconds若请求 predicted_tokens2000预估响应时间 2s则消耗 4000 token-seconds若桶剩余 4000拒绝请求返回系统繁忙请稍后重试预计等待 12s。→ 这样一个 200-token 的快速请求不会被 3000-token 的慢请求堵死。5.3 成本感知路由把请求导向性价比最高的 LLM不是所有任务都需 GPT-4。我们维护 LLM profile 表ModelMax InputMax OutputCost per 1k tokensLatency P95Best Forgpt-4-turbo128k4k$0.01 / $0.031200msComplex planning, multi-step reasoningclaude-3-haiku200k4k$0.00025 / $0.00125320msFast tool calling, simple QAllama3-70b8k8k$0.0005 / $0.0008850msOn-prem, high privacy→ Router 根据predicted_tokens和任务类型is_planning_task,is_tool_call,is_summarize选择 modelpredicted_tokens 500且is_tool_call→claude-3-haikupredicted_tokens 2000且is_planning_task→gpt-4-turbo其他 →llama3-70b成本最低。关键经验token 预估不准比没预估更危险。我们上线初期用固定系数prompt length × 1.3结果高估 40%大量请求被误拒低估 30%GPU 显存爆满 OOM。最终靠 real-time feedback loop 修正每次请求 actual_tokens 与 predicted_tokens 的差值实时更新 regressor weights。现在误差稳定在 ±8 tokens。6. 决策点7Memory 管理不是存储是生命周期编排与上下文蒸馏把 Memory 当数据库用是 Agent 工程最大误区。我们曾有个客服 Agent内存存了 200 轮对话每次推理都把全部历史塞进 prompt结果 token 溢出、响应变慢、LLM 开始胡编。后来发现90% 的对话中LLM 真正用到的只有最近 3 轮 1 条关键知识。Memory 的工程核心是Context Distillation从海量信息中实时蒸馏出本次推理所需的最小有效上下文。6.1 生命周期分层不是“存”和“删”是“热/温/冷”三级流转Hot Memory 5min当前 session 的 active context存于 Redis带 TTLWarm Memory5min ~ 24h用户 profile、偏好、近期任务状态存于 PostgreSQL可关联查询Cold Memory 24h归档日志、审计记录存于 S3只读。→ 每次推理只从 Hot Warm 中提取Cold 不参与实时决策。6.2 蒸馏策略三阶段筛选不是关键词匹配Turn-level filtering丢弃所有systemrole messages丢弃usermessages 中无 action intent 的如“你好”“谢谢”保留assistantmessages 中含 tool call 或 final answer 的。Semantic summarization对保留的 turns用轻量 summarizerT5-small生成摘要User asked to book meeting on Friday, assistant checked calendar and found slot 2-3pm, confirmed with user.摘要长度严格限制 ≤ 128 tokens。Knowledge grounding基于当前 query从 Warm Memory 检索相关知识▪️ 用户历史 booking 偏好会议室大小、是否需投影仪▪️ 企业 policy会议超 1h 需 manager approval▪️ 设备状态投影仪维修中本周不可用检索结果带 relevance score只取 score 0.6 的 top-2 条。→ 最终注入 prompt 的 memory不超过 300 tokens且 100% 与当前任务强相关。6.3 安全隔离Memory 不是共享池是租户级沙箱每个用户 session 有独立 memory namespace不同业务线客服/销售/HRmemory 物理隔离敏感字段手机号、身份证自动 redact替换为PHONE且 redaction 规则可配置。实测对比未蒸馏时平均 prompt length 2850 tokensP95 响应 4.2s蒸馏后平均 210 tokensP95 响应 0.8sLLM 准确率提升 22%因噪声减少。更重要的是内存泄漏风险归零——Hot Memory TTL 到期自动清理无需人工干预。7. 工程落地 checklist七个决策点每个都必须有 concrete implementation讲完理论给一份我们团队用的Agent 工程落地 checklist。不是“建议”是上线前必须填满的项。少一项就等于埋一颗雷。决策点必须交付物验证方式未达标后果1. Planningplanner_config.yaml含 bypass_threshold, fallback_planner, max_steps用 100 条真实用户指令测试统计 bypass 率、fallback 触发率Planning 成性能瓶颈高并发下 timeout 暴增2. Memorymemory_distiller.py含 turn filter rules, summarizer model, knowledge retrieval config输入 50 轮历史对话输出 distilled context ≤ 300 tokens人工抽检 relevancePrompt 过长LLM 丢失关键信息幻觉率上升3. Tool Callingtool_registry.json每个 tool 含 machine-readable schema, fallback, timeout_ms自动扫描所有 tool验证 schema pattern 是否 match real API specTool 调用失败率 15%用户投诉“总说找不到服务”4. Observationobservation_normalizer/每个 tool 对应 normalizer class含 confidence algo对 100 条 raw API responses运行 normalizer检查 output 字段一致性、confidence 合理性LLM 误解 tool 结果执行错误动作如订错会议室5. Self-Correctioncorrection_state_machine.py含 error type mapping, handler logic, fallback triggers注入模拟 errortimeout, 4xx, malformed json验证 correction path 正确性错误累积小问题演变成大事故如重复扣款6. Token Controltoken_router.py含 estimator model, bucket config, model routing rules压测混合 1000qps含 20% 高 token 请求监控 token-seconds usageGPU 显存 OOM服务雪崩SLA 彻底崩溃7. Memory Lifecyclememory_ttl_policy.mdHot/Warm/Cold 存储位置、TTL、redaction rules审计随机抽 100 条用户数据验证敏感字段 redact、跨租户隔离数据泄露风险合规审计不通过最后分享一个血泪教训我们曾认为 “Observation Normalizer” 是个 trivial task让 junior engineer 用正则写了三天。上线后发现天气 API 的{temp: 25.3°C}被正则错切成{temp: 25.3}丢了单位LLM 把 25.3 当成华氏度结论是“极寒天气”。后来重写为 Pydantic Model custom validator加了 unit check问题根除。所以记住Agent 工程没有 trivial part。每个决策点都是生产环境的守门人。画七要素图只要十分钟让七个决策点在高并发、低延迟、强一致的环境下稳稳跑起来需要三个月的迭代、压测、调优。别省这个时间。
阅读完成 · 觉得有帮助？
