前置知识已完成第一课至第八课本课目标把模糊的计划步骤拆解为带类型、可验证的原子动作让执行安全可控核心概念原子性 / 确定性 / Schema 验证 / 类型化执行前言第八课Agent 会规划了。planagent.create_plan(写一篇关于 AI Agent 的技术博客)# → {steps: [研究 AI Agent 最新进展, 确定文章大纲, 撰写初稿, 审校修改]}但有一个问题——撰写初稿到底要做什么写多长1000 字还是 5000 字写给谁看技术人员还是小白输出格式是什么Markdown 还是纯文本写到什么程度算完成你不知道Agent 也不知道。第八课的执行只是打印已执行因为步骤太模糊了根本没有办法真正执行。就像你给下属说去做一下市场调研。他可能花 10 分钟搜一下百度也可能花 3 个月写一份 200 页的报告——因为你没有定义做什么、做到什么程度、输出是什么。本课要解决这个问题。给每个步骤加上动作名称 参数 验证规则让它变成一个可检查、可执行的最小单元。一、撰写初稿为什么不能直接执行1.1 模糊步骤的三个问题第八课的步骤是一个字符串撰写初稿这个字符串面临三个问题① 不可验证你怎么知道 Agent 撰写初稿做对了因为没有标准。输出 50 字算完成吗输出 5000 字也算完成吗② 不可执行execute_step(撰写初稿)这个函数要怎么实现你不知道该调什么工具、传什么参数。字符串步骤没法直接变成代码。③ 不可调试如果执行出了问题你不知道是哪一步错了、为什么错。因为步骤没有结构化的输入和输出只能靠猜。1.2 原子动作的解法把撰写初稿变成一个结构化的动作{action:generate_text,inputs:{topic:AI Agent 的技术博客,target_audience:有编程基础的技术人员,length:2000-3000字,format:markdown}}现在你可以操作模糊步骤原子动作验证撰写初稿对吗不知道action和inputs字段完整吗可以检查执行怎么做不知道调用generate_text(topic, ...)可以实现调试哪里错了不知道inputs.target_audience缺失导致输出不对这就是原子动作的价值把模糊变成具体把不可控变成可控。二、什么是原子动作2.1 原子性最小的执行单元原子动作是不可再分的最小操作。就像化学里的原子——你不能再把生成一段文字拆成更小的有意义的操作了。写一篇关于 AI 的博客 ← 模糊步骤不是一个原子动作 ↓ 拆解 生成关于 AI 的 2000 字 Markdown 文本 ← 原子动作有明确输入和输出原子动作要么完全成功要么完全失败。不存在做了一半的中间状态。2.2 确定性相同输入可预测的输出给定相同的原子动作执行结果应该是可预测的。{action:generate_text,inputs:{topic:Python 基础,length:500字}}不管执行几次输出都应该是大约 500 字、关于 Python 基础的文本。如果topic是空的或者length是 “一万亿字”执行前就应该被拦截。2.3 类型化执行Schema 即合约每个原子动作都有一份合约Schema规定了动作名称这个动作叫什么generate_text、search_web、send_email……必需输入必须提供哪些参数topic、length……验证规则参数必须满足什么条件length必须是正数……Schema合约 动作名称generate_text 必需输入topic字符串不能为空、length字符串如 1000字 可选输入format默认 markdown、tone默认 formal 验证流程 1. 检查 action 字段存在 → ✅ 2. 检查 inputs.topic 不为空 → ✅ 3. 检查 inputs.length 格式合理 → ✅ → 通过验证可以执行核心洞察小步骤 安全系统。动作越小破坏半径越小。三、原子动作 vs 模糊步骤第八课和第九课解决的是同一个问题的两个层次第八课目标 → 计划步骤列表 → 逐步执行 写博客 → [研究, 写大纲, 撰写初稿, 审校] → 每步标记已执行 第九课计划步骤 → 原子动作列表 → 验证后执行 撰写初稿 → {action: generate_text, inputs: {...}} → 检查 schema → 执行第八课模糊步骤第九课原子动作数据格式字符串列表结构化 JSONaction inputs能验证吗不能字符串没有结构能检查字段完整性能执行吗不能不知道做什么能action 名对应具体函数能调试吗不能没有输入输出能可以追踪每个 inputs 的值出错了怎么办只能重试整个步骤可以定位到具体参数第九课是对第八课的升级——同样的逐步执行模式但每一步从说一句话变成了调一个函数。四、代码实现4.1 原子动作生成器agent/planner.py在第八课的planner.py中新增create_atomic_action()函数defcreate_atomic_action(llm,step:str)-dict|None: 将计划步骤转换为原子动作。 用于第九课 Args: llm: 语言模型实例 step: 计划中的一个步骤 Returns: 原子动作字典失败返回 None fromshared.utilsimportextract_json_from_text promptf将以下计划步骤转换为一个具体的原子动作。只返回有效的 JSON。 规则 1. 只返回有效的 JSON 2. 不要任何解释不要 Markdown 3. 直接以 {{ 开头以 }} 结尾 4. action 应该是一个简单、具体的操作名称 5. inputs 应该包含执行该动作所需的所有参数 6. 参数值应该具体不要模糊 JSON 格式 {{action: 动作名称, inputs: {{参数名: 参数值}}}} 步骤{step}请返回 JSONforattemptinrange(3):responsellm.generate(prompt,temperature0.0)actionextract_json_from_text(response)ifactionandactioninaction:ifinputsnotinactionornotisinstance(action[inputs],dict):action[inputs]{}returnactionreturnNone逐段拆解① Prompt 设计核心指令“action 应该是简单、具体的操作名称inputs 应该包含所有参数”。对比第八课的 Prompt——第八课要求返回步骤列表第九课要求返回单个动作 参数。粒度从做什么细化到了怎么调用。② 验证逻辑ifactionandactioninaction:ifinputsnotinactionornotisinstance(action[inputs],dict):action[inputs]{}returnaction只检查action字段存在。inputs如果缺失或格式不对自动补一个空字典——容错处理。本课先做最基本的验证后续课程会加更严格的 schema 校验。③ 还是老三样extract_json_from_text()——第三课以来的老朋友重试 3 次 ——老规矩temperature0.0——原子动作需要确定性4.2 Agent 中的原子动作方法在agent/agent.py中新增defcreate_atomic_action(self,step:str)-dict|None: 将计划步骤转换为原子动作第九课核心方法。 Args: step: 计划中的一个步骤 Returns: 带 action 和 inputs 的原子动作字典 fromagent.plannerimportcreate_atomic_actionasaction_fn atomicaction_fn(self,step)ifatomic:action_nameatomic.get(action,?)inputsatomic.get(inputs,{})print(f⚛️ 原子动作生成完成{action_name}({inputs}))returnatomic注意设计细节① 同样委托给planner.py和第八课的create_plan()一样原子动作的生成逻辑放在planner.pyAgent 类只做调度。职责分离的原则贯穿始终。② 生成时打印结果print(f⚛️ 原子动作生成完成{action_name}({inputs}))方便调试。你可以清楚看到每个步骤被转换成了什么动作、带了什么参数。③ 和create_plan()的关系# 第八课生成计划planagent.create_plan(写一篇博客)# → {steps: [研究, 写大纲, 撰写初稿, 审校]}# 第九课把每个步骤变成原子动作forstepinplan[steps]:atomicagent.create_atomic_action(step)# step 撰写初稿 → {action: generate_text, inputs: {topic: ..., length: ...}}第八课生成步骤列表第九课把每个步骤转成可执行的动作。两步串联就形成了目标 → 计划 → 原子动作 → 执行的完整链路。五、运行示例5.1 基础场景单个步骤转换fromagent.agentimportAgent agentAgent(modelqwen2.5:7b)# 将一个模糊步骤转为原子动作step写一篇关于 AI Agent 的入门介绍atomicagent.create_atomic_action(step)print(f\n原始步骤{step})print(f原子动作{atomic})预期输出类似⚛️ 原子动作生成完成generate_text({topic: AI Agent 入门介绍, target_audience: 初学者, length: 1500-2000字, format: markdown}) 原始步骤写一篇关于 AI Agent 的入门介绍 原子动作{action: generate_text, inputs: {topic: AI Agent 入门介绍, target_audience: 初学者, length: 1500-2000字, format: markdown}}注意看写一篇关于 AI Agent 的入门介绍变成了一个带 4 个参数的具体动作。5.2 从计划到原子动作# 先生成计划第八课能力planagent.create_plan(创建一个 Python 教程)# 再把每个步骤转为原子动作第九课能力ifplanandstepsinplan:print(\n 计划 → 原子动作映射\n)fori,stepinenumerate(plan[steps],1):atomicagent.create_atomic_action(step)ifatomic:print(f 步骤{i}{step})print(f 动作{i}{atomic[action]}({atomic[inputs]}))print()预期输出类似 计划 → 原子动作映射 ⚛️ 原子动作生成完成search_web({query: Python 教程 最佳实践 2026, num_results: 5}) 步骤1调研 Python 教程的最佳实践和热门主题 动作1search_web({query: Python 教程 最佳实践 2026, num_results: 5}) ⚛️ 原子动作生成完成generate_text({topic: Python 基础教程大纲, sections: 5-8个章节, format: markdown}) 步骤2制定教程大纲和章节结构 动作2generate_text({topic: Python 基础教程大纲, sections: 5-8个章节, format: markdown}) ...略这就是“目标 → 计划 → 原子动作”的完整转换链路。5.3 对比不同步骤的原子动作同一个目标不同步骤会产生不同类型的原子动作steps[研究竞品的定价策略,写一封客户跟进邮件,整理上周的销售数据,制作季度汇报 PPT]forstepinsteps:atomicagent.create_atomic_action(step)可能的输出研究竞品的定价策略 → {action: search_web, inputs: {query: 竞品定价策略分析, sources: 行业报告、官网}} 写一封客户跟进邮件 → {action: generate_text, inputs: {type: 商务邮件, recipient: 客户, tone: 专业友好}} 整理上周的销售数据 → {action: process_data, inputs: {data_source: 销售系统, time_range: 上周, output: 汇总报表}} 制作季度汇报 PPT → {action: create_presentation, inputs: {topic: 季度汇报, slides: 10-15页, format: pptx}}不同的模糊步骤被转换成了不同类型的原子动作每个都有针对性的参数。这正是类型化执行的价值。5.4 交互模式cdlesson09 python complete_example.py会进入交互模式你可以输入任意步骤观察它被转换成什么样的原子动作。六、与第八课的本质区别两课都处理计划步骤但粒度完全不同第八课规划——步骤级别目标写一篇博客 ↓ 计划[研究主题, 写大纲, 撰写初稿, 审校] ↓ 执行每步打印已执行步骤是字符串没有结构。执行是占位符。第九课原子动作——操作级别步骤撰写初稿 ↓ 原子动作{action: generate_text, inputs: {topic: ..., length: ...}} ↓ 验证action 存在inputs 合理 → 通过 → 可以执行动作是结构化数据有 schema。执行前可以验证。第八课模糊步骤第九课原子动作输入字符串“撰写初稿”结构化{action: generate_text, inputs: {...}}能验证吗❌ 字符串没有结构✅ 检查 action inputs能执行吗❌ 不知道做什么✅ action 名对应具体函数出了错只能重试定位到具体参数类比给下属说做个方案给下属说用 PPT 做 10 页方案包含竞品分析和预算第八课定义了做什么What第九课定义了怎么做How。七、关键洞察7.1 小步骤 安全系统这是本课最重要的洞察动作越小系统越安全。破坏半径越可控。一个写文章的大动作可能产生 10000 字的垃圾输出。但一个生成 200 字的产品描述的原子动作最多浪费 200 字。原子动作的四个安全特性特性说明易验证执行前检查参数不合格就不执行易测试每个动作可以独立测试易调试失败被隔离到具体动作和参数破坏半径小小动作即使出错影响也有限7.2 模糊是万恶之源写文章是模糊的。模糊带来三个问题LLM 不知道输出什么→ 结果不可预测代码不知道调什么→ 无法实现人不知道对不对→ 无法审查generate_text(topic‘AI agents’, length‘1000 words’)是具体的。具体意味着LLM 知道输出什么 → 结果可预测代码知道调什么 →generate_text(topic, length)可以实现人知道对不对 → 1000 字对不对一眼就能看出来核心原则尽可能把每一步的具体程度推到极致。7.3 验证在执行之前原子动作的设计哲学是先验证后执行。传统方式直接执行 → 出错了再处理 原子动作验证 schema → 通过 → 执行 / 不通过 → 拦截就像你写代码先编译再运行而不是直接跑然后看报错。验证越早修复成本越低。7.4 原子动作是构建块单个原子动作很简单。但组合起来可以构建复杂的工作流generate_outline(topic) ← 原子动作 1 ↓ search_web(query) ← 原子动作 2依赖动作 1 的输出 ↓ generate_text(topic, outline) ← 原子动作 3依赖动作 1、2 的输出 ↓ review_and_edit(text) ← 原子动作 4依赖动作 3 的输出每个原子动作都很简单但串联起来就是一篇完整的文章生成流程。第十课会讲如何处理这些依赖关系。八、常见问题Q生成的原子动作还是很模糊怎么办A优化 Prompt。加更具体的约束比如action 必须是以下之一generate_text、search_web、send_email、create_file。把动作名称限制在预定义集合里模糊性会大幅降低。这就是约束越强输出越可控。Qinputs 里的参数不合理怎么办比如 length 是 “一亿字”A本课做了基本的结构验证action 和 inputs 字段存在但没有做值的语义验证。后续可以通过加 schema 规则来实现比如length必须是正数且不超过 10000。本课先把结构化输出这个模式跑通value validation 是下一步。Q有些步骤很难拆成原子动作怎么办A有些步骤本身就是协调性的比如和团队讨论确定方向。这类步骤可能不适合原子化。一个策略是先把能原子化的步骤原子化不能原子化的保留为人工步骤让 Agent 跳过或提醒人类介入。Q原子动作和第五课的工具调用有什么区别A很像但角度不同。第五课是 Agent运行时动态选择工具调用第九课是规划阶段预先确定每步用什么动作。第五课是边想边做第九课是先想好再验证再做。两种模式可以结合——规划时预定义动作运行时根据情况调整。Q每次都要调 LLM 来生成原子动作会不会很慢A会。每个步骤都要一次 LLM 调用。但在实际场景中这比执行错了再回滚的成本低得多。而且很多步骤的原子动作是可以缓存的——相似步骤复用之前的转换结果。九、九课演进线把前九课放在一起看Agent 的能力越来越像人第一课能对话了LLM Ollama 第二课有角色了 能多轮对话System Prompt History 第三课能输出 JSON 了结构化输出 验证 重试 第四课能做选择了意图理解 → 动作路由 第五课能调用工具了工具选择 参数提取 安全执行 第六课能循环了Agent Loop 状态追踪 终止条件 第七课能记住了跨对话记忆存储 检索 显式管理 第八课能规划了计划生成 → 验证 → 逐步执行 第九课能拆解了模糊步骤 → 原子动作 → Schema 验证还差什么第十课思维链推理——让规划过程更严谨处理步骤间的依赖关系十、下期预告第十课思维链推理——让 Agent 学会想清楚再做本课的原子动作已经是可验证的最小执行单元了。但还有一个问题步骤之间的顺序和依赖。比如写初稿必须在写大纲之后审校必须在写初稿之后。第八课的执行是简单遍历列表没有处理这些依赖关系。下一课我们将引入思维链推理Chain of Thought和依赖图让 Agent 不仅知道每步做什么还能推理出哪步先做、哪步后做、哪些可以并行做。这是从逐步执行到智能调度的关键升级。敬请期待完整代码获取本课涉及的完整代码包括agent/planner.py——规划器模块新增create_atomic_action()函数agent/agent.py——Agent 类新增create_atomic_action()方法complete_example.py——演示模式4 个场景 交互模式代码获取请参照 本系列第一篇文章。标签#Python#AI Agent#LLM#原子动作#Schema验证#Ollama#Qwen#大模型#手搓Agent本文为《手搓 AI Agent 从 0 到 1》系列教程第 9 课