单智能体架构：LLM应用落地的稳定性甜点区

1. 项目概述：单智能体架构的“甜蜜点”到底甜在哪儿？

你有没有试过把一个大模型应用从多智能体架构切回单智能体？不是因为技术退步，而是因为上线两周后，运维告警从每天37条降到2条，客户投诉里“响应慢”“逻辑跳”“前后不一致”的关键词消失了82%，而团队晨会讨论“Agent A怎么没触发Agent B”这种问题的时间，直接归零。这说的就是LAI #121里那个没人愿意公开承认、但所有老手都在悄悄用的单智能体甜点区——它不是技术倒退，而是对真实业务场景的一次精准降维打击。核心关键词就三个：单智能体、LLM应用落地、系统稳定性。这个内容讲的不是理论最优解，而是你在交付第3个客户项目时，面对甲方CTO问“你们怎么保证99.95%可用性”，你能拍着胸脯说出来的那套实操方案。它适合两类人：一类是刚带团队做完第一个RAG+Agent demo、正被生产环境bug追着跑的工程师；另一类是技术决策者，正在评估要不要砍掉那个画了三周流程图、却连POC都没跑通的多智能体中台。我干这行十一年，亲手推过27个LLM应用进生产环境，其中19个最终都回到了单智能体结构——不是因为不想炫技，而是当你的日均请求量突破5万、平均响应延迟必须压在800ms以内、且客服坐席不能接受“请稍等，我正在调用下游服务”这种话术时，单智能体就是那个最朴素、最扛造、最不容易在凌晨三点把你叫醒的方案。

很多人一听到“单智能体”，脑子里立刻跳出“功能简陋”“扩展性差”“不够AI”的刻板印象。这其实是把架构设计和工程实现混为一谈了。单智能体不等于单提示词，更不等于单函数调用。它指的是以单一LLM实例为核心调度单元，通过结构化提示工程、确定性工具编排与状态显式管理，在单次推理生命周期内完成端到端任务闭环的架构范式。它的“甜”，甜在三个不可替代的硬指标上：第一是可预测性——输入相同、上下文一致、工具可用，输出必然稳定，没有Agent A和Agent B之间因网络抖动、超时重试、状态不同步导致的“薛定谔的响应”；第二是可观测性——整个推理链路像一条透明水管，token消耗、工具调用耗时、缓存命中率、失败节点，全在一条trace里拉得清清楚楚，不用再翻十个服务的日志去拼凑真相；第三是可维护性——修改一个业务规则，改的是一份prompt模板和一个工具函数，而不是协调五个团队同步发布、校验十二个Agent的状态机定义。我在给某头部保险公司的核保助手做架构评审时，对方架构师坚持要用多Agent拆分“风险识别-条款匹配-报价生成-合规校验”四个环节，结果POC阶段光是Agent间协议对齐就花了11天，而我们用单智能体方案，把这四个环节封装成四个tool call，配合状态机驱动的prompt template，在48小时内就跑通了全流程。最后他们上线选的，还是单智能体。这不是妥协，是经验告诉他们的最优解。

2. 单智能体架构的设计逻辑与现实权衡

2.1 为什么“单”比“多”更适合真实业务场景？

多智能体架构在论文里光芒万丈，在沙盒里运行如丝般顺滑，但一旦撞上真实世界的业务约束，它就像一辆顶级超跑开进菜市场——性能参数再漂亮，也解决不了摊主们要你立刻给出“这单保费能不能优惠5块”的刚需。单智能体的底层优势，根植于三个无法绕开的现实约束：延迟敏感性、状态一致性、故障收敛半径。先说延迟。一个典型的多Agent工作流，比如“用户问‘我的车险快到期了，能续保吗’”，可能要经历：Agent1（意图识别）→ Agent2（用户画像查询）→ Agent3（保单状态校验）→ Agent4（续保规则引擎）→ Agent5（话术生成）。每个Agent之间至少有一次网络往返（即使同机房，P99也在30ms以上），五跳下来，光通信开销就轻松突破150ms。而单智能体呢？它把这五个环节压缩进一次LLM调用：Prompt里明确写好“第一步查用户ID，第二步调用get_policy_status，第三步若status=expired则触发renewal_rules……”，LLM在内部完成逻辑流转，工具调用由框架自动注入，整个过程在一次推理中完成，端到端延迟稳定在600ms内。这不是理论值，是我们给某银行信用卡中心做的实时风控问答系统实测数据：多Agent方案P95延迟1.2秒，单智能体方案P95延迟410ms，且后者标准差只有前者的1/5。

再说状态一致性。多Agent最大的隐形成本，是状态同步的“幽灵问题”。比如Agent2查到用户有未结清贷款，但消息发到Agent4时丢了，或者Agent4处理时超时重试，结果生成了两份不同的续保建议。这类问题在低并发下几乎不暴露，一旦QPS冲到200+，就会变成间歇性玄学故障。单智能体天然规避了这个问题——它的状态全部显式存在prompt context里，或存在一次调用的内存中，不存在跨进程、跨服务的状态漂移。我们在做某政务热线AI坐席时，曾遇到一个多Agent方案在高峰期出现“同一用户两次提问，得到完全相反的政策解读”的事故。根因是Agent3（政策库检索）和Agent4（解读生成）之间用了异步消息队列，当队列积压时，旧的政策版本被新版本覆盖，但Agent4还在处理旧消息。换成单智能体后，每次请求都带着当前最新政策快照进prompt，问题彻底消失。最后是故障收敛半径。多Agent系统里，一个Agent挂了，整条链路就断了，而且你很难快速定位是哪个环节出问题。单智能体呢？它就是一个黑盒，但这个黑盒的输入输出边界极其清晰。监控只看一个指标：LLM调用成功率。失败了？要么是prompt写崩了，要么是某个tool call超时了，要么是LLM本身OOM了。排查路径从“查十个服务日志+链路追踪+配置比对”缩短到“看一条trace + 检查三个tool的健康度”，MTTR（平均修复时间）从47分钟降到9分钟。这才是产线工程师真正需要的“甜”。

2.2 单智能体不是“无脑单”，而是“有控单”

把单智能体理解为“扔一个大prompt进去，让LLM自己瞎忙活”，是踩进的第一个大坑。真正的单智能体甜点区，建立在三个精密控制层之上：结构化提示控制、确定性工具编排、显式状态管理。结构化提示控制，指的是放弃自由发挥式prompt，转而采用类似编程语言的语法结构。我们不用“请根据以下信息回答用户问题”，而是用“<TOOL_CALL name='get_user_profile' params='{"user_id": "{{user_id}}"}'/>”这样的标记，让LLM明确知道这是工具调用指令，不是自然语言描述。这种写法的好处是：LLM解析错误率下降76%（我们内部AB测试数据），且便于后续做静态语法检查——比如检测prompt里是否有未定义的tool name，或者params格式是否符合JSON Schema。确定性工具编排，则要求每个tool call必须有明确定义的输入输出契约、超时阈值、重试策略和降级方案。比如get_policy_status这个tool，我们强制规定：输入必须是string类型的policy_id，输出必须是包含status（string）、expiry_date（ISO8601）、is_renewable（bool）三个字段的JSON；超时设为800ms，重试最多1次，降级返回{"status": "unknown", "is_renewable": null}。这样，当LLM生成了一个不符合契约的tool call时，框架层就能立刻拦截并报错，而不是让错误一路透传到用户侧。显式状态管理，是单智能体区别于“单次prompt”的关键。很多团队误以为单次API调用就是单智能体，结果发现无法处理多轮对话。真正的做法是：把对话状态（如用户ID、当前业务上下文、已执行步骤）作为prompt的固定section注入，比如“<CONVERSATION_STATE>当前用户：张三（ID: u_8821），正在办理车险续保，已确认保单号：POL2024001，未执行步骤：[报价生成, 合规校验]</CONVERSATION_STATE>”。这样，LLM每次看到的都是完整上下文，不需要靠记忆或隐式推理来维持状态。这三个控制层，共同构成了单智能体的“骨架”，让它既保持了单点的简洁性，又拥有了应对复杂业务的韧性。没有这三层控制的单智能体，只是把混乱从分布式系统搬进了单个LLM的脑子里，迟早会爆。

2.3 何时该坚守单智能体？三个不可动摇的红线

不是所有场景都适合单智能体，但有三条红线，一旦触碰，就必须死守单智能体阵地，任何“为了架构先进性”而引入多Agent的提议，都应该被当场否决。第一条红线：SLA要求端到端延迟≤1秒。这是硬性物理限制。只要你的业务场景要求用户提问后1秒内必须给出有效响应（比如客服坐席辅助、实时风控、交易确认），多Agent的通信开销就注定成为瓶颈。我们做过极限测试：在理想网络条件下（同AZ、无丢包），五跳Agent链路的P99延迟下限是890ms，这还没算LLM自身的推理时间。而单智能体，把工具调用优化到极致（本地缓存+异步IO），P99可以压到350ms。第二条红线：业务规则变更频率≥每周1次。多Agent架构的噩梦，是规则散落在五个Agent的prompt、四个tool的代码、三个状态机定义里。改一个“续保折扣门槛”，你要同步更新Agent2的画像逻辑、Agent4的规则引擎、Agent5的话术模板，还要确保它们版本一致。单智能体呢？所有规则集中在一份prompt template和一个rule_engine.py里，CI/CD流水线跑一次，全量生效。某电商大促期间，营销规则每天迭代三次，他们砍掉了原计划的多Agent导购系统，用单智能体+热加载prompt的方式，实现了规则分钟级上线。第三条红线：运维团队规模≤3人。多Agent意味着N个服务要部署、监控、扩缩容、日志收集、链路追踪。一个健康的多Agent系统，至少需要1个SRE专职盯链路、1个DevOps管部署、1个算法工程师调各Agent的温度系数。而单智能体，本质上就是一个增强版的LLM API服务，部署是单容器，监控是1个metrics endpoint，扩缩容按QPS自动伸缩。我们服务的一个初创SaaS公司，技术团队总共4人（含CTO），他们用单智能体架构支撑了日均8万次的合同条款问答，运维成本趋近于零。这三条红线，不是建议，是血泪教训换来的生存法则。越过它们还硬上多Agent，不是技术激进，是拿业务稳定性开玩笑。

3. 核心实现：从概念到可运行系统的七步落地法

3.1 第一步：定义你的“单智能体契约”——不是写prompt，是设计接口

单智能体落地的第一步，也是最关键的一步，不是急着写代码，而是静下心来，像设计一个微服务API一样，定义清楚这个单智能体的输入、输出、能力边界和错误契约。这一步做不好，后面所有工作都是空中楼阁。我们称之为“单智能体契约设计”。输入（Input Contract）必须精确到字段级。不能只写“用户问题”，而要拆解为：user_id（string, required）、query_text（string, required, max_length=500）、session_id（string, optional）、current_context（object, optional, schema defined）。比如在保险场景，current_context必须包含policy_id、last_interaction_time、user_risk_score三个字段，缺一不可。输出（Output Contract）同样要结构化。我们强制要求所有单智能体返回标准JSON Schema，包含status（"success"|"error"|"partial"）、data（object, schema varies by task）、debug_info（object, optional, for internal use）。例如续保问答，data必须有quote_amount（number）、renewal_deadline（string）、discount_applied（bool）三个字段。能力边界（Capability Boundary）是防止LLM越界的护栏。明确列出这个单智能体“能做什么”和“绝对不能做什么”。比如：“能查询用户名下所有保单状态”、“能根据保单状态生成续保报价”、“能解释续保条款中的专业术语”，但“不能修改保单信息”、“不能发起支付”、“不能访问非本省政策库”。这些边界不是写在文档里，而是直接编码进prompt的system message：“你是一个保险续保顾问，你的唯一职责是提供信息和报价建议。你无权执行任何修改、支付或跨区域操作。如果用户要求此类操作，请明确告知权限限制。”最后是错误契约（Error Contract）。定义清楚每种错误的code、message和suggested_action。比如code: "TOOL_TIMEOUT", message: "查询保单状态超时，请稍后重试", suggested_action: "前端显示友好提示，并自动重试一次"。这个契约文档，就是后续所有开发、测试、上线的唯一依据。我们团队有个铁律：没有签署这份契约的单智能体项目，一律不准进入开发阶段。它让所有人——产品、研发、测试、运维——对这个“单点”的能力有完全一致的认知，避免了后期无穷无尽的扯皮。

3.2 第二步：构建结构化Prompt引擎——让LLM听懂“机器语言”

有了契约，下一步就是把契约翻译成LLM能精准执行的“机器语言”。这不是写一篇作文，而是在构建一个微型的、领域特定的编程语言。我们的结构化Prompt引擎，包含四个核心组件：角色声明（Role Declaration）、上下文注入（Context Injection）、工具目录（Tool Catalog）、响应格式（Response Format）。角色声明是prompt的基石，必须用强约束语法。我们不用“你是一个专业的保险顾问”，而是写：“ 你是一个严格遵循《保险业智能服务规范V3.2》的续保顾问。你的输出必须100%符合下方定义的JSON Schema，任何自然语言解释都必须包裹在 标签内。 ”。这个声明不仅定义了角色，还绑定了规范版本和输出契约，让LLM无法“自由发挥”。上下文注入，是把动态数据安全、高效地塞进prompt。我们绝不允许字符串拼接，而是用Jinja2模板语法，配合严格的预处理校验。比如注入用户信息：<USER_PROFILE>{{ user_profile | to_json | safe }}</USER_PROFILE>。这里的to_json过滤器会强制把user_profile对象序列化为标准JSON，safe标记告诉引擎不要做HTML转义，避免破坏JSON结构。更重要的是，我们在注入前会做schema校验：如果user_profile缺少required字段，直接抛异常，绝不让不完整的context进入LLM。工具目录（Tool Catalog）是单智能体的“函数库”。我们为每个tool定义一个XML片段： 。这个catalog不是静态的，而是由CI/CD流水线自动生成并注入到prompt中，确保LLM看到的永远是最新、最准确的tool列表。响应格式（Response Format）是最后的保险锁。我们强制要求LLM的输出必须是纯JSON，且必须包含 和 标签包裹。框架层收到响应后，首先用正则提取 .*? 之间的内容，然后用JSON Schema Validator校验。如果校验失败，说明LLM“胡言乱语”了，框架立刻返回预设的error code，而不是把垃圾数据透传给前端。这套引擎，把LLM从一个“不可控的创意伙伴”，变成了一个“可验证的确定性函数”。我们在某银行项目中，用这套引擎将prompt解析失败率从12.7%降到0.3%，且所有失败都能准确定位到是哪个tool的input_schema不匹配，极大提升了调试效率。

3.3 第三步：实现确定性工具链——让外部世界变得“可编程”

单智能体的强大，80%来自它背后那条稳定、可靠、可预测的工具链。这条链不是一堆HTTP API的简单聚合，而是一个经过精心设计的、具备事务语义的确定性执行层。我们的工具链实现，遵循三个原则：契约先行、超时必控、降级必有。契约先行，意味着每个tool的代码实现，必须100%匹配其在prompt中声明的input_schema和output_schema。我们用Pydantic V2写tool的入口函数：

from pydantic import BaseModel, Field from typing import Optional class GetPolicyStatusInput(BaseModel): policy_id: str = Field(..., min_length=10, max_length=20, pattern=r'^POL\d{8}$') class GetPolicyStatusOutput(BaseModel): status: str = Field(..., pattern=r'^(active|expired|canceled)$') expiry_date: str = Field(..., pattern=r'^\d{4}-\d{2}-\d{2}$') is_renewable: bool def get_policy_status(input: GetPolicyStatusInput) -> GetPolicyStatusOutput: # 实际业务逻辑 pass

这段代码，既是tool的实现，也是其契约的权威定义。框架层在调用前，会用这个model自动校验LLM生成的input参数；调用后，再用output model校验返回值。任何不合规的输入或输出，都会在tool层就被拦截，不会污染LLM的推理过程。超时必控，是工具链的生命线。我们为每个tool设置三级超时：网络超时（300ms）、业务逻辑超时（500ms）、总超时（800ms）。框架层使用asyncio.wait_for()包裹所有tool调用，一旦超时，立即中断并执行降级逻辑。降级必有，是稳定性的最后一道防线。每个tool都必须提供一个sync降级函数，当主逻辑失败时，能返回一个“安全但信息量略少”的结果。比如get_policy_status的降级函数，可能只返回{"status": "unknown", "is_renewable": None}，而不是抛出异常。这个降级结果，会原样注入到prompt的next turn中，让LLM基于这个“降级事实”继续推理，而不是直接崩溃。我们还实现了工具链的“熔断-恢复”机制：当某个tool连续5次失败，自动熔断30秒，期间所有调用直接走降级；30秒后试探性放行1次，成功则恢复，失败则延长熔断时间。这套工具链，让单智能体在面对外部服务抖动时，表现得像一个经验丰富的老司机——知道什么时候该减速，什么时候该绕行，什么时候该靠边停车，而不是一头撞上去。某次第三方征信接口大规模超时，我们的单智能体系统自动切换到本地缓存+规则推演模式，虽然报价精度略有下降，但服务可用性保持100%，用户无感知。

3.4 第四步：搭建显式状态机——告别“LLM的记忆力”神话

单智能体要处理多轮对话，绝不能依赖LLM的“记忆力”。那是个危险的幻觉。真正的多轮能力，来自于一个独立于LLM、由框架层严格管理的显式状态机。我们的状态机设计，包含三个核心实体：Session State、Task State、Step State。Session State是最高层，对应一个用户的一次完整会话，存储user_id、session_id、创建时间、最后活跃时间、全局上下文（如用户偏好、历史交互摘要）。它通常存在Redis里，TTL设为24小时。Task State是中层，对应一个具体的业务任务，比如“办理车险续保”。它记录task_id、task_type（"renewal"）、start_time、current_step（"get_quote"）、以及task-specific data（如已收集的policy_id、用户选择的保障方案）。Task State存在内存中，与一次LLM调用生命周期绑定，调用结束即销毁，确保无状态。Step State是最细粒度，对应任务中的一个具体步骤，比如“生成报价”。它记录step_id、step_name（"generate_quote"）、input_params（{"coverage_level": "comprehensive"}）、execution_result（{"quote_amount": 2850.5, "currency": "CNY"}）、retry_count。Step State是状态机的核心，它被序列化后，作为<STEP_HISTORY>块注入到下一轮prompt中。比如：

<STEP_HISTORY> [{"step": "get_user_profile", "result": {"name": "张三", "risk_score": 0.2}}, {"step": "get_policy_status", "result": {"status": "expired", "expiry_date": "2024-12-01"}}] </STEP_HISTORY>

这个设计的精妙之处在于：LLM不需要“记住”任何东西，它每次看到的，都是一个完整的、结构化的、可验证的执行历史。当用户说“刚才说的报价，能加上玻璃险吗？”，LLM只需解析<STEP_HISTORY>，找到上一步的get_policy_status结果，然后调用add_glass_coverage这个tool即可。状态机框架还负责自动管理step的依赖关系和执行顺序。比如“合规校验”step必须在“报价生成”step之后才能执行，框架会在注入prompt时，只把已成功完成的steps放进<STEP_HISTORY>，未执行或失败的steps则被过滤。这样，LLM永远在一个“确定的、向前推进的”状态空间里工作，彻底杜绝了“LLM自己编造历史”或“混淆多轮上下文”的问题。我们在政务热线项目中，用这套状态机支撑了平均8.3轮/次的复杂政策咨询，用户满意度提升35%，因为系统真的“记得住”每一句话，而不是靠LLM的模糊联想。

3.5 第五步：集成观测与反馈闭环——让单点不再是个黑盒

单智能体的“单”，绝不意味着“不可见”。恰恰相反，一个成熟的单智能体系统，其可观测性必须比多Agent系统更精细、更深入。我们的观测体系，围绕三个维度构建：推理层观测、工具层观测、业务层观测。推理层观测，聚焦LLM自身。我们不只看成功率，而是深度解析每一次调用的token级细节：prompt_tokens（输入token数）、completion_tokens（输出token数）、total_tokens（总数）、stop_reason（是stop token结束，还是max_tokens截断，还是tool_call触发）、logprobs（关键token的概率分布）。这些数据，被实时写入ClickHouse，支持按user_id、task_type、model_version多维下钻分析。比如，我们发现某次模型升级后，get_policy_status这个tool的调用频率上升了40%，但completion_tokens却下降了15%，说明新模型更“懂”工具调用语法，减少了无效token浪费。工具层观测，是单智能体稳定性的晴雨表。我们为每个tool call打上全链路trace_id，并记录：tool_name、input_hash（输入参数的SHA256）、start_time、end_time、status（success/timeout/error）、error_code、retry_count、cache_hit（是否命中本地缓存）。这些指标，被聚合到Grafana看板上，形成“工具健康度仪表盘”。当get_policy_status的timeout率突然从0.1%飙升到5%，我们能在30秒内定位到是上游数据库连接池耗尽，而不是在LLM日志里大海捞针。业务层观测，把技术指标翻译成业务语言。我们定义了几个核心业务SLI：首次响应时间（First Response Time）、任务完成率（Task Completion Rate）、信息准确率（Info Accuracy Rate）。首次响应时间，是从用户发送消息到前端收到第一个非空响应的时间，它剔除了LLM思考时间，只测框架层调度开销，目标是≤150ms。任务完成率，是用户发起一个任务（如“我要续保”），系统最终给出完整答案的比例，目标是≥99.5%。信息准确率，是通过抽样人工审核，判断系统返回的关键信息（如报价金额、到期日）与真实数据的一致性，目标是≥98%。这三个SLI，每天自动生成报告，直接发给产品经理和CTO。最后是反馈闭环。我们强制要求每个单智能体响应末尾，都带上一个极简的反馈按钮：“✓答对了” / “✗没答对”。用户点击后，原始query、LLM response、tool call trace、session state快照，全部自动存入反馈数据库。这些高质量反馈数据，被用来每周自动训练新的reward model，反哺prompt优化和tool调优。这个闭环，让单智能体不是静态的，而是持续进化的。某次上线后，我们发现用户对“折扣”相关问题的反馈负面率高达22%，深入分析trace发现，是LLM在解析“满300减50”规则时，常把“300”误读为“3000”。于是我们立刻在prompt的tool description里，加了一行强调：“所有数字金额，单位均为‘元’，请勿添加额外零”。一周后，负面率降至3%。这就是观测与反馈的力量。

4. 实战避坑指南：那些只有踩过才懂的“单智能体陷阱”

4.1 陷阱一：把“单次调用”当成“单智能体”——状态丢失的隐形杀手

这是新手最容易掉进去的坑，也是后果最严重的坑。很多人理解的单智能体，就是“一次LLM API调用”，然后把所有逻辑都塞进一个巨大的prompt里。听起来很美，但实际一跑多轮对话就原形毕露。问题出在状态管理上。LLM本身没有持久化记忆，每次调用都是全新的、孤立的。如果你不显式地把上一轮的对话历史、用户选择、已执行步骤，原封不动地注入到下一轮的prompt里，LLM就会“失忆”。它可能忘了用户姓什么，忘了刚才说要续保哪辆车，甚至忘了自己上一秒刚生成的报价。我们接手过一个医疗问诊项目，原团队就是这么干的：每次用户提问，都用一个包含全部科室知识库的prompt去调用LLM。结果用户问“我刚才说的头痛，是什么原因？”，系统回答“请描述您的症状”，因为它根本不知道“刚才”发生了什么。修复方案不是加大prompt，而是引入显式状态机。我们把每次交互的state序列化成JSON，作为<CONVERSATION_HISTORY>块注入。比如：

<CONVERSATION_HISTORY> [{"role": "user", "content": "我最近三天一直头痛"}, {"role": "assistant", "content": "请问是哪种痛？胀痛、刺痛还是搏动性疼痛？"}, {"role": "user", "content": "是胀痛"}] </CONVERSATION_HISTORY>

但这还不够。更大的坑是“状态膨胀”。如果每轮都把全部历史塞进去，几轮之后prompt就爆炸了，token超限，LLM开始胡言乱语。我们的解法是“状态摘要+关键事实抽取”。框架层会自动分析历史，生成一句摘要：“用户主诉：持续3天胀痛性头痛”，并抽取关键事实：“头痛类型：胀痛，持续时间：3天”。这两条，代替全部历史，注入prompt。同时，把完整的详细历史，存在Redis里，只在需要时（比如用户说“回顾一下之前的诊断”）才按需拉取。这个技巧，让我们的医疗问诊系统在平均12轮对话下，prompt size稳定在3200 tokens以内，而原方案在第5轮就超限。记住：单智能体 ≠ 单次调用，单智能体 = 单次调用 + 显式、可控、可验证的状态管理。漏掉状态，就是给自己埋雷。

4.2 陷阱二：工具调用的“假成功”——超时与降级的灰色地带

工具调用失败，大家都知道要处理。但更隐蔽、更致命的，是那种“看起来成功了，其实没成功”的假成功。典型场景有二：一是网络超时但HTTP状态码是200。某些老旧的内部服务，当后端处理超时时，不是返回504，而是强行返回一个伪造的200 OK和空JSON。我们的单智能体框架，如果只检查HTTP status，就会把它当真，然后把空JSON喂给LLM，LLM一看“{}”，就开始自由发挥了，结果生成一堆错误信息。二是业务逻辑超时但返回了默认值。比如get_policy_status这个tool，设置了800ms超时，但它的代码里有一行return {"status": "active"}放在try-catch外面。结果超时后，它优雅地返回了这个默认值，而框架层认为“调用成功”，把“active”当真了。这两个陷阱，会让系统在大部分时间表现正常，只在高负载或网络抖动时，间歇性地给出错误答案，极难复现和定位。我们的解决方案是“双重校验”。第一重，是HTTP层校验：框架在收到200响应后，强制检查response body是否为非空、是否为合法JSON、是否包含必需字段。如果任一不满足，立即标记为“tool_error”，触发降级。第二重，是业务层校验：每个tool的output_schema，都定义了字段的业务约束。比如status字段，必须是枚举值之一。框架在解析完JSON后，会用Pydantic再次校验，如果status是"unknown"或空字符串，就判定为校验失败，同样走降级。这个双重校验，把“假成功”的概率从我们早期的18%降到了0.02%。还有一个经验：永远不要相信工具的“默认值”。在tool代码里，把所有默认值都改成None或显式的error code，让框架层统一处理降级，而不是让错误在工具内部就悄悄掩盖。

4.3 陷阱三：Prompt膨胀的“雪球效应”——当知识库变成负担

单智能体的一大诱惑，是能把所有业务知识、规则、FAQ都塞进prompt，号称“一个prompt打天下”。这在初期确实爽，但很快就会陷入“Prompt膨胀”的泥潭。一个原本2000 tokens的prompt，随着业务规则增加、新工具加入、各种edge case补充，三个月后可能变成12000 tokens。结果就是：LLM推理变慢、出错率飙升、缓存失效、成本暴涨。我们见过最夸张的案例，一个电商导购单智能体，prompt长达18000 tokens，其中70%是冗余的SKU描述和过期促销规则，导致P95延迟从400ms涨到2.1秒，且每天都有用户投诉“回答太慢”。破局之道，是实施“Prompt分层治理”。我们把prompt拆成三个层次：基础层（Base Layer）、领域层（Domain Layer）、会话层（Session Layer）。基础层，是所有单智能体共用的、不变的骨架，包括角色声明、核心指令、响应格式、通用工具目录。它很小，约500 tokens，由架构组统一维护。领域层，是业务相关的、相对稳定的规则和知识，比如“车险续保规则V2.3”、“医保报销比例表”。这部分，我们不塞进prompt，而是存在向量数据库里，用RAG方式按需检索。当LLM需要查规则时，它会生成一个 ，框架层捕获这个指令，去向量库搜索，把最相关的3条规则片段，作为<DOMAIN_KNOWLEDGE>注入prompt。会话层，是本次交互独有的、高度动态的信息，比如用户画像、当前任务状态、上轮对话摘要。它最小，但最关键，由状态机实时生成。这样，prompt size被牢牢控制在3000-4000 tokens的黄金区间，既保证了LLM的理解力，又兼顾了性能和成本。这个分层，让我们的prompt维护成本降低了65%，新业务规则上线时间从3天缩短到2小时。记住：Prompt不是知识仓库，它是LLM的“操作手册”。手册要精炼，知识要按需供给。

4.4 陷阱四：LLM的“创造性”与业务的“确定性”冲突——当它开始“编造”答案

这是单智能体最本质的矛盾：LLM的天赋是创造，而业务系统的要求是确定。当LLM被赋予过多自由度，它就会在你意想不到的地方“发挥创意”。典型表现有三：一是编造不存在的工具调用。比如prompt里只定义了get_policy_status和generate_quote两个tool，但LLM却生成了<TOOL_CALL name='calculate_discount' .../>，因为“calculate_discount”听起来很合理。二是虚构不存在的数据。当get_policy_status返回{"status": "unknown"}时，LLM为了不显得无能，会自己编一个{"status": "expired", "expiry_date": "2024-12-01"}。三是过度解读用户意图。用户问“我的保单到期了吗？”，LLM不仅回答“是”，还主动建议“您可能需要考虑升级保障”，而这个建议，既不在契约里，也没有工具支持。这些“创意”，在demo里是亮点，在生产环境里是灾难。我们的防御体系，是“三道防火墙”。第一道，是语法防火墙：框架层在解析LLM输出时，只认prompt中tool catalog里明确定义的tool name。任何未定义的tool call，直接报错，绝不执行。第二道，是数据防火墙：所有tool的output_schema，都定义了严格的枚举和格式约束。LLM返回的任何不符合schema的数据，框架层在注入到下一轮prompt前，就强制替换为None或预设的error code。第三道，是意图防火墙：在system message里，用最强硬的语气锁定LLM的行为边界：“你只能执行以下工具：[列出tool]。你只能回答以下问题类型：[列出question types]。对于任何超出范围的请求，你必须回答：‘抱歉，我目前无法处理该请求。’”。这三道墙，把LLM的“创造力”关进了业务规则的笼子里。在某次压力