核心命题Agent 交付的不是对话能力而是可控的动作执行。一句话带走Agent 交付的核心不是「让 AI 能调工具」而是把每个不可逆动作变成可确认、可重试、可兜底的动作。知识库问答解决的是「给出信息」但很多企业场景需要「完成动作」创建工单、生成 CRM 更新草稿、查询订单状态、安排会议、发送通知或触发审批。一旦 AI 开始执行动作交付风险就从「回答是否准确」扩大到「动作是否被授权、参数是否正确、失败是否可恢复、重复执行是否会造成损失」。RAG 问答的风险是「回答不准确」但 Agent 的风险是「动作出错」——创建了错误的工单、写错了 CRM 数据、触发了不该触发的审批。动作一旦执行可能造成实际业务损失而且很难回滚。所以 Agent 的交付标准比问答高得多不能只做个会调 API 的聊天框。两个典型事故•某客服 Agent用户说「帮我查一下订单」Agent 理解成「取消订单」直接调用了取消订单的 API导致客户订单被误取消•某销售助手 Agent网络超时后重试结果创建了 3 条重复的 CRM 跟进记录销售花了半天时间清理因此Agent 不能只被设计成一个会调用工具的聊天机器人。它必须有明确的动作边界、参数校验、幂等机制、失败处理和人工接管流程。本章讲清楚五件事Agent 的最小交付模型是什么、工具怎么设计、状态机怎么建、失败怎么处理、销售助手案例怎么落地。一、Agent 的最小交付模型五个组件缺一不可一个可交付的 Agent 至少包含以下五个组件少一个都不能上线组件作用不做的后果任务理解把用户的自然语言指令解析成明确的任务动作参数Agent 不知道要做什么乱调用工具工具集一组职责单一、参数结构化、有权限校验的工具工具太粗权限和审计没法做状态机显式管理任务的执行状态待执行/执行中/待确认/已完成/失败用户看不到进度失败了不知道怎么恢复权限校验每个工具调用前校验用户是否有权执行该动作越权操作合规事故失败处理可重试错误重试、不可重试错误转人工、幂等防重复重复执行、错误扩散、用户体验差为什么必须有状态机没有状态机的 Agent 是「黑盒」——用户发一个指令然后看到一个加载动画最后要么成功要么失败中间发生了什么不知道。有了状态机用户能看到「正在查询订单」「正在等待您确认」「执行失败已转人工」体验和可控性完全不同。为什么必须有权限校验问答场景下用户最多看到不该看的内容Agent 场景下用户可能执行不该执行的动作如删除数据、修改配置。所以每个工具调用前都要校验权限而且是服务端校验不能信任前端传的权限标识。五个组件的关系任务理解是入口——它决定了 Agent 要做什么工具集是能力——它决定了 Agent 能做什么状态机是过程——它让执行过程可见、可控、可恢复权限校验是边界——它确保 Agent 不做超出授权的事失败处理是兜底——它确保出错时不会造成不可逆的损失。五个组件形成一个完整的闭环缺一不可。组件冲突时谁优先五个组件平时各司其职但在边界情况下会互相冲突这时候必须有明确的优先顺序否则实现者会按各自的理解排布导致同类事故反复出现。冲突场景优先方理由权限校验 vs 任务理解权限校验即使用户的指令被正确理解了无权执行的动作也不能执行——不可授权的事理解得再对也不做权限校验 vs 失败处理权限校验权限不足属于不可重试错误不应该进入重试队列消耗资源失败处理 vs 状态机状态机失败必须落到一个明确的状态执行失败 / 转人工不能被 try/catch 吞掉状态机 vs 用户体验状态机不能为了少显示几个中间态而跳过「待确认」——高风险动作的确认环节不可省略任务理解 vs 工具集工具集如果任务理解出的动作不在工具集里正确行为是明确告知「做不到」而不是临时拼凑一个调用这张表的用法冲突发生时永远优先保住「安全」和「可追溯」而不是优先保住「自动化程度」或「体验流畅」。因为前者的损失不可逆后者的损失只是一次交互不够顺。二、以销售助手为例Agent 怎么落地销售助手可以读取客户跟进记录生成「待更新 CRM」的草稿但首期不直接修改 CRM 主数据。销售确认草稿后系统才可以进入写入流程涉及客户状态变更、批量修改或跨团队操作时需要更高等级审批。这个边界看似降低了自动化程度实际上提高了可控性。AI FDE 应优先交付用户愿意接受且出错后容易补救的动作。销售助手的工具集•get_customer_followups(customer_id)读取客户跟进记录只读权限要求低•create_crm_draft(customer_id, summary, next_action, source_ids)生成 CRM 更新草稿不直接写入主数据•submit_crm_change(draft_id)提交草稿到 CRM需要用户确认后才能调用•request_manager_approval(change_id)发起经理审批高风险动作首期边界只做前两个工具读取和生成草稿不做直接写入。这样即使 Agent 出错最多是生成了错误的草稿销售确认时能发现不会污染 CRM 主数据。二期再开放「提交草稿」和「经理审批」但需要更强的校验和审计。案例某销售助手首期上线只做「读取跟进记录 生成摘要草稿」。销售每周五用一次确认草稿后手动写入 CRM。运行 1 个月后用户反馈「摘要准确率 92%希望能自动写入」。二期才开放「提交草稿」功能并加了三重校验草稿内容不能为空、必须有引用来源、提交前必须用户点确认按钮。上线后没有出现过错误写入。分阶段放开的逻辑首期做只读 草稿是为了建立用户对 Agent 的信任。用户用了一个月发现 Agent 生成的草稿质量不错92% 准确率才会愿意让它直接写入。但即使二期开放了写入也要保留「用户确认」这个环节——因为 Agent 出错的成本污染 CRM 主数据远高于用户确认的成本多点一个按钮。只有当 Agent 的准确率持续稳定在 99% 以上且出错后容易回滚时才考虑三期自动写入。三、工具设计原则三个原则避免 Agent 失控1. 工具职责单一不要提供一个名为update_everything的大工具。更好的做法是拆成•get_customer_followups读取跟进记录•create_crm_draft创建草稿•submit_crm_change提交变更•request_manager_approval发起审批为什么要拆工具越具体权限判断、参数校验、审计和测试越容易。如果一个工具能做所有事那权限只能是「要么全给要么全不给」没法做细粒度控制。而且出了问题也不知道是哪个动作出的错。案例某 Agent 早期有个update_crm工具能改客户的任何字段。后来发现销售 A 用它改了客户的owner本来只有经理能改导致客户被「抢」走了。拆分成update_crm_basic改基本信息和transfer_customer_owner改 owner需要经理审批后越权问题就解决了。2. 参数必须结构化工具输入应使用明确字段而不是一段自然语言。例如更新草稿需要customer_id、summary、next_action和source_ids并在服务端再次校验这些字段。为什么要结构化自然语言参数无法校验Agent 可能把「张三的客户」当成 customer_id 传进去。结构化参数可以做类型校验、范围校验、权限校验。错误示例update_crm(帮我把张三的客户跟进改成已签约)—— 无法校验不知道要改哪个客户、改成什么正确示例update_crm_draft( customer_idcust-001, summary客户已确认签约等待合同盖章, next_action跟进合同盖章进度, source_ids[followup-001, followup-002] )每个字段都有明确含义服务端可以校验 customer_id 是否存在、用户是否有权访问、source_ids 是否是真实的跟进记录。3. 关键动作必须幂等客户端重试、网络超时和模型重复调用都可能造成重复写入。每一次业务动作应携带idempotency_key服务端使用它判断请求是否已经处理。为什么要幂等Agent 调用工具时可能因为网络超时不知道是否成功于是重试。如果没有幂等就会重复执行——创建两条工单、写两次 CRM、发两封邮件。实现方式def create_ticket(idempotency_key, title, content, user_id): # 先用幂等键查有没有已处理的请求 existing db.find_by_idempotency_key(idempotency_key) if existing: return existing # 已处理过直接返回结果不重复创建 # 没处理过创建工单 ticket Ticket(titletitle, contentcontent, user_iduser_id) db.save(ticket) # 记录幂等键和结果的映射 db.save_idempotency_key(idempotency_key, ticket.id) return ticket幂等键怎么生成关键在于幂等键必须由调用方在首次发起时生成并在重试时原样复用而不是每次调用重新计算。常见错误是让服务端按「用户 动作 时间戳 随机数」去算键——这样每次调用都会得到不同的值重试时自然对不上幂等形同虚设事故照样发生。正确的做法分三档方案幂等键适用客户端生成推荐首次调用时生成 UUID重试时复用同一个绝大多数写操作业务自然键用业务上唯一的字段组合如订单号 操作类型有天然唯一键的场景服务端生成 客户端回传服务端下发客户端后续请求带回无法在客户端生成时注意幂等键的有效期。幂等记录不能永久保留也不能太短太短则超时重试落在窗口外仍会重复太长则表会无限膨胀。通常设 24 小时与业务的重试窗口对齐。另外幂等记录要存结果而不只是「已处理」标记——重试时直接返回第一次的结果调用方拿到的响应才是完整的。案例某工单 Agent 上线后用户反馈「我只说了一次怎么创建了 3 条工单」。排查发现是网络超时后 Agent 自动重试了 3 次而服务端没有幂等校验。加了idempotency_key后重试时直接返回第一次创建的工单问题解决。四、Agent 状态机让执行过程对用户可见把状态显式化前端就可以向用户展示「正在等待审批」「工具调用失败」「已转人工」而不是一直显示一个无法解释的加载动画。销售助手的状态机[待执行] → [解析中] → [待确认] → [执行中] → [已完成] │ │ │ ↓ ↓ ↓ [解析失败] [用户拒绝] [执行失败] → [转人工]三条失败分支各自对应一个前置状态不要混在一起看失败分支从哪个状态分出含义解析失败解析中Agent 无法理解指令连续 2 次失败后转人工用户拒绝待确认用户看了草稿后点「取消」任务终止不是失败执行失败执行中工具调用出错按第五节的规则判断重试还是转人工每个状态的含义状态含义前端展示可执行的动作待执行Agent 刚收到指令还没开始「已收到您的请求」取消解析中Agent 正在理解指令、决定调用哪个工具「正在理解您的需求...」取消待确认Agent 已生成草稿等用户确认展示草稿「确认执行 / 修改 / 取消」确认、修改、取消执行中Agent 正在调用工具「正在执行...」取消如果工具支持取消已完成执行成功展示结果「完成」查看详情、重新执行执行失败工具调用失败展示失败原因「重试 / 转人工」重试、转人工转人工已通知人工介入「已为您转接人工请稍候」等待为什么状态机要显式化用户体验用户知道当前在做什么不会一直盯着加载动画猜可控性用户可以在关键节点待确认介入避免错误执行可恢复性执行失败时用户知道是重试还是转人工而不是卡死可审计每个状态转换都有日志出了问题能回放案例某审批 Agent 早期没有状态机用户点了「审批通过」后看到一个加载动画30 秒后提示「成功」。但有时候其实超时了用户以为成功了实际没通过。加了状态机后用户能看到「正在提交审批」「提交成功/失败」失败时可以重试体验和可靠性都提升了。状态机与工具调用的对应关系每个工具调用都应该对应一个明确的状态转换。比如调用create_crm_draft时状态从「解析中」转为「待确认」调用submit_crm_change时状态从「执行中」转为「已完成」或「执行失败」。如果工具调用返回了非预期结果比如超时状态机应该明确记录这个异常而不是默默吞掉错误。五、失败处理三类错误三种处理方式可重试错误网络超时、服务暂时不可用、限流和短暂连接失败通常可以重试但要设置最大次数、退避策略和幂等键。重试策略•最大重试次数3 次避免无限重试•退避策略指数退避1s → 2s → 4s避免雪崩•幂等键重试时用同一个幂等键避免重复执行•超时设置每次重试都有超时不会无限等待案例某 Agent 调用工单系统 API高峰期经常 429限流。早期没有重试直接报错「创建失败」。加了重试3 次指数退避后成功率从 85% 升到 99%。不可重试错误参数格式错误、权限不足、客户不存在和业务规则冲突不应无休止重试。系统应该解释问题并要求用户补充信息或转人工。为什么不能重试这些错误重试也不会成功只会浪费资源和用户时间。比如权限不足重试 100 次还是权限不足应该直接告诉用户「您没有权限执行此操作请联系管理员」。处理方式•参数格式错误告诉用户哪个参数错了应该怎么填•权限不足告诉用户没有权限建议联系谁•客户不存在告诉用户客户 ID 不存在请核对•业务规则冲突告诉用户冲突的原因如「该客户已存在跟进记录」人工接管人工接管不是 Agent 失败后的临时补丁而是高风险流程的一部分。交接时应保留用户问题、已执行步骤、工具返回、失败原因和待人工确认内容。什么时候必须转人工•执行失败且重试无效•涉及高风险动作如删除数据、批量修改、跨团队操作•用户明确要求人工•Agent 无法理解用户意图连续 2 次解析失败交接内容不能少•用户的原始问题•Agent 已执行的步骤和调用的工具•工具返回的结果•失败的原因•待人工确认或处理的内容案例某财务 Agent用户说「帮我把这笔报销打回去」。Agent 解析后发现需要财务经理权限但用户是普通员工。Agent 没有直接报错而是转人工给财务经理并附上「用户请求驳回报销 #1234原因发票不合规」。财务经理 5 分钟内处理完用户体验很好。如果 Agent 直接报错「权限不足」用户还得自己找财务经理体验差很多。人工接管的工程实现转人工不是简单地弹一个「请联系客服」。它需要1把 Agent 的执行上下文用户意图、已执行步骤、工具返回、失败原因序列化为结构化数据传递给客服系统2客服接到后能看到完整的上下文不需要用户重复描述问题3人工处理完后结果要回写到 Agent 的状态机让 Agent 知道这个任务已经由人工完成了避免后续重复执行。把本章翻译成 AI FDE hub 工程契约从问答到执行AI Agent 的现场交付方法 这件事最终要落到一份能被四方签收的契约上。下面这份 YAML 就是它的字段模板# AI FDE hub · AI Agent 现场交付 · 工程契约示例 chapter: 006 framework: AI FDE hub 三段式交付入场 / 搭建 / 离场 tags: [AI, Agent, 工具调用, 工作流] scope: role: AI FDE 工程师 boundary: 对接客户业务负责人、合规、研发、测试四方共同验收 agent_model: components: [任务理解, 工具集, 状态机, 权限校验, 失败处理] tool_principles: - 职责单一一个工具只做一件事 - 参数结构化明确字段服务端校验 - 关键动作幂等idempotency_key 防重复 state_machine: [待执行, 解析中, 待确认, 执行中, 已完成, 执行失败, 转人工] failure_handling: retryable: 网络超时/限流/暂时不可用 → 最多3次指数退避幂等键 non_retryable: 参数错误/权限不足/不存在/规则冲突 → 解释原因补充信息或转人工 human_handoff: 失败且重试无效/高风险动作/用户要求/无法理解 → 保留上下文转人工和相邻章节的关系本章与前后相邻的第 5 章《AI FDE 如何设计企业知识库检索链路》、第 7 章《AI 应用的模型网关与可观测性》同处一个主题段共用同一套「产物 退出条件 决策门」语言——第 5 章解决「答得准」本章把链路推进到「做得对」第 7 章则给这条执行链路补上网关与可观测性让每次动作都能被追踪和限流。Toy Project vs. 生产级系统 · 8 项关键差异这张表聚焦 Agent 从演示走向生产时风险性质的变化。问答系统出错最多是答错Agent 出错是动了真实数据——所以下面每一项的差距都要按「是否可能造成不可逆损失」来评估而不是按功能是否齐全。维度Toy Project生产级系统差距代价工具设计一个大工具做所有事职责单一 参数结构化权限只能全给或全不给越权无从拦截幂等机制无重试就重复执行idempotency_key 防重复一次超时重试就产生重复工单人工清理成本远超开发成本状态管理黑盒只有加载动画显式状态机 前端展示用户以为成功了其实超时业务动作悬空权限校验前端判断或无服务端每次调用前校验用户能执行不该执行的动作如改客户归属失败处理try/catch 静默失败三类错误三种处理方式可重试的不重试不该重试的白等用户只能放弃人工接管无报错就结束保留上下文转人工用户被迫从头向人工复述问题绕一圈回到原点首期边界首期就开放所有动作首期只读草稿逐步放开首期就写坏主数据信任崩塌后难再推进审计追踪无日志每次工具调用记录完整上下文出错后无法还原「谁在什么时候触发了什么动作」客户现场最常见的三种反模式这三种做法在 Agent 交付现场反复出现共同点是都把 Agent 当成了一个「会调 API 的聊天框」而忽略了动作一旦执行就产生真实后果。提前识别比事后补救成本低一个数量级。反模式典型表现正确做法不推荐原因首期就开放写权限客户说「要自动写 CRM」首期就直接开放写入结果错误数据污染主数据首期只做只读草稿用户确认后再写入二期再逐步放开主数据被污染后清理成本极高且用户信任难以重建工具粒度太粗一个update_crm工具能改所有字段权限无法细分按字段和操作类型拆分工具每个工具只做一件事权限只能全给或全不给谁都可能改到不该改的字段没有幂等就上线网络超时后重试创建了重复的工单和 CRM 记录所有写操作必须携带 idempotency_key用户说一次却执行三次账目和记录全部失真附录AI Agent 现场交付速查一句话记法问答出错只是答错Agent 出错是动了真实数据——所以先划动作边界再谈自动化程度。本章五个组件怎么分工组件一句话职责上线前必须确认任务理解把自然语言指令解析成「动作 参数」解析不出的指令是否明确告知做不到而不是临时拼凑一次调用工具集提供职责单一、参数结构化的工具是否还存在一个能改所有字段的大工具状态机让执行过程可见、可控、可恢复待确认、执行失败、转人工是否都有前端展示权限校验服务端在每次调用前校验授权是否存在任何依赖前端传参的权限判断失败处理可重试的重试、不可重试的转人工、写操作幂等每个写操作是否都带 idempotency_key边界表边界首期做法放开条件读 vs 写只读 生成草稿不碰 CRM 主数据用户稳定使用一个月、草稿质量被认可后才提交草稿单条 vs 批量只处理单条动作单条写入零错误且幂等与审计记录齐备本人权限 vs 跨团队只做当前用户权限内的动作接入经理审批如 request_manager_approval低风险字段 vs 高风险字段只放开低风险字段如跟进备注高风险字段客户 owner、合同金额始终保留人工确认现场症状 → 根因判断 → 先做什么 → 不该做什么现场症状根因判断先做什么不该做什么用户只说一次却生成了 3 条工单/记录写操作没有幂等超时重试直接重复执行给每个写操作补 idempotency_key由调用方首次生成、重试复用靠调低重试次数掩盖问题用户说「查订单」订单却被取消任务理解把动作解析错了且没有待确认环节高风险动作前加待确认状态让用户点确认把问题简单归因于「模型不够聪明」销售改了本不该他改的客户 owner工具粒度太粗一个工具能改所有字段按字段和操作类型拆分工具改 owner 单独走审批只在提示词里写「不要改 owner」用户点完按钮只看到加载动画最后不知成败没有显式状态机中间态被吞掉把待执行/解析中/待确认/执行中/已完成/执行失败/转人工显式化用一个 try/catch 把中间态全部吞掉权限不足时用户只收到一句报错不可重试错误被当成终态没有转人工保留原始问题、已执行步骤和失败原因转人工让用户自己去外部找对接人首期上线就写坏 CRM 主数据首期边界没设直接开放了写权限退回只读 草稿二期再逐步放开用「用户很急」作为跳过确认环节的理由一个判断顺序先问动作可不可逆——不可逆就必须有用户确认再问动作会不会重复——会重试就必须有幂等键再问动作会不会越权——有工具就必须有服务端权限校验最后问失败怎么办——必须有明确状态和转人工路径。四条都过才轮到讨论自动化程度。一句收尾Agent 交付的成熟度不看它能调多少工具而看它出错时能不能把损失兜住。和相邻章节的关系本章与第 5 章《AI FDE 如何设计企业知识库检索链路》、第 7 章《AI 应用的模型网关与可观测性》同处一个主题段——第 5 章保证「答得准」本章把链路推进到「做得对」第 7 章再给执行链路补上网关与可观测性让每次动作都能被追踪和限流。思考题客户说「我们的 Agent 要能自动帮销售写回 CRM」你觉得首期应该怎么做为什么参考答案首期不应该直接自动写回 CRM应该分三步走1首期只做「读取 CRM 跟进记录 生成更新草稿」销售确认后手动写入。这样即使 Agent 出错最多是草稿错了不会污染 CRM 主数据2二期开放「提交草稿到 CRM」但必须加三重校验草稿内容非空、有引用来源、用户点确认按钮3三期才考虑「自动写入」但仅限低风险字段如跟进备注高风险字段如客户owner、合同金额仍需人工确认。原因是 Agent 执行动作的风险远高于问答必须先建立信任再逐步放开权限。换个说法客户要的是「自动写回 CRM」但首期真正该交付的是一次不会造成损失的执行。这两者的差别在于「用户确认」这一个环节——它看起来减慢了自动化实际上把不可逆的动作变成了可撤销的动作。Agent 的边界从来不是「能做多少」而是「出错时损失能不能兜住」。AI FDE hub本文由 AI FDE hub 出品关注「AI PDE 陪跑计划」获取 AI 现场交付方法论