01Agent 到底是什么何时该用何时不该用Agent 工程实战系列 · 序章 ·一、问题场景老板说“给客服做个 AI 助手”你是 SupportPilot客服工单助手项目的开发。一周之内业务方丢来三个需求“用户问运费和退货政策自动回答。”“用户申请退款核对订单校验是否在 7 天内金额小于 200 元自动退其余转人工。”“用户说‘我的包裹好像丢了’助手要自己查订单、查物流、判断是否异常再决定补发、退款还是转人工。”三个需求都被称为“AI 助手”但它们是同一种东西吗都应该做成 Agent 吗答案是否定的。很多团队的第一个坑就是把这三件事混为一谈要么给简单问题上了复杂架构要么让一个“聊天机器人”去干需要自主决策的活。本篇给你一把尺子用来判断一个需求落在哪一档并带你用 50 行代码亲手跑通最小的 Agent。二、核心概念2.1 一个判断标准谁决定下一步区分 Chatbot、Workflow、Agent不看它“多聪明”也不看它“调用了几个工具”只问一个问题下一步做什么是开发者在代码里写死的还是模型在运行时自己决定的层级谁决定下一步典型形态SupportPilot 中的例子0 单次调用没有“下一步”提示词 → 回答翻译用户留言、判断情绪1 Workflow工作流代码路径由开发者预先写死提示链、路由、并行需求 2退款流程2 Agent模型运行时自己选工具、定步数、决定何时停模型 工具 循环需求 3包裹丢失3 多 Agent多个模型相互委派编排者-执行者第 10、17 篇需求 1 属于第 0 到第 1 档检索一次、生成一次路径是固定的。有检索不等于是 Agent。这条光谱不是“越往下越高级”而是“把多少决定权交给模型”。决定权越多灵活性越强可预测性越弱。打个比方Workflow 像柜员照着 SOP 办业务每一步都有规定Agent 像一个拿到目标、权限和工具的实习生怎么做他自己想办法你得操心的是他会不会乱来。2.2 Agent 模型 工具 循环目标 → [模型决策] → 调用工具 → 观察结果 → 回到[模型决策] → …… → 模型认为完成 / 触发上限 → 结束模型负责判断“现在该做什么”。工具模型的手脚用来读写外部世界查订单、查知识库、发邮件。循环让“观察到的结果”能影响“下一步决策”。没有循环工具调用只是一次性的 function calling。终止条件最容易被忽略的第四个要素。没有它Agent 可能永远不停或者在不该停的时候停。2.3 四个常见误解误解实际情况有工具调用就是 Agent工具调用只是一次动作。路径写死在代码里就是 Workflow多步骤就是 Agent多步但路径固定是提示链。Agent 的标志是路径由模型动态决定用了 RAG 就是 Agent检索一次再回答是流水线。让模型自己决定查什么、查几次、查不到换什么才靠近 Agent第 09 篇多 Agent 比单 Agent 高级往往更贵、更难调试多数场景单 Agent 加好工具就够了第 10 篇三、设计取舍何时用何时不用3.1 Agent 的账单把决策权交给模型是有代价的——它得反复思考、反复调用每一步都在烧 token是要付费的。把同一件事分别做成 Workflow 和 Agent差别如下维度WorkflowAgent延迟固定可预估步数不定通常是单次调用的数倍成本可预算随步数增长有长尾偶发走很多步可预测性路径固定同一输入可能走不同路径可测试对每个节点单独测试需要评估整条轨迹第 18 篇可调试看哪个节点出错需要完整 Trace 才能还原第 19 篇安全面权限随节点固定模型可能触达所有被授权的工具第 22–24 篇灵活性只覆盖预设情形能处理没见过的组合因此有一条贯穿全系列的原则默认从最简单的方案开始只有实测发现简单方案不够用才增加AI自己决定多少的程度。这也是业界在总结 Agent 工程实践时反复强调的思路。3.2 产物 ①Agent 适用性决策表拿到一个需求依次回答下面 7 个问题#问题回答后的结论1步骤能否在开发时穷举能 → 用 Workflow 或单次调用2下一步是否取决于上一步的结果且分支多到写不完是 → 倾向 Agent3需要的工具和数据是否已有可调用的接口没有 → 先建接口别急着做 Agent4成败能否被自动判定有明确验收标准不能 → 先补验收标准否则无法评估和迭代5出错后能否撤销或有人兜底不能 → 限制AI自己决定多少的程度只读 人工确认写操作6能否接受数倍延迟和不固定的成本不能 → 退回 Workflow7任务价值是否覆盖成本不能 → 不做把它压缩成一张决策流程Q1 步骤能穷举 ── 能 ──→ 用 Workflow或单次调用 │ 不能 Q2 成败能自动判定 ── 不能 ──→ 先补验收标准暂不做 Agent │ 能 Q3 工具和数据接口已就绪 ── 否 ──→ 先建工具再回来 │ 是 Q4 出错能撤销或有人兜底 ── 否 ──→ 只读 Agent写操作必须人工确认 │ 能 Q5 延迟、成本可接受价值覆盖成本 ── 否 ──→ 退回 Workflow │ 是 适合 Agent从“单 Agent 少量工具”开始3.3 用决策表判定 SupportPilot 的三个需求需求判定理由1 政策问答单次调用 RAG一次检索、一次生成路径固定不需要循环2 退款流程Workflow规则明确、步骤可穷举合规要求结果确定。模型只负责节点内的“理解用户意图、抽取订单号”3 包裹丢失Agent只读起步查什么、查几次取决于中间结果路径写不完。但补发、退款属于写操作先加人工确认一个产品里三种形态并存是正常且健康的。实践中常见的组合是Workflow 做骨架Agent 做关节即在固定流程的某个节点里嵌一个小 Agent 处理开放性问题。四、动手实现50 行最小 Agent准备环境示例使用 DeepSeek Python SDK换成其他厂商的函数调用接口结构完全一样pipinstallopenaiexportDEEPSEEK_API_KEY你的密钥# Windows PowerShell: setx DEEPSEEK_API_KEY 你的密钥新建agent_min.pyimportjson,osfromopenaiimportOpenAI clientOpenAI(api_keyos.environ[DEEPSEEK_API_KEY],# 读取环境变量base_urlhttps://api.deepseek.com,# DeepSeek 的 OpenAI 兼容端点)MODELdeepseek-v4-pro# DeepSeek 4 Pro也可换成 deepseek-v4-flash 省钱MAX_STEPS8# 预算防止死循环ORDERS{A1001:{status:已发货,eta:2026-10-14},A1002:{status:待付款,eta:None}}defget_order(order_id:str)-dict:returnORDERS.get(order_id)or{error:f订单{order_id}不存在}TOOLS[{type:function,function:{name:get_order,description:按订单号查询订单状态和预计送达时间。只读不会修改订单。,parameters:{type:object,properties:{order_id:{type:string,description:订单号形如 A1001}},required:[order_id],},},}]HANDLERS{get_order:get_order}SYSTEM你是客服助手。需要订单信息时必须调用工具不要凭空猜测信息不足时直接向用户提问。defrun(user_msg:str)-str:messages[{role:system,content:SYSTEM},{role:user,content:user_msg}]forstepinrange(MAX_STEPS):# 循环决策 → 行动 → 观察respclient.chat.completions.create(modelMODEL,max_tokens1024,toolsTOOLS,messagesmessages)msgresp.choices[0].message messages.append(msg)# 决策进入上下文ifnotmsg.tool_calls:# 模型没有再要工具可以收尾returnmsg.contentorforcallinmsg.tool_calls:# 行动 观察argsjson.loads(call.function.argumentsor{})print(f[step{step}] 调用{call.function.name}({args}))try:outHANDLERS[call.function.name](**args)exceptExceptionase:# 错误也回传让模型自己调整out{error:str(e)}messages.append({role:tool,tool_call_id:call.id,content:json.dumps(out,ensure_asciiFalse)})return达到步数上限已停止转人工处理if__name____main__:print(run(帮我查下订单 A1001 什么时候到))读懂这 50 行代码位置对应概念为什么重要for step in range(MAX_STEPS)循环 终止条件没有上限工具持续失败时会无限循环、成本失控not msg.tool_calls不是 tool_use 就收尾模型决定何时停这是“模型决定下一步”的体现Workflow 里这一步由代码决定try/except里回传is_error错误也是观察模型看到错误后可以改参数重试或向用户澄清而不是让程序崩溃messages.append(...)两处上下文即状态工具结果必须放回消息历史模型下一轮才“看得见”第 05 篇详讲跑几个小实验把上述代码中的def run(user_msg: str) - str: 函数 改成defrun(messages:list,user_msg:str)-str:处理一轮提问messages 由外部传入并持续累积实现多轮记忆。messages.append({role:user,content:user_msg})forstepinrange(MAX_STEPS):# 循环决策 → 行动 → 观察respclient.chat.completions.create(modelMODEL,max_tokens1024,toolsTOOLS,messagesmessages)msgresp.choices[0].message messages.append(msg)# 决策进入上下文ifnotmsg.tool_calls:# 模型没有再要工具可以收尾returnmsg.contentorforcallinmsg.tool_calls:# 行动 观察argsjson.loads(call.function.argumentsor{})print(f[step{step}] 调用{call.function.name}({args}))try:outHANDLERS[call.function.name](**args)exceptExceptionase:# 错误也回传让模型自己调整out{error:str(e)}messages.append({role:tool,tool_call_id:call.id,content:json.dumps(out,ensure_asciiFalse)})return达到步数上限已停止转人工处理if__name____main__:messages[{role:system,content:SYSTEM}]# 整轮会话共享print(客服 Agent 已启动输入 exit 或 quit 退出。)whileTrue:try:user_msginput(\n你: ).strip()except(EOFError,KeyboardInterrupt):# CtrlC / CtrlD 优雅退出print(\n已退出。)breakifnotuser_msg:continueifuser_msg.lower()in(exit,quit):print(已退出。)breakprint(Agent:,run(messages,user_msg))实际输出因模型而异重点是观察行为模式正常路径问“订单 A1001 什么时候到”观察一次工具调用后给出回答。多次调用问“A1001 和 A1002 哪个先到”观察模型是否一次发起两个调用代码已兼容并行的多个调用。工具报错问“订单 A9999 到哪了”观察工具返回错误后模型如何向用户解释。触发预算把MAX_STEPS改成 1再问第 1 题观察兜底话术。去掉约束删掉SYSTEM里“不要凭空猜测”一句不提供订单号直接问“我的货到哪了”观察它会追问还是编造。五、踩坑清单典型失败模式失败模式现象根因预防对应篇目用 Agent 做固定流程退款审批偶尔跳过“7 天内”校验把必须执行的规则交给模型自觉规则放进代码模型只做理解03、04无限循环、步数爆炸工具持续报错模型反复用同样参数重试没有步数、成本、时间上限错误信息没有指引三重预算 错误信息写明下一步建议08、13工具选错、参数瞎填调了不该调的工具或编出订单号工具描述含糊、功能重叠工具是“给模型看的界面”06凭空编造没查到数据却给出确定的答复没约束“无证据则追问或转人工”证据绑定与核验25无法评估就上线“感觉还行”改一次提示词就出新问题没有成功标准和测试集先写验收标准03、18万物皆 Agent为一次文本分类搭了循环和工具链把“用上新技术”当成了目标先用决策表自查本篇一个反例感受“用 Agent 做固定流程”的代价某团队把退款流程做成 Agent让模型自己决定“先查订单还是直接退款”。演示时一切正常上线后偶尔出现模型跳过了时效校验就直接退款的情况。原因不难理解校验是否执行取决于模型每次的判断而判断有概率波动。把校验写进 Workflow 的固定节点之后问题消失调用次数也更少、更便宜。六、自测本篇练习练习挑一个你手头的真实需求按下面的模板写 3 行判定。需求…… 自治层级判定0 / 1 / 2 / 3…… 关键理由引用决策表第几问…… 最大风险……自测 5 题用户上传发票图片系统用模型提取金额后写入财务系统。这是 Agent 吗某团队让模型“自己决定是否先做风控校验再放款”。这个设计有什么问题一个流程固定 5 步每步调用一次模型上一步的输出作为下一步的输入。它属于哪一档想做“自动处理邮件并直接删除垃圾邮件”的 Agent但没有任何办法判定是否误删。该怎么办把agent_min.py里的MAX_STEPS删掉什么情况下会真的出事参考答案不是。路径固定属于单次调用或 Workflow。需要关注的是写入财务系统前的校验与确认。必须执行的合规步骤不能靠模型自觉应写进代码的固定节点。提示链属于 Workflow。既无法验证又不可撤销应先降低AI自己决定多少的程度只读或移入隔离区由人工确认同时建立评估标准。工具持续失败或模型始终无法得出结论时会无限循环延迟与成本失控。七、系列地图一个 Agent 要过哪三关一个 Agent 从想法到安全上线要依次过三关。全系列围绕同一个项目 SupportPilot 展开每篇给它加一项能力阶段要回答的问题篇目SupportPilot 里长出什么设计做什么怎么搭边界在哪02–11一页纸设计文档、架构图、工具契约、记忆方案开发怎么做稳怎么证明它好用怎么上线12–21可运行服务、评估集、监控、部署安全被攻击或自己出错时怎么办22–27威胁模型、防护层、审计、红队用例、上线检查表毕业能否独立走完全流程28完整仓库与全流程检查表本篇 3.1 节的“安全面”一行是后面安全篇的伏笔Agent 的风险很大程度来自模型可以触达所有被授权的工具。八、下一篇预告02Agent 架构全景图今天这 50 行代码在完整的 Agent 里只占一角。下一篇我们把八大模块画成一张图看看缺了什么模块本篇 50 行里有吗模型有工具有仅 1 个只读编排循环有最简形态记忆雏形只有当次消息列表规划无护栏雏形只有步数上限评估无可观测雏形只有 print其余五个模块要么缺失要么只有雏形正是这个系列接下来要一块块补齐的。