Soma Zero Tutorials
🔍 搜索功能尚未开启，敬请期待。

5.5 框架组件（Agent 编排的所有组件）

本节定位：5.1 讲了"造一个靠谱 agent 要守哪些纪律"，这一节换成"词典 / 总览"视角，把做一个 LLM agent 系统、编排起来到底有哪些组件一个个摆出来、讲清楚——每个组件是什么、解决什么问题、谁是谁的零件。其中最容易混的一对——skill（技能）和 tool（工具）的边界，单开一节重点讲透。读完这一节，你再看任何 agent 框架的文档，都能把它的名词对号入座。

这一节怎么读：先给一张"总骨架"，知道 agent 由哪几大块组成；再按五层把组件逐个讲（每个组件都先用大白话说"它是干嘛的"）；然后专门用一节讲 skill vs tool 的边界；接着讲一个顶层抉择——什么时候该上 agent、什么时候写死 workflow 就够；最后落回我们自己的 Soma / Anima 项目，把这些组件对号入座。

一、总骨架：一个 agent 由什么组成

先把最顶层的全景给出来。一个 agent，本质上是这么一组东西凑在一起转：

agent = 大脑（LLM）+ 规划（planning）+ 记忆（memory）+ 工具使用（tool use），在一个环境（environment）里、按一个循环（loop）运转。

用一句人话串起来：一个大脑（大模型）在某个环境里，靠记忆记着来龙去脉、靠规划想清楚下一步、再调工具动手干，干完看结果、接着想——这个"想→干→看→再想"的循环转下去，直到把活干完。这就是 Lilian Weng 那篇被广泛引用的综述给出的 agent 经典骨架。

这五大块只是"粗骨架"。真要把一个系统搭起来，每一块底下还细分出很多具体组件。下面我们把它们按"职责"摊成五层来讲，从最上面的"想"，一路讲到最下面的"管"。

二、按五层讲组件

为什么分五层？因为一个 agent 系统的组件，按职责天然分成五类：谁来想（大脑层）→ 怎么干活（能力层）→ 跟外界怎么接触（接口层）→ 靠什么记事（支撑层）→ 怎么保证不出事（治理层）。先看全景图，再逐层拆。

LLM agent 系统的五层组件分层图
图 5.5.0　一个 LLM agent 系统的五层组件：大脑（决策）→ 能力（干活）→ 接口（对外）→ 支撑（记忆）→ 治理（安全）

2.1 大脑层 · 决策

这一层管"想"，是整个 agent 的指挥中枢。

  • LLM 当 policy（策略）：是什么——把大模型当成那个"看了现状、决定下一步做什么"的决策器。"policy（策略）"是强化学习里的词，意思是"从状态到动作的映射"；这里就是"给模型看现在的局面，它输出下一步该干啥"。解决什么——让"决定怎么做"这件事不用写死成代码，交给会推理的大模型临场判断。
  • agent loop（主循环）：是什么——"观察（observe）→ 思考（think）→ 行动（act）→ 再观察"这个一圈一圈转的循环，就是 agent 的心脏（5.1 已详述）。解决什么——让 agent 能多步地、根据反馈不断调整，而不是"一次问答"就结束。
  • planning（规划）：是什么——让模型在动手前先"想清楚怎么做"的一组方法。常见四种：
    • CoT（思维链，Chain-of-Thought）：让模型把"推理过程一步步写出来"再给答案，想得更稳。
    • ReAct（推理 + 行动交替）：把"想一句（Reasoning）"和"做一个动作（Acting）"交替进行——想一下、调个工具、看结果、再想，是当今 agent 最主流的主循环写法。
    • reflection（自我反思）：做完后让模型"回头评判自己做得好不好"，把教训写下来，下次改进（代表作 Reflexion）。
    • plan-and-execute（先出计划再执行）：先让模型列一份完整计划（第一步、第二步……），再照计划逐条执行；适合步骤清晰的长任务。
  • orchestrator / router（编排器 / 路由器）：是什么——做"分诊"的那个组件：这一步该调哪个 skill、哪个 tool？该交给哪个子 agent？什么时候该停？ 它就像分诊台护士，把每个请求导向正确的处理者。解决什么——当 agent 手里有很多能力时，得有人决定"这次用哪个"，并管住"何时收手"。

2.2 能力层 · 怎么干活

这一层是 agent "动手的本事"所在，也是本节的重点。这里有四个组件，tool 和 skill 是核心，必须分清。

  • tool（工具）：是什么——一个带 schema 的原子函数。schema 就是这个工具的"说明牌"：名字 + 一句描述 + 输入参数的 JSON Schema（规定要填哪些参数、什么类型）。它一进一出、做完就返回。关键点：模型只负责决定"调哪个工具、参数填什么"，真正执行的是背后的代码，不是模型自己。解决什么——让模型能"伸手到外部世界"做确定性的事（查数据库、算一道题、发一条指令），而不是只会"嘴上说"。
  • skill（技能）：是什么——一个程序性知识包 / 操作手册。以 Anthropic 的 Agent Skills 为标准范例：一个 skill 就是一个文件夹，里面有一份 SKILL.md（带"名字 + 描述"的说明书 + 详细指令），外加可选的脚本（scripts）和资源（resources）。它最妙的机制叫渐进披露（progressive disclosure）：模型一开始只读到这个 skill 的"名字 + 一句描述"（几乎不占上下文）；只有当任务跟它相关时，才加载 SKILL.md 全文；用到里面的脚本 / 资源时，才进一步加载——按需展开，不一上来就塞满上下文。最关键的一句：skill 自己不执行，它的作用是"把怎么干这件事的打法讲给模型听"，模型读完手册，再去调具体的 tool 把活干完。所以——skill 教打法，tool 出动作；skill 比 tool 高一层、会编排 tool。解决什么——把"一类任务的成熟打法 / 领域经验"沉淀成可复用、可分享的包，让 agent 不必每次从零摸索。
  • 子 agent / 委派（delegation）：是什么——把一个子任务整个交给另一个 agent去完成，它有自己独立的上下文，干完把结果汇报回来。解决什么——隔离上下文（5.1 讲过"单脑收口"的取舍）、让专职 agent 干专职活；但也别滥用，能不拆就不拆。
  • RAG（检索增强生成，Retrieval-Augmented Generation）：是什么——回答前先从外部知识库里检索出相关材料，再把它拼进提示词一起喂给模型。解决什么——让模型用上"训练时没见过、或太多装不进上下文"的知识（公司文档、最新资料），既减少瞎编、又不用把整个知识库塞满上下文。

2.3 接口层 · 对外触点

这一层是 agent 跟"外面世界"打交道的那些触点。

  • environment / world（环境 / 世界）：是什么——agent 作用于它、并从它那里观察的对象。对一个编码 agent，环境是文件系统和终端；对我们的机器人，"世界"就是棋盘 + 机械臂 + 相机。这正是我们项目里说的"世界 = 接口"——agent 通过这层统一接口去"看"和"做"。解决什么——把"agent 能感知什么、能改变什么"收口成一个清晰的边界。
  • resource（资源）：是什么——提供给模型当上下文的只读数据（一份文档、一段配置、一张表）。一句口诀分清它和工具：资源是"读"，工具是"做"——资源只供模型查看、不产生副作用；工具会真的执行、改变世界。解决什么——让模型能"看到"必要的背景信息，又不至于把"读"和"动手"混为一谈。
  • MCP（Model Context Protocol，模型上下文协议）：是什么——一个开放标准，规定了"AI 应用怎么去连接外部的工具和数据源"。官方的比喻是"AI 世界的 USB-C 接口"：就像 USB-C 给设备定了一个统一插口，MCP 给"模型连工具 / 连数据"定了一个统一插法，一次实现、到处可用。和 tool / world 的关系——MCP 不是又一个新组件类型，而是一种"标准的接线方式"：你把一个工具或数据源做成"MCP 服务器"，任何支持 MCP 的 agent 都能即插即用地把它当 tool（做）或 resource（读）来用。换句话说，tool / resource 是"能力本身"，MCP 是"把这些能力标准化地插到 agent 上的协议"。解决什么——免去给每个工具、每个 agent 两两写一遍对接代码。

2.4 支撑层 · 记忆与状态

这一层让 agent "记得住事、理得清状态"。5.1 已深入讲过记忆工程，这里把组件名词对齐一遍。

  • memory（记忆）：是什么——分两大类。短期 / 工作记忆：就是当前这次任务塞在上下文窗口里的东西，任务一结束就没了。长期记忆：写到外部、能跨任务留存的东西，又细分两种——情景记忆（episodic）记"具体发生过的事 / 经历"（如"上次这种残局我换子换早了"），语义记忆（semantic）记"沉淀下来的事实 / 知识"（如"这种开局的标准应法"）。还有一个常见小组件 scratchpad（草稿纸）：模型临时打草稿、记中间结果的地方。解决什么——突破"上下文窗口装不下"和"换一次任务就忘光"两个限制。
  • state / context（状态 / 上下文）：是什么——这次任务"当前进行到哪了"的工作状态（走到第几步、上一步成没成、手头有哪些中间结果）。解决什么——让流程的每一步都知道"我现在在哪、接下来该干嘛"，也是 checkpoint 能存档恢复的依据。
  • context engineering（上下文工程）：是什么——精挑细选"到底哪些信息该放进上下文"的功夫（5.1 的主线）。解决什么——对抗"上下文越长、模型对里面信息的可靠召回反而越差"（context rot）。核心原则：用能达成目标的、最小的一组高信号信息。
  • prompt template（提示词模板）：是什么——把"系统指令 + 工具说明 + 记忆 + 当前状态"按一个固定模板拼成最终喂给模型的提示词。解决什么——让"每次怎么组织提示词"标准化、可复用、可调试，而不是每次手拼。

2.5 治理层 · 安全

这一层管"别出事"，对会真实运动的机器人尤其关键（5.1 第六节是它的展开）。

  • guardrails（护栏）：是什么——一道不经过模型的、确定性的代码闸门，在动作真正执行前做硬校验（参数是否合法、是否越界），不满足就硬拦。解决什么——把"硬安全"从"靠提示词求模型听话"升级成"代码强制阻断"，模型再怎么想也绕不过。
  • HITL（人在环，Human-in-the-Loop）：是什么——在高风险 / 不可逆动作执行前，暂停下来交给人确认，人点头才继续。解决什么——给不可逆的物理动作加一道"人来兜底"的最终保险（正是我们项目"真机命令必须由人执行"的体现）。
  • checkpoint / 持久化：是什么——把每一步的状态存成快照写到外部。解决什么——崩溃 / 断电 / 急停后能从断点恢复，不用从头再来（5.1 已详述，且强调"重放只能用于仿真和逻辑层、绝不重放真机动作"）。

三、重点：skill 与 tool 的边界

这一对最容易混，单独讲透。先看图，再上对照表和口诀。

skill 与 tool 的边界
图 5.5.1　skill 是"被加载的打法手册"（自己不执行，教模型怎么编排 tool）；tool 是"被调用的原子动作"（被调到才执行，做完即止）
对比维度tool（工具）skill（技能）
本质是什么一个带 schema 的原子函数一个含 SKILL.md 的文件夹（操作手册 + 脚本 + 资源）
怎么被用上被调用（模型决定调它、填参数）被加载（模型把手册读进上下文）
自己执行吗会（背后代码真的跑）不会（只提供知识，靠模型再去调 tool）
装的是什么一个确定性动作一类任务的"程序性知识 / 打法"
层级关系底层零件高一层，会编排多个 tool
上下文占用schema 常驻（描述要简洁）渐进披露，按需加载，几乎可"无限扩展"
粒度小（一进一出）大（可能是一整套多步流程）

一句口诀记住边界：tool 是"被调用的原子动作"，skill 是"被加载的程序性知识"。

边界模糊点（诚实地说一句）：这两者并不是泾渭分明的。当一个 skill 内部其实只包了一次工具调用、它的 SKILL.md 手册近乎为空（没什么"打法"可教）时，这个 skill 就退化成了那个 tool 的一个别名——此时再叫它 skill 已没多大意义。判断标准很简单：这个包里有没有"值得教给模型的程序性知识 / 多步打法"。有，才配叫 skill；没有，它就只是个 tool。

四、顶层抉择：workflow 还是 agent

在动手搭之前，还有个更高层的抉择，直接决定成本和可靠性。Anthropic 那篇《Building effective agents》把"agentic 系统"分成两类：

  • workflow（工作流）：是什么——把流程用代码写死，第一步干啥、第二步干啥、什么条件走哪个分支，全是预先编排好的（模型可能在某个节点里被调一下，但"走哪条路"是定好的）。好处——可预测、可复现、便宜（不用反复让模型决策）。
  • agent（智能体）：是什么——把"下一步做什么、用哪个工具、要不要继续"交给模型临场自主决定。好处——灵活、能应付开放和意外情况；代价——更贵（每步都要调模型）、更不可预测、更难调试。

实践准则（来自该文）：能用写死的 workflow 解决的，就别上 agent。 只有当任务步骤无法预先确定、必须临场判断时，灵活性带来的收益才值得 agent 的额外成本和不确定性。先用最简单的方案，复杂度只在确有必要时才加。

这条准则和 5.1 那个"能用固定流程就别放权"的结论是同一个精神——对一台有物理风险的机械臂，主流程尽量写死（workflow / 行为树），只在确实需要临场判断的节点上才让模型自主。

五、落到我们 Soma / Anima 框架

把上面这套组件词典，对到我们自己的项目上，就能清楚看出"已经有什么、正在补什么"：

  • world（世界 = 接口）：已有。我们的统一接口（项目里叫 AWI / 世界接口）就是接口层的 environment / world——agent 通过它去"看棋盘、驱动臂"。
  • agent loop（主循环）：已有。大脑层的 ReAct 式主循环（想一步、调一下、看结果、再想）已经在跑。
  • 记忆 / 上下文 / 安全闸：已有基础。支撑层的外置进度文件 + checkpoint、治理层的确定性安全闸门与人在环（真机由人执行），在 5.1 都已落地为设计原则。
  • skill 层：正在新增的一层。我们要把"对弈这类任务的成熟打法"沉淀成 skill（比如 5.4 讲的"通用对弈 skill"），让大脑读手册、再去编排底层 tool 干活。

一句话对齐分工：world = 接口（agent 看与做的统一边界）、skill = 对弈能力（一套被加载的打法手册，会编排 tool）、tool = skill 内部的零件（一个个被调用的原子动作）。这正好把本节的组件词典，接回了 5.4 "通用对弈 skill，象棋是第一个适配器"的设计。

六、本节小结

  • 总骨架：agent = 大脑(LLM) + 规划 + 记忆 + 工具使用，在环境里按循环运转。
  • 五层组件：大脑层（LLM policy / loop / planning / orchestrator）、能力层（tool / skill / 委派 / RAG）、接口层（world / resource / MCP）、支撑层（memory / state / context engineering / prompt template）、治理层（guardrails / HITL / checkpoint）。
  • skill vs tool：tool 是被调用的原子动作，skill 是被加载的程序性知识；skill 高一层、会编排 tool。 手册近乎为空时 skill 退化为 tool 的别名。
  • 顶层抉择：能写死的 workflow 就别上 agent——可预测、便宜；只有非临场判断不可时才上 agent。
  • 对到项目：world / loop / 记忆 / 安全闸已有，skill 层是正在新增的一层；world=接口、skill=对弈能力、tool=skill 内零件。

参考来源