【Agent工程】1—— 演示成功不等于系统可用文章目录【Agent工程】1—— 演示成功不等于系统可用1. 演示成功不等于系统可用2. 本专栏在解决什么问题2.1 问题定义2.2 非目标3. 专栏内容划分与方向4. 最小上线闭环5. 工具面先分清三层边界6. 贯穿示例工单助手 Agent6.1 同一请求下的两种写法7. 可运行示意用字典描述一版最小任务卡片8. 四个常见误区9. 适用边界10. 术语速查11. 小结与下一篇摘要很多项目已经能把大模型接到几个工具上演示时偶尔成功真正难的是做成可长期运行的系统——任务可拆、权限可控、结果可验收、成本可封顶。本篇说明 Agent / 工具系统工程在解决什么问题、专栏后续大致写哪些方向并用工单助手作为贯穿示例给出一版最小任务卡片与验收代码。适合准备把 Agent 从演示推进到业务链路的工程师。读完可以判断当前停在演示层还是已经具备可上线系统的骨架。1. 演示成功不等于系统可用把模型接到工具以后常见的「成功」长这样提示词里写清目标挂上查库、改状态、发消息等工具人工连点几次看起来做对了这在演示里足够在业务里不够。演示通常不回答这次成功的条件是什么换一批工单是否仍成立写操作是否被限制在最小必要范围失败时如何重试、降级或交给人一次运行花了多少钱、会不会在循环里把预算烧光事后能否还原调用了哪些工具、改了什么状态本专栏把这类问题统称为Agent / 工具系统工程关注的不是又一个更炫的对话效果而是把工具调用做成有边界、有验收、有审计的系统能力。2. 本专栏在解决什么问题2.1 问题定义给定一个业务目标例如把符合条件的工单升级为紧急并通知值班一组可调用工具查询、写入、通知、检索代码等一个会规划步骤并调用工具的 Agent 运行时要求系统在约束内完成目标并且可验证有明确的完成定义与验收方式可约束工具权限与副作用范围事先声明可观测关键调用与状态变更留痕可控成本有超时、次数与费用上限2.2 非目标本专栏不展开模型预训练、微调配方的完整教程某一家厂商控制台的逐屏点击说明把 Agent 神化成「全自动替代全部岗位」的叙事模型能力当然重要但在工具系统里它往往只是规划与语言层真正决定能不能上线的常常是任务定义、权限边界与验收门禁。3. 专栏内容划分与方向后续内容按工程顺序展开先把任务与权限说清楚再谈多 Agent 与成本否则编排只会把混乱放大。方向主要讨论什么总览分清演示与可上线系统固定最小闭环任务与验收模糊目标如何拆成任务卡片与完成定义工具面工具注册、读写分离、作用域、危险操作编排单 Agent 闭环以及多 Agent 委托边界运行时上下文预算、限流、超时、幂等观测、成本与上线审计、评测、配额、灰度、回滚与人机协同常见切入方式项目现状更合适的阅读重点只会演示对话还没有任务卡片先读任务与验收再读工具面已有工具调用但权限混乱先读工具面再回头补任务卡片单 Agent 已稳定准备拆多 Agent验收做扎实后再读编排马上要接业务流量对照观测、成本与上线相关章节做检查不必按专栏顺序通读但若跳过任务与验收直接做多 Agent后面排障成本通常更高。4. 最小上线闭环把一版 Agent 系统视为「可以进入业务」至少要闭合下面五环环节最少产出物缺了会怎样目标一句话业务结果 非目标Agent 优化错误目标权限工具清单与读写边界误改生产或越权读取执行可追踪的调用轨迹出问题无法复盘验收命令、断言或对照表只剩「感觉对了」无法复现成本步数 / 时间 / 费用上限循环调用拖垮预算这五环是本专栏的验收骨架。后文每一块内容都会回到其中至少一环而不是另起一套口号。实践里可以用一句话自检如果无法用命令或断言证明「这次做完了」就还停留在演示层。任务卡片不是文牍而是把这句自检提前写成字段。五环不必一次做完美但上线前至少要能指出目标写在哪里、谁有写权限、失败如何发现、怎样判定完成、预算上限是多少。缺任何一项演示里的偶然成功都很难复现。5. 工具面先分清三层边界工具不只是「函数能调用」。工程上至少要分开三层发现层有哪些工具、参数是什么、返回什么Agent 规划依赖这一层的准确性。权限层当前角色是否允许调用只读工具与写操作是否分开挂载。副作用层调用会改哪些外部状态失败时是否可补偿、是否要求幂等键。很多演示把三层揉在一个 tools 数组里短期省事长期会在排障时付出代价分不清是提示词问题、权限问题还是工具本身的副作用设计问题。6. 贯穿示例工单助手 Agent后续篇章默认使用同一业务故事降低上下文切换成本。场景客服或值班同学提出——把工单 T-1024 升为紧急写明原因并通知值班频道。允许的工具示意工具类型说明get_ticket只读查询工单当前状态update_ticket_priority写入修改优先级add_ticket_comment写入追加备注notify_oncall写入外部副作用通知值班完成定义示例工单优先级为urgent备注中包含约定关键词如升级原因值班通知已发送或明确记录「通知失败并已降级」全程未调用未授权工具例如直接删单、改账单演示版只关心模型有没有说出正确步骤系统版还要关心步骤是否在权限内、验收是否可机器执行。6.1 同一请求下的两种写法维度演示写法系统写法输入一段自然语言自然语言 任务卡片或由拆分器生成卡片工具临时塞进提示词注册表声明运行时按角色挂载成功标准人看对话觉得对acceptance_report可返回passed失败处理再问一句模型重试策略、降级通知、人工接管事后聊天记录审计字段工具、参数摘要、结果码、耗时本专栏后文会反复使用这张对照表每当引入新机制多 Agent、限流、配额都先看它落在上表哪一列。7. 可运行示意用字典描述一版最小任务卡片下面代码不绑定某一家 Agent 框架只表达本专栏反复使用的数据结构。字段可以映射到具体编排器。from__future__importannotationsfromtypingimportAnydefbuild_ticket_upgrade_card(ticket_id:str,reason:str)-dict[str,Any]:构造工单升级任务卡片示意。return{goal:f将工单{ticket_id}升级为紧急并通知值班,non_goals:[删除工单,修改计费字段,读取无关客户隐私备注],allowed_tools:[get_ticket,update_ticket_priority,add_ticket_comment,notify_oncall,],write_tools:[update_ticket_priority,add_ticket_comment,notify_oncall,],acceptance:{priority_equals:urgent,comment_must_contain:[升级原因,reason],notify_required:True,},budgets:{max_steps:8,max_seconds:60,max_tool_calls:12,},}defacceptance_report(card:dict[str,Any],final_state:dict[str,Any])-dict[str,Any]:根据最终状态做最小验收示意不连真实系统。acccard[acceptance]checks{priority_ok:final_state.get(priority)acc[priority_equals],comment_ok:all(keyin(final_state.get(comment)or)forkeyinacc[comment_must_contain]),notify_ok:(notacc[notify_required])orbool(final_state.get(notified)),tools_ok:set(final_state.get(used_tools,[])).issubset(set(card[allowed_tools])),}checks[passed]all(checks.values())returnchecksif__name____main__:cardbuild_ticket_upgrade_card(T-1024,产线停机)# 假设某次运行后的终态成功路径final_state{priority:urgent,comment:升级原因产线停机,notified:True,used_tools:[get_ticket,update_ticket_priority,add_ticket_comment,notify_oncall,],}print(acceptance_report(card,final_state))再给一段越权路径对照说明验收为什么必须检查工具集合if__name____main__:cardbuild_ticket_upgrade_card(T-1024,产线停机)bad_state{priority:urgent,comment:升级原因产线停机,notified:True,used_tools:[get_ticket,update_ticket_priority,delete_ticket,# 未授权],}reportacceptance_report(card,bad_state)assertreport[passed]isFalseassertreport[tools_ok]isFalseprint(越权路径已被验收拦住:,report)这两段代码的重点不是把工单系统写完而是固定专栏口径先有任务卡片再谈 Agent 自由发挥验收必须可机器判断未授权工具即使结果碰巧对了也不能算通过8. 四个常见误区误区典型表现更稳妥的做法把对话当系统只保存聊天记录没有任务卡片先写目标拆解与完成定义工具权限过大读写、高危操作挂在同一角色用注册表与权限策略拆开只看成功率抽测几次「好像行」建立评测集与成本配额无人值守幻想无审计、无人工接管点准备灰度、回滚与人机协同项目若同时踩中前两条建议先不要上多 Agent把单 Agent 的权限与验收做稳收益通常更大。9. 适用边界本专栏适合已经能调用模型 API 或本地推理准备把工具链路产品化的工程师需要给 Agent 项目补权限、验收与审计的技术负责人本专栏不适合作为大模型数学原理第一课某一具体 IDE 插件的操作手册替代品「无需工程、只靠提示词即可上生产」的证明材料若主要短板是模型写不出可用代码或检索质量差应先补齐编码能力或检索评测工具系统工程解决的是调用与约束不能替代那两块基础。10. 术语速查术语含义Agent能按目标规划步骤并调用工具的运行时角色工具Tool可被调用的外部能力如查询、写入、通知任务卡片目标、非目标、允许工具、验收与预算的结构化描述完成定义怎样算做完最好可机器判定权限边界谁能调用哪些工具、读写是否分离副作用调用对外部状态的真实改变审计保留关键调用与决策轨迹便于复盘降级主路径失败时的保守替代路径11. 小结与下一篇回到文首的判断如果只有提示词和临时工具列表还没有任务卡片、权限边界与验收命令那么当前更接近演示而不是可上线系统。本篇固定了三件事专栏主线是任务 → 工具面 → 编排 → 运行时 → 观测与上线最小上线闭环是目标、权限、执行、验收、成本贯穿示例是工单助手 Agent下一篇进入「任务与验收」把模糊业务一句话拆成可执行的任务卡片字段并给出第一版拆分脚本。系列导航本篇为专栏第 1 篇下一篇【Agent工程】2—— 模糊目标到任务卡片撰写中 【Agent工程】（1）—— 演示成功不等于系统可用
【Agent工程】1—— 演示成功不等于系统可用文章目录【Agent工程】1—— 演示成功不等于系统可用1. 演示成功不等于系统可用2. 本专栏在解决什么问题2.1 问题定义2.2 非目标3. 专栏内容划分与方向4. 最小上线闭环5. 工具面先分清三层边界6. 贯穿示例工单助手 Agent6.1 同一请求下的两种写法7. 可运行示意用字典描述一版最小任务卡片8. 四个常见误区9. 适用边界10. 术语速查11. 小结与下一篇摘要很多项目已经能把大模型接到几个工具上演示时偶尔成功真正难的是做成可长期运行的系统——任务可拆、权限可控、结果可验收、成本可封顶。本篇说明 Agent / 工具系统工程在解决什么问题、专栏后续大致写哪些方向并用工单助手作为贯穿示例给出一版最小任务卡片与验收代码。适合准备把 Agent 从演示推进到业务链路的工程师。读完可以判断当前停在演示层还是已经具备可上线系统的骨架。1. 演示成功不等于系统可用把模型接到工具以后常见的「成功」长这样提示词里写清目标挂上查库、改状态、发消息等工具人工连点几次看起来做对了这在演示里足够在业务里不够。演示通常不回答这次成功的条件是什么换一批工单是否仍成立写操作是否被限制在最小必要范围失败时如何重试、降级或交给人一次运行花了多少钱、会不会在循环里把预算烧光事后能否还原调用了哪些工具、改了什么状态本专栏把这类问题统称为Agent / 工具系统工程关注的不是又一个更炫的对话效果而是把工具调用做成有边界、有验收、有审计的系统能力。2. 本专栏在解决什么问题2.1 问题定义给定一个业务目标例如把符合条件的工单升级为紧急并通知值班一组可调用工具查询、写入、通知、检索代码等一个会规划步骤并调用工具的 Agent 运行时要求系统在约束内完成目标并且可验证有明确的完成定义与验收方式可约束工具权限与副作用范围事先声明可观测关键调用与状态变更留痕可控成本有超时、次数与费用上限2.2 非目标本专栏不展开模型预训练、微调配方的完整教程某一家厂商控制台的逐屏点击说明把 Agent 神化成「全自动替代全部岗位」的叙事模型能力当然重要但在工具系统里它往往只是规划与语言层真正决定能不能上线的常常是任务定义、权限边界与验收门禁。3. 专栏内容划分与方向后续内容按工程顺序展开先把任务与权限说清楚再谈多 Agent 与成本否则编排只会把混乱放大。方向主要讨论什么总览分清演示与可上线系统固定最小闭环任务与验收模糊目标如何拆成任务卡片与完成定义工具面工具注册、读写分离、作用域、危险操作编排单 Agent 闭环以及多 Agent 委托边界运行时上下文预算、限流、超时、幂等观测、成本与上线审计、评测、配额、灰度、回滚与人机协同常见切入方式项目现状更合适的阅读重点只会演示对话还没有任务卡片先读任务与验收再读工具面已有工具调用但权限混乱先读工具面再回头补任务卡片单 Agent 已稳定准备拆多 Agent验收做扎实后再读编排马上要接业务流量对照观测、成本与上线相关章节做检查不必按专栏顺序通读但若跳过任务与验收直接做多 Agent后面排障成本通常更高。4. 最小上线闭环把一版 Agent 系统视为「可以进入业务」至少要闭合下面五环环节最少产出物缺了会怎样目标一句话业务结果 非目标Agent 优化错误目标权限工具清单与读写边界误改生产或越权读取执行可追踪的调用轨迹出问题无法复盘验收命令、断言或对照表只剩「感觉对了」无法复现成本步数 / 时间 / 费用上限循环调用拖垮预算这五环是本专栏的验收骨架。后文每一块内容都会回到其中至少一环而不是另起一套口号。实践里可以用一句话自检如果无法用命令或断言证明「这次做完了」就还停留在演示层。任务卡片不是文牍而是把这句自检提前写成字段。五环不必一次做完美但上线前至少要能指出目标写在哪里、谁有写权限、失败如何发现、怎样判定完成、预算上限是多少。缺任何一项演示里的偶然成功都很难复现。5. 工具面先分清三层边界工具不只是「函数能调用」。工程上至少要分开三层发现层有哪些工具、参数是什么、返回什么Agent 规划依赖这一层的准确性。权限层当前角色是否允许调用只读工具与写操作是否分开挂载。副作用层调用会改哪些外部状态失败时是否可补偿、是否要求幂等键。很多演示把三层揉在一个 tools 数组里短期省事长期会在排障时付出代价分不清是提示词问题、权限问题还是工具本身的副作用设计问题。6. 贯穿示例工单助手 Agent后续篇章默认使用同一业务故事降低上下文切换成本。场景客服或值班同学提出——把工单 T-1024 升为紧急写明原因并通知值班频道。允许的工具示意工具类型说明get_ticket只读查询工单当前状态update_ticket_priority写入修改优先级add_ticket_comment写入追加备注notify_oncall写入外部副作用通知值班完成定义示例工单优先级为urgent备注中包含约定关键词如升级原因值班通知已发送或明确记录「通知失败并已降级」全程未调用未授权工具例如直接删单、改账单演示版只关心模型有没有说出正确步骤系统版还要关心步骤是否在权限内、验收是否可机器执行。6.1 同一请求下的两种写法维度演示写法系统写法输入一段自然语言自然语言 任务卡片或由拆分器生成卡片工具临时塞进提示词注册表声明运行时按角色挂载成功标准人看对话觉得对acceptance_report可返回passed失败处理再问一句模型重试策略、降级通知、人工接管事后聊天记录审计字段工具、参数摘要、结果码、耗时本专栏后文会反复使用这张对照表每当引入新机制多 Agent、限流、配额都先看它落在上表哪一列。7. 可运行示意用字典描述一版最小任务卡片下面代码不绑定某一家 Agent 框架只表达本专栏反复使用的数据结构。字段可以映射到具体编排器。from__future__importannotationsfromtypingimportAnydefbuild_ticket_upgrade_card(ticket_id:str,reason:str)-dict[str,Any]:构造工单升级任务卡片示意。return{goal:f将工单{ticket_id}升级为紧急并通知值班,non_goals:[删除工单,修改计费字段,读取无关客户隐私备注],allowed_tools:[get_ticket,update_ticket_priority,add_ticket_comment,notify_oncall,],write_tools:[update_ticket_priority,add_ticket_comment,notify_oncall,],acceptance:{priority_equals:urgent,comment_must_contain:[升级原因,reason],notify_required:True,},budgets:{max_steps:8,max_seconds:60,max_tool_calls:12,},}defacceptance_report(card:dict[str,Any],final_state:dict[str,Any])-dict[str,Any]:根据最终状态做最小验收示意不连真实系统。acccard[acceptance]checks{priority_ok:final_state.get(priority)acc[priority_equals],comment_ok:all(keyin(final_state.get(comment)or)forkeyinacc[comment_must_contain]),notify_ok:(notacc[notify_required])orbool(final_state.get(notified)),tools_ok:set(final_state.get(used_tools,[])).issubset(set(card[allowed_tools])),}checks[passed]all(checks.values())returnchecksif__name____main__:cardbuild_ticket_upgrade_card(T-1024,产线停机)# 假设某次运行后的终态成功路径final_state{priority:urgent,comment:升级原因产线停机,notified:True,used_tools:[get_ticket,update_ticket_priority,add_ticket_comment,notify_oncall,],}print(acceptance_report(card,final_state))再给一段越权路径对照说明验收为什么必须检查工具集合if__name____main__:cardbuild_ticket_upgrade_card(T-1024,产线停机)bad_state{priority:urgent,comment:升级原因产线停机,notified:True,used_tools:[get_ticket,update_ticket_priority,delete_ticket,# 未授权],}reportacceptance_report(card,bad_state)assertreport[passed]isFalseassertreport[tools_ok]isFalseprint(越权路径已被验收拦住:,report)这两段代码的重点不是把工单系统写完而是固定专栏口径先有任务卡片再谈 Agent 自由发挥验收必须可机器判断未授权工具即使结果碰巧对了也不能算通过8. 四个常见误区误区典型表现更稳妥的做法把对话当系统只保存聊天记录没有任务卡片先写目标拆解与完成定义工具权限过大读写、高危操作挂在同一角色用注册表与权限策略拆开只看成功率抽测几次「好像行」建立评测集与成本配额无人值守幻想无审计、无人工接管点准备灰度、回滚与人机协同项目若同时踩中前两条建议先不要上多 Agent把单 Agent 的权限与验收做稳收益通常更大。9. 适用边界本专栏适合已经能调用模型 API 或本地推理准备把工具链路产品化的工程师需要给 Agent 项目补权限、验收与审计的技术负责人本专栏不适合作为大模型数学原理第一课某一具体 IDE 插件的操作手册替代品「无需工程、只靠提示词即可上生产」的证明材料若主要短板是模型写不出可用代码或检索质量差应先补齐编码能力或检索评测工具系统工程解决的是调用与约束不能替代那两块基础。10. 术语速查术语含义Agent能按目标规划步骤并调用工具的运行时角色工具Tool可被调用的外部能力如查询、写入、通知任务卡片目标、非目标、允许工具、验收与预算的结构化描述完成定义怎样算做完最好可机器判定权限边界谁能调用哪些工具、读写是否分离副作用调用对外部状态的真实改变审计保留关键调用与决策轨迹便于复盘降级主路径失败时的保守替代路径11. 小结与下一篇回到文首的判断如果只有提示词和临时工具列表还没有任务卡片、权限边界与验收命令那么当前更接近演示而不是可上线系统。本篇固定了三件事专栏主线是任务 → 工具面 → 编排 → 运行时 → 观测与上线最小上线闭环是目标、权限、执行、验收、成本贯穿示例是工单助手 Agent下一篇进入「任务与验收」把模糊业务一句话拆成可执行的任务卡片字段并给出第一版拆分脚本。系列导航本篇为专栏第 1 篇下一篇【Agent工程】2—— 模糊目标到任务卡片撰写中