【Agent工程】（2）—— 模糊目标到任务卡片

【Agent工程】2—— 模糊目标到任务卡片文章目录【Agent工程】2—— 模糊目标到任务卡片1. 一句模糊目标会把系统带偏2. 任务卡片要写清的六块字段2.1 目标与非目标必须成对出现2.2 验收项优先可机器判定3. 从模糊句到卡片的拆分流程4. 贯穿示例工单升级请求4.1 什么时候拆成多张卡片5. 可运行示意拆分草稿与校验门禁5.1 启发式拆分5.2 校验门禁5.3 约束字段怎么写才有用6. 四个常见误区6.1 卡片与提示词的分工7. 适用边界8. 术语速查9. 小结与下一篇摘要Agent 最常见的翻车不是模型不会调用工具而是业务目标仍停在一句模糊话上。本篇把模糊请求拆成任务卡片的六块字段说明校验门禁怎么拦半成品卡片并给出可运行的拆分与校验脚本。贯穿示例继续用工单助手。适合读完 【Agent工程】1—— 演示成功不等于系统可用、准备把「帮我处理一下」变成可验收输入的工程师。读完可以独立完成从自然语言写出一版可校验的任务卡片。1. 一句模糊目标会把系统带偏业务侧常见说法是帮我处理一下紧急工单把那个单弄一下通知值班就行看着办尽量快点人听得懂意图Agent 却必须在工具空间里自行补全假设。常见后果是改了优先级又顺手改了不该动的字段通知发了多条或发到错误频道对话里声称「做完了」外部状态对不上复盘时说不清调用了哪些工具、依据是什么本专栏把这类问题统称为任务定义层的工作在模型规划步骤之前先把业务意图压成字段。少了这一层后面的权限、编排、限流都会建立在不稳的输入上。第 1 篇已经说明演示成功不等于系统可用。本篇只攻其中一环——在调用工具之前先把目标写成可校验的任务卡片。前文见 【Agent工程】1—— 演示成功不等于系统可用。2. 任务卡片要写清的六块字段任务卡片不是会议纪要而是 Agent 运行前的结构化输入。建议至少包含下面六块字段作用写不好会怎样目标一句话业务结果Agent 优化错误目标非目标明确不做的事范围悄悄膨胀允许工具可调用清单越权调用难发现验收可机器判定的完成条件只能靠「感觉对了」预算步数、时间、调用次数上限循环调用拖垮成本约束角色、环境、禁止项跑到错误环境或错误角色工程上可以把六块看成两层意图层目标、非目标、约束执行层允许工具、验收、预算缺意图层执行再漂亮也难对齐业务缺执行层意图再清楚也无法机械验收。2.1 目标与非目标必须成对出现只写目标、不写非目标是最常见的半成品卡片。工单升级场景里目标可以是「将 T-1024 升级为紧急并通知值班」非目标至少应写明不删除工单不修改计费相关字段不读取与本次升级无关的客户隐私备注非目标写得越具体后续权限策略越好落地。工具面细节放在后续篇目本篇先保证卡片里有位置写下这些边界。2.2 验收项优先可机器判定验收写成「处理得比较合理」没有工程价值。更稳妥的写法是外部状态满足某条件如priority urgent文本字段包含约定关键词通知接口返回成功或明确记录降级结果实际调用工具集合是允许清单的子集能写成断言或命令的就不要只写成形容词。3. 从模糊句到卡片的拆分流程推荐固定四步且把校验放在 Agent 启动之前收集原始请求保留业务原话便于回溯。结构化填表按六块字段填写不确定的项标成待确认而不是假装确定。机器校验缺目标、缺验收、无允许工具直接拒绝进入执行。作为执行输入通过校验的卡片再交给 Agent 运行时。拆分可以由人手工完成也可以用启发式脚本生成草稿后再人工改。关键点不在「谁来拆」而在未通过校验的卡片不得进入工具调用阶段。拆分过程中有两类信息不要丢掉原始请求全文进入raw_request用于审计与争议回溯。不确定项清单例如工单号未识别、通知渠道未定写入needs_review或单独的待确认列表。不确定项被清空之前校验门禁应继续拦截自动执行。宁可多一次人工确认也不要在缺关键字段时调用写工具。对已经接入表单或工单系统的团队拆分不一定要从聊天原文开始。更稳的做法是上游系统直接产出结构化字段聊天只作为补充说明。本篇仍从模糊句讲起是因为多数试点项目的第一批请求都来自自然语言。4. 贯穿示例工单升级请求继续使用工单助手场景。模糊请求帮我把那个单弄成紧急顺便通知一下。澄清后的业务事实可由值班同学或前置表单补齐工单号T-1024升级原因产线停机需要通知值班频道对应任务卡片摘要字段内容目标将工单 T-1024 升级为紧急并通知值班非目标不删除工单不修改计费字段不读取无关隐私备注允许工具get_ticket、update_ticket_priority、add_ticket_comment、notify_oncall验收优先级为 urgent备注含「升级原因」与具体原因已通知或记录降级未使用未授权工具预算最多 8 步、60 秒、12 次工具调用约束仅生产只读查询 工单写接口禁止调用删除类工具同一业务意图左侧不可验收右侧可以进入运行时。4.1 什么时候拆成多张卡片一张卡片只服务一个主目标。下面情况建议拆分情况建议既要升级工单又要改计费规则拆成两张卡避免副作用缠在一起通知渠道尚未确定先出「升级」卡通知作为后续卡或人工步骤需要先查清工单是否存在先出只读查询卡再出写入卡多个工单批量处理每单或每批一张卡失败时便于重试拆多卡不是为了增加流程仪式而是为了让失败可定位、权限可收窄、验收可独立通过。5. 可运行示意拆分草稿与校验门禁下面两段脚本不绑定具体 Agent 框架。第一段把模糊句拆成草稿卡片第二段检查必填字段。草稿不等于终稿上线前仍建议人工核对非目标与验收。5.1 启发式拆分from__future__importannotationsimportjsonimportrefromtypingimportAnydefsplit_ticket_goal(raw:str)-dict[str,Any]:把工单相关模糊句拆成任务卡片草稿启发式需人工复核。ticket_idsre.findall(rT-\d,raw,flagsre.I)ticket_idticket_ids[0].upper()ifticket_idselseT-UNKNOWNurgentany(kinrawforkin(紧急,加急,urgent))notifyany(kinrawforkin(通知,值班,oncall))goalf处理工单{ticket_id}ifurgent:goalf将工单{ticket_id}升级为紧急ifnotify:goal并通知值班return{raw_request:raw,goal:goal,non_goals:[删除工单,修改计费字段,读取无关客户隐私备注],allowed_tools:[get_ticket,update_ticket_priority,add_ticket_comment,notify_oncall,],acceptance:{priority_equals:urgentifurgentelseNone,comment_must_contain:[升级原因]ifurgentelse[],notify_required:notify,},budgets:{max_steps:8,max_seconds:60,max_tool_calls:12},constraints:[禁止调用 delete_ticket,写操作仅限工单相关接口],needs_review:ticket_idT-UNKNOWNornoturgent,note:启发式拆分草稿执行前请人工补全工单号、原因与验收细节。,}if__name____main__:cardsplit_ticket_goal(帮我把 T-1024 弄成紧急顺便通知一下值班)print(json.dumps(card,ensure_asciiFalse,indent2))5.2 校验门禁from__future__importannotationsfromtypingimportAny REQUIRED(goal,non_goals,allowed_tools,acceptance,budgets)defvalidate_task_card(card:dict[str,Any])-dict[str,Any]:校验任务卡片是否具备最小可执行字段。errors:list[str][]forkeyinREQUIRED:ifkeynotincardorcard[key]in(None,,[],{}):errors.append(f缺少字段:{key})ifgoalincardandisinstance(card[goal],str)andlen(card[goal].strip())8:errors.append(目标过短难以作为业务结果描述)toolscard.get(allowed_tools)or[]ifisinstance(tools,list)andlen(tools)0:errors.append(允许工具列表为空)acccard.get(acceptance)or{}ifisinstance(acc,dict)andnotacc:errors.append(验收条件为空)ifcard.get(needs_review)isTrue:errors.append(标记为需要人工复核尚未确认)return{ok:noterrors,errors:errors}if__name____main__:frompprintimportpprint good{goal:将工单 T-1024 升级为紧急并通知值班,non_goals:[删除工单],allowed_tools:[get_ticket,update_ticket_priority,notify_oncall],acceptance:{priority_equals:urgent,notify_required:True},budgets:{max_steps:8},needs_review:False,}bad{goal:处理一下,needs_review:True}pprint(validate_task_card(good))pprint(validate_task_card(bad))校验逻辑的要点缺字段就拒绝而不是让 Agent「边跑边猜」needs_reviewTrue时同样拒绝自动执行通过校验只代表卡片形状合格不代表业务策略已经最优5.3 约束字段怎么写才有用约束不要写成空话。更有用的约束通常是可检查的环境仅 staging / 仅工单写接口禁止工具名delete_ticket调用次数与预算字段一致避免两处矛盾人工闸门涉及对外通知前必须二次确认具体实现放到后续工具面与人机协同篇目约束与允许工具清单重复时以更严的一方为准并在卡片里写清楚避免运行时各解释各的。6. 四个常见误区误区典型表现更稳妥的做法只写目标不写非目标范围在执行中膨胀目标与非目标成对填写验收写成「看起来对」无法复现、无法回归改成状态断言或命令工具清单事后再补越权调用难以发现执行前锁定允许工具一张卡片塞进多个目标失败后无法定位一卡一主目标复杂需求拆多卡项目若经常出现「Agent 做了很多但业务说没做完」优先检查是不是把多目标塞进了同一张卡片。6.1 卡片与提示词的分工任务卡片不替代提示词二者职责不同对象更适合放什么任务卡片目标、边界、工具清单、验收、预算等可校验字段系统提示词语气、输出格式、通用安全原则、角色说明用户原话作为raw_request保留便于审计与人工复核把验收条件只写在提示词里、不写进卡片运行时很难做统一门禁把长篇风格说明塞进卡片又会让校验脚本难以维护。比较稳的做法是卡片管「做对没有」提示词管「怎么说、怎么组织中间推理」。对工单助手而言优先级是否变为 urgent属于卡片验收回复值班同学时用什么措辞属于提示词或下游通知模板。7. 适用边界本篇方法适合工具调用型 Agent需要把自然语言请求变成结构化输入已有工单、运维、客服类系统接口缺的是任务定义层本篇不覆盖提示词文采与模型选型对比完整权限引擎与工具注册表实现后续工具面篇目展开多 Agent 委托与失败编排后续编排篇目展开拆分脚本是启发式草稿生成器不是需求管理系统。工单号缺失、原因不明、通知渠道未定时应停在人工复核而不是强行自动执行。和编程助手场景相比工具型 Agent 的卡片还多了「允许工具」与「副作用边界」。只把目标写清楚但工具清单留空仍然会在执行阶段失控。8. 术语速查术语含义模糊目标只有意图、缺少可验证边界的自然语言请求任务卡片目标、非目标、允许工具、验收、预算、约束的结构化描述非目标明确不做的事项用来限制范围膨胀完成定义怎样算做完本篇落在验收字段校验门禁执行前检查卡片必填项与复核标记预算步数、时间、工具调用次数等上限启发式拆分用规则从原话生成草稿卡片需人工确认9. 小结与下一篇回到文首的问题Agent 是否经常「做完了但业务不认」若输入仍是一句模糊话问题往往不在模型而在任务尚未结构化。本篇固定了三件事任务卡片至少包含目标、非目标、允许工具、验收、预算、约束校验门禁应放在工具调用之前工单升级示例表明同一意图可以写成可机器核对的输入下一篇继续「任务与验收」把验收字段进一步落成命令与断言并说明哪些项必须人工确认。系列导航上一篇【Agent工程】1—— 演示成功不等于系统可用下一篇【Agent工程】3—— 验收命令与完成定义