1. 为什么“最小循环”不是起点，而是陷阱？

很多人一接触 AI Agent，第一反应就是打开文档，照着示例代码敲一个“while True: user_input → LLM → parse → execute → output”四步循环。我去年带三个实习生做内部知识助手时，也这么干过——结果两周后系统在生产环境凌晨三点开始疯狂重试、超时、返回空字符串，日志里全是“tool not found”和“function call malformed”。回溯才发现，那个被我们当作“最小可行”的循环，根本不是最小，而是最危险的幻觉。

所谓“最小循环”，本质是把 Agent 当成一个更聪明的命令行脚本：输入→思考→调用→输出。但现实中的可靠系统，从来不是靠“能跑通”定义的，而是靠“在异常中不崩溃、在模糊中不乱猜、在超时后有退路”定义的。比如用户问“帮我查下上个月销售Top3的客户，顺便生成PPT”，这个请求里藏着至少五个隐性断点：LLM是否理解“上个月”在财务周期里的具体范围？工具是否支持跨表关联查询？PPT生成工具能否处理中文标题换行？网络抖动时API返回408，是重试三次还是降级为纯文本摘要？当用户中途打断说“等等，改成前五名”，整个执行链路如何安全中断并释放资源？

这些不是锦上添花的优化项，而是从第一行代码就必须设计的骨架。我后来重写了整个架构，把“循环”拆解成七个不可跳过的原子状态：Input Sanitization → Intent Disambiguation → Tool Schema Validation → Execution Orchestration → Timeout Graceful Degradation → Output Structured Rendering → Feedback Loop Logging。每个状态都强制要求返回明确的状态码（如STATE_INPUT_CLEAN/STATE_INTENT_AMBIGUOUS/STATE_TOOL_SCHEMA_MISMATCH），而不是让下游去猜“这个JSON是不是合法的function call”。

提示：不要用while True启动你的第一个Agent。先写一个状态机，哪怕只实现Input Sanitization和Intent Disambiguation两个状态，用真实业务语句测试——比如“把Q3报表发给王总，抄送李经理，用公司模板，加水印”。你会发现90%的失败不在LLM推理，而在输入解析阶段就已埋雷。

这背后是认知范式的切换：Agent 不是“会调用工具的LLM”，而是“以LLM为决策核心的分布式状态协调器”。它的可靠性不取决于单次推理的准确率，而取决于状态跃迁的确定性。就像汽车引擎的可靠性不看单次点火成功率，而看曲轴连杆在2000转/分钟持续运转10万公里后的形变公差。我们接下来要拆解的，正是这个状态协调器的物理结构——它由什么材料构成？各部件如何咬合？失效时哪部分最先变形？

2. Agent Loop 的物理结构：从纸面流程图到可部署模块

市面上90%的Agent教程把Loop画成一个圆圈：User Input → LLM → Function Calling → Tool → LLM → Output。这种图对理解概念有用，但对工程落地有害——它掩盖了所有需要物理隔离的边界。真正的Agent Loop不是逻辑闭环，而是由六个物理隔离层组成的流水线，每层之间通过明确定义的契约（Contract）通信，而非共享内存或全局变量。

2.1 输入净化层：拒绝“干净输入”的幻觉

几乎所有线上故障都始于这一层。用户输入“查下张三的订单”，但没说哪个系统（ERP/CRM/售后平台）、哪个时间范围（创建时间/发货时间/支付时间）、是否包含已取消订单。如果直接把这句话喂给LLM，模型大概率会自行补全假设，比如默认查ERP系统近30天数据——而实际业务要求是CRM系统近7天有效订单。

我们采用三级净化机制：

• 语法层：用正则+有限状态机识别基础结构（如“查[XX]的[YY]”、“把[AA]发给[BB]”），提取原始槽位，不依赖LLM。
• 语义层：调用轻量级分类模型（TinyBERT微调版，<5MB）判断意图类别（查询/操作/生成/解释），并标注置信度阈值（<0.7则触发澄清）。
• 上下文层：注入会话历史摘要（非原始记录，而是结构化摘要：“用户身份：销售总监；当前项目：华东区Q3复盘；最近操作：导出客户列表”），约束LLM的补全空间。

实测效果：在金融客服场景中，输入净化层将LLM因歧义导致的错误function call降低76%，且平均响应延迟仅增加23ms（纯CPU计算，无GPU依赖）。

2.2 意图解析层：LLM不是翻译器，而是协议转换器

很多团队卡在这里：LLM返回的function call JSON格式正确，但参数值完全错误。比如工具要求{"customer_id": "CUST-2024-XXXX"}，LLM却填入{"customer_id": "张三"}。这不是模型能力问题，而是角色定义错误——你让LLM当翻译，它却在做推理。

我们的解法是强制LLM扮演“协议转换器”：

1. 预定义工具契约（Tool Contract）为YAML格式，包含字段类型、约束、示例值；
2. 在System Prompt中明确指令：“你只能按以下契约格式输出JSON，字段名、类型、约束必须100%匹配，禁止添加/删除/改名任何字段，禁止填充示例值以外的值”；
3. 输出后增加Schema校验层（JSON Schema Validator），不匹配则直接报错STATE_TOOL_SCHEMA_MISMATCH，绝不尝试修复。

关键细节：契约中的description字段必须写业务语义，而非技术说明。比如写“客户唯一编码，格式为CUST-年份-6位数字，可在CRM系统客户详情页URL中找到”，而不是“string, pattern: ^CUST-\d{4}-\d{6}$”。前者让LLM理解“为什么需要这个格式”，后者只是让它机械匹配正则。

2.3 工具编排层：不是调用工具，而是管理工具生命周期

Function Calling常被误解为“LLM告诉系统调什么”，实际应是“系统根据LLM的决策，启动、监控、回收工具实例”。我们把工具抽象为容器化服务（Docker），每个工具实例有独立资源配额（CPU/Memory/Timeout）和健康检查端点。

编排逻辑分三阶段：

• 准入检查：验证工具版本兼容性（如PPT生成工具v2.3要求LLM输出含slide_layout字段，否则拒绝执行）；
• 沙箱执行：工具在受限容器中运行，禁止网络外联，文件系统只读（除指定output目录）；
• 结果归一化：无论工具返回HTML/PDF/JSON，统一转换为标准结构体{data: {...}, metadata: {tool_name, version, exec_time}}。

曾有个案例：Excel处理工具在大文件时内存溢出，但LLM仍返回“success”。通过沙箱OOM信号捕获+结果归一化层的metadata.exec_time > 30s规则，自动触发降级策略——改用流式处理API分片计算，而非让LLM重试。

2.4 状态协调层：让“循环”变成“有向无环图”

真正的可靠性来自状态跃迁的确定性。我们用Apache Airflow的DAG概念重构Loop：每个状态是节点，边是状态码。例如：

STATE_INPUT_CLEAN → STATE_INTENT_DISAMBIGUATED (code 200) STATE_INTENT_DISAMBIGUATED → STATE_TOOL_CALL_VALID (code 201) STATE_TOOL_CALL_VALID → STATE_TOOL_EXECUTING (code 202) STATE_TOOL_EXECUTING → STATE_TOOL_SUCCESS (code 200) STATE_TOOL_EXECUTING → STATE_TOOL_TIMEOUT (code 408) → STATE_DEGRADE_TO_TEXT (code 200)

关键设计：所有状态跃迁必须幂等。同一状态码重复进入，结果必须一致（如多次STATE_TOOL_TIMEOUT都触发相同降级路径）。这避免了网络重传导致的状态混乱。

注意：不要用Redis的INCR做状态计数器。我们曾因Redis集群脑裂，导致同一请求被计为两次timeout，错误触发双倍降级。现在改用PostgreSQL的INSERT ... ON CONFLICT DO NOTHING保证状态跃迁原子性。

3. Tool 的本质：不是插件，而是契约化的业务能力单元

行业里常把Tool叫“插件”或“技能”，这导致两个致命误区：一是认为Tool越多越好，二是认为Tool可以随意组合。实际上，Tool是业务能力的契约化封装，它的价值不在于数量，而在于契约的严谨性和可组合性。

3.1 Tool契约的四个不可妥协维度

一个合格的Tool契约必须同时满足：

• 输入契约：字段名、类型、必填性、取值范围、业务含义。例如CRM查询Tool的date_range字段，不能只写“string”，而要定义{"start": "2024-01-01", "end": "2024-01-31", "unit": "day"}，并注明“unit支持day/month/quarter，start/end必须符合财务周期规则”。
• 输出契约：结构、字段语义、空值约定。如“若无结果，返回{"customers": []}而非{"error": "not found"}，保持下游解析一致性。
• SLA契约：最大响应时间、错误码体系、重试策略。明确写“99%请求<2s，超时返回HTTP 408，客户端应重试1次后降级”。
• 安全契约：数据权限、审计日志、PII脱敏规则。如“返回客户信息时，手机号自动掩码为138****1234，身份证号全字段过滤”。

我们曾因某财务Tool的SLA契约缺失，导致批量报表生成任务在高峰期排队超10分钟，LLM因等待超时反复重试，最终压垮数据库连接池。补上SLA后，上游自动启用队列限流+异步通知模式。

3.2 Tool组合的物理约束：为什么不能随便拼接

“让LLM决定调用顺序”听起来很AI，实则高危。两个Tool的组合必须满足数据流契约和时序契约：

• 数据流契约：Tool A的输出结构必须100%匹配Tool B的输入结构。我们用JSON Schema Diff工具自动检测，差异>0即阻断发布。
• 时序契约：某些Tool存在强依赖关系。如“发送邮件”Tool必须在“生成报告”Tool成功后调用，且中间不能插入其他操作。我们在DAG编排层硬编码依赖关系，而非交给LLM动态决策。

真实案例：市场部要求“生成竞品分析报告→自动发邮件→同步到钉钉”。表面看是三个Tool串联，但“同步到钉钉”需依赖邮件发送后的Message-ID作为溯源凭证。若LLM擅自调整顺序，或插入“保存草稿”Tool，整个链路就断裂。解决方案是将这三个动作封装为一个复合Tool，对外暴露单一契约，内部实现时序控制。

3.3 Tool的演进：从函数到服务，再到能力市场

初期团队常把Tool写成Python函数，随LLM代码一起部署。这导致三个问题：更新需重启服务、不同语言LLM无法复用、安全审计困难。我们的演进路径是：

1. 函数阶段：快速验证，但严格限制为纯计算（无IO、无网络）；
2. HTTP服务阶段：每个Tool独立部署为gRPC服务，契约通过Protobuf定义，天然支持多语言客户端；
3. 能力市场阶段：建立内部Tool Registry，支持版本管理、使用统计、权限分级（如财务Tool仅开放给Finance组）。

关键经验：Tool的URI不应是/api/v1/crm/search，而应是/capability/crm/customer_search@v2.1。@v2.1确保契约变更时，旧版LLM仍可调用，新版LLM自动发现升级。

4. Model 的选择陷阱：不是越大越好，而是契约匹配度越高越好

搜索热词里充斥着“GPT-5.6-SOL”“GPT-6.1-SOL”这类不存在的型号，反映行业普遍存在的模型幻觉——以为更强的模型能解决所有Agent问题。真相是：Model在Agent架构中只是决策引擎，它的价值取决于与Tool契约的匹配精度，而非参数量。

4.1 模型能力的三个真实维度

评估Model不能只看benchmark分数，必须考察：

• 契约遵循能力（Contract Adherence）：在给定Tool契约下，生成JSON的字段名、类型、约束符合率。我们测试过7个主流模型，Claude-3 Haiku在字段名匹配率上达98.2%，而某国产大模型仅73.5%（常把customer_id错写为cust_id）。
• 长程状态记忆（State Retention）：在多轮Tool调用中，保持上下文一致性。例如用户说“把刚才生成的报告发给张三”，Model必须准确关联“刚才”指代前一轮的PPT生成结果。Llama-3-70B在此项表现最优（92.1%），因其KV Cache优化更适合状态维持。
• 错误恢复能力（Error Recovery）：当Tool返回错误（如{"error": "customer not found"}），Model能否生成合理降级指令（如“请用户提供客户手机号或邮箱进行模糊查询”），而非死循环重试。Gemini-1.5 Pro在此场景错误恢复率最高（89.3%）。

实测心得：别迷信“100万上下文”。我们曾用支持128K上下文的模型处理10轮对话，但因KV Cache未优化，第7轮后就开始混淆客户ID。反而是上下文8K但专为Agent优化的Phi-3-mini，在20轮内保持99.6%状态准确率。

4.2 模型与Tool的耦合设计：让模型“少思考，多匹配”

最高效的Agent不是让Model做复杂推理，而是让它专注做两件事：精准匹配Tool契约+清晰表达失败原因。为此我们设计三层提示工程：

• 契约锚定层：在System Prompt中固化Tool契约片段，如“你只能调用以下Tool：CRM_SEARCH，其输入必须为{...}，输出必须为{...}”；
• 错误反射层：当Tool返回错误，Prompt强制要求“先原样复述错误信息，再给出1个具体、可执行的用户引导”；
• 降级声明层：预设降级路径，如“若CRM_SEARCH失败，则调用CUSTOMER_LOOKUP_BY_PHONE”。

这种设计让Model从“全能决策者”降级为“高精度协议处理器”，大幅降低幻觉率。在电商客服场景，契约锚定层使无效function call减少81%。

4.3 模型部署的物理隔离：为什么不能共用一个API端点

很多团队用同一个/v1/chat/completions端点服务所有Agent任务，这导致三个隐患：

• 资源争抢：高优先级任务（如支付确认）被低优先级任务（如闲聊）拖慢；
• 契约污染：不同Tool的契约混在同一个模型上下文中，增加解析歧义；
• 灰度困难：升级模型时，所有Agent功能同时切换，无法AB测试。

我们的解法是按契约粒度部署模型：

• crm-agent-model：专精CRM契约，加载CRM领域微调权重；
• report-agent-model：专精报表生成契约，内置PPT/Excel Schema；
• fallback-model：极简架构，仅处理错误恢复和用户引导。

每个模型端点独立扩缩容，CRM模型在促销期自动扩容至20节点，而fallback模型始终维持2节点。运维复杂度上升，但故障隔离性提升300%。

5. 从单点循环到可靠系统的七项硬核实践

把“最小循环”变成“可靠系统”，不是堆砌技术，而是建立七条不可妥协的工程纪律。这些纪律来自我们踩过的137个坑，其中42个发生在生产环境。

5.1 状态日志必须包含“可逆性标识”

所有状态跃迁日志必须记录reversible_id（如session_abc123_step4），该ID能唯一定位到本次决策的全部上下文快照。当用户投诉“Agent把我的订单删了”，运维人员输入ID，5秒内还原当时LLM输入、Tool输入、Tool输出、降级策略——而不是翻三天日志。

关键实现：reversible_id由session_id + step_seq + hash(input_payload)生成，确保相同输入永远产生相同ID。我们不用UUID，因为UUID无法关联输入内容。

5.2 所有Tool必须实现“幂等执行”

用户连续点击“生成报告”按钮三次，系统必须返回同一份报告，而非创建三份。实现方式：

• Tool接收请求时，先查request_id（由前端生成并透传）是否已存在；
• 若存在，直接返回缓存结果；
• 若不存在，执行业务逻辑并写入缓存。

曾有个财务Tool未实现幂等，导致用户重复提交后，系统生成三份相同编号的发票，引发税务稽查风险。

5.3 降级策略必须“用户可见且可控”

当Tool超时，不能静默降级为文本摘要。必须向用户明确告知：“PPT生成较慢，已为您生成文字版摘要，是否需要继续等待？”并提供“继续等待”/“下载文字版”/“取消”三个按钮。用户选择权是信任基石。

技术实现：在状态协调层，STATE_TOOL_TIMEOUT不直接跳转STATE_DEGRADE_TO_TEXT，而是进入STATE_USER_CONFIRM_DEGRADE，等待前端交互。

5.4 模型输出必须通过“双校验管道”

LLM输出的function call JSON，必须经过：

• Schema校验：字段名、类型、必填性；
• 业务校验：调用前模拟执行（如检查customer_id是否存在于缓存白名单）。

双校验失败时，不返回错误给用户，而是触发STATE_REASK_WITH_HINT——向用户提问：“您说的‘张三’是指CRM系统中的客户张三，还是微信联系人张三？请提供手机号以便确认。”

5.5 工具链路必须“端到端可观测”

每个Tool调用必须记录：

• input_hash（输入内容SHA256）
• output_hash（输出内容SHA256）
• exec_time_ms
• resource_usage（CPU/Mem峰值）

这些指标接入Prometheus，设置告警：avg_over_time(exec_time_ms[1h]) > 5000。曾因此提前发现数据库索引失效，避免了大规模超时。

5.6 安全边界必须“物理隔离”

• LLM运行在无网络的VPC子网；
• Tool服务运行在独立安全组，仅允许LLM子网IP访问；
• 所有PII数据（手机号、身份证）在进入LLM前，由前置服务脱敏，LLM永远看不到明文。

我们禁用任何“LLM直接访问数据库”的方案，哪怕测试环境也不允许。

5.7 迭代必须“契约先行”

新增Tool时，流程必须是：

1. 编写YAML契约（含输入/输出/SLA/安全条款）；
2. 团队评审契约（开发、产品、安全三方签字）；
3. 基于契约生成Mock服务；
4. LLM调用Mock服务完成集成测试；
5. 最后才实现真实Tool。

契约评审通过率不足80%，项目立即暂停。这让我们避免了7个本会失败的Tool上线。

最后分享一个真实体会：去年上线的客户合同审核Agent，初期追求“全自动”，结果因法律条款歧义导致3份合同误判。后来我们加入人工复核节点，当LLM置信度<0.95时，自动转交法务。上线半年后，法务反馈“现在每天只处理5份待复核合同，比原来手动审50份还轻松”。可靠不是100%自动化，而是让每个环节都在它最擅长的确定性区间工作——LLM负责快速初筛，人类负责最终裁决，Tool负责精准执行。这才是Agent该有的样子。