代码 vs JSON：工具动作表示之辩——CodeAct 的实证与代价
同一个拉数据、分组算均值、画图的任务，JSON 工具路线要约 53 次往返，一段代码一个动作跑完；CodeAct 在 17 个模型上给出 12/17 成功率最高的实证。但功率上去了，schema 校验只剩语法层，影响面扩到文件/网络/进程。本篇把两边论据摆开，帮你判断自己的 agent 该用哪种动作表示。
同一个数据分析任务，JSON 工具路线要约 53 次往返，一段代码一个动作跑完。这笔账后面还会反复出现。差别就出在动作表示（action representation）上：Action 到底写成一条填好参数的 JSON，还是一段可执行代码？
这是 agent 设计里最早拍板、也最难回头的一格。Executable Code Actions Elicit Better LLM Agents（CodeAct） 拿 17 个模型做了系统对照，是目前最硬的证据：代码动作在多数模型上获胜；但 slides L2 p.17 同时递来一张三栏账单，功率越大，约束与安全越贵。
一、代码是元工具：53 次往返 vs 一个动作
工具怎么用的前提，是动作用什么写。What Are Tools Anyway? A Survey from the Language Model Perspective 把工具的创造、选择、使用纳入统一分析框架，动作表示是整个框架里最先要定的一格。
slides L2 p.13-15 的论点可以浓缩成一句话：代码是元工具（meta-tool）。它能在一个动作内组合三样受限 JSON 动作空间给不了的东西：
- 控制流：循环、条件。
- 库：pandas 等整个生态。
- 多操作：连续多步一口气写完。
JSON 动作每步只能选一个函数、填一份参数。对每个分组各算一次这种逻辑写不进一个 JSON 对象。只能展开成几十次独立的函数调用。
课程用的量化例子（slides L2 p.13-17）是一个数据分析任务：拉 1 个 CSV、过滤、算 50 个分组均值、画 1 张图。JSON 工具路线的账单：1 次 fetch + 1 次 filter + 50 次 group_mean + 1 次 plot，约 53 次往返。
CodeAct 路线则在同一个动作里用循环完成全部计算，并复用中间变量。CSV 进了内存之后，过滤、分组、画图共享同一份数据。不再来回序列化。
group_mean {“group”: “华北”} → 等一次往返 group_mean {“group”: “华东”} → 再等一次往返 …… 共 50 次调用，每次都带着全量历史重新推理
for region in df [“region”].unique (): means [region] = df [df [“region”] == region][“value”].mean () 一个动作提交执行；df 与 means 是同一段代码里的变量
二、实证数字：12/17，以及「报错也是观测」
CodeAct（UIUC Heng Ji 组，ICML 2024）在 17 个模型上做了系统对照，结论是两组数字：12/17 的模型用代码动作拿到最高成功率，12/17 的模型用代码动作用的轮次最少。质量与效率，两项指标都占多数。
slides L2 p.16 那张图展示的是 8 个模型的子集，在那个子集里代码动作全胜，视觉冲击很强。但论文全量是 17 个模型、两项指标各 12/17；转述时务必写 12/17，别被子集图放大成 17/17。
比排名更有机理价值的是第二个发现：错误消息本身是有用的 observation。代码执行失败时，解释器的报错作为观测回灌上下文，模型据此修订代码再执行。这就是动态修订（dynamic revision）。
JSON 路线里参数错了，多半只能换个值重发；代码路线的报错携带着堆栈与变量线索，修复空间大得多：
这条路线的工程落点：OpenHands 的工具体系就以 CodeAct 为底座（官方 references）。想看代码动作在真实 agent 框架里怎么注册、怎么执行、观测怎么回灌，它是最直接的参考实现。
三、三栏账单：功率、约束、影响
slides L2 p.17 把代码是高功率工具这件事拆成三栏对账，每一栏都是一组交换：
| 栏目 | 得到 | 失去 |
|---|---|---|
| 表达力强 | 循环、变量、库，任意逻辑可组合 | —— |
| 更难约束 | —— | 动作空间宽，验证不如窄类型接口精确 |
| 影响更大 | 能碰文件、网络、进程 | 必须配沙箱、资源限额、权限、审计日志 |
约束一栏最值得展开。窄 JSON 接口在执行前就能按 JSON Schema 做四层约束校验，参数不合法根本到不了执行器。
换成代码，四层里只剩语法层可用：执行前你只能判断这段代码能否被解析；至于它要删哪个文件、连哪个网络，要跑起来才知道。
于是第三栏不是可选项。沙箱（sandbox）、资源限额、权限、审计日志，这四样是代码动作的生产标配。
辩论至此可以收口。窄接口与代码各有一片自己合适的地盘：
- 窄接口。动作可枚举、参数可先验校验、每一步审计可数，适合面向外部世界、动作需要逐一留痕的场景。
- 代码。数据在动作内部流转、逻辑任意组合，适合面向数据与代码本身的批处理、探索型任务。
工程上常见的和解是混合工具集：十几个动词级 JSON 工具加一个受控 shell。这对应讲次页实践视角里那条砍工具反而更准的经验。
四、编排视角：第三条路 —— 动作不变，控制器上场
这场辩论还有第三个参赛者：动作表示不动，让 LLM 升上去当控制器，把组合逻辑从动作内部挪到控制器与一群工具之间。
HuggingGPT 让 LLM 当总控，调度 Hugging Face 上百个专家模型，走任务解析 → 模型选择 → 任务执行 → 响应生成四阶段流水线；Chameleon 则让 LLM 做认知控制器（cognitive controller），即插即用地编排检索、程序执行等模块。
两条分岔，一条是模型池调度，一条是模块化管线，合称控制器型编排（orchestration）。
与 CodeAct 对照，差别在组合逻辑放哪：控制器型编排把先做什么后做什么写在控制器的调度里，每次下发仍是一次受限动作，53 次往返的账单在这条路线下同样成立；CodeAct 把组合逻辑直接写进动作本身，一个动作就是一段程序，失败面则全部押在沙箱与权限边界上。
slides L2 p.13-17 把两条路线并排摆开。动作表示的选择，同时决定了 agent 的功率上限与安全下限。
与本讲的连接
本篇下钻的是伴读笔记「接口的形状：细粒度函数 vs 通用程序接口」一节，那道每个 Agent 工程师绕不开的第一道设计题，在 slides L2 p.13-17 有完整的论据与账单。
资料卡中 m-codeact 是本篇主文献，m-hugginggpt 与 m-chameleon 构成编排路线的对照阅读，m-what-are-tools 则是讲次页「工具定义」板块的概念地基。
与同讲前几篇详解连起来读：ReAct 轨迹篇定了循环的节奏，序列化方言篇讲了 JSON 动作在词表层长什么样，本篇补上最后一格，Action 这一行到底该用 JSON 写还是用代码写。
quiz 若考「代码动作的优势与代价」，答案骨架就是那张三栏账单：
- 功率。循环、变量、库，任意逻辑都能在一个动作里组合。
- 约束。动作空间一宽，执行前就只剩语法层校验。
- 影响。能碰文件、网络、进程，沙箱、资源限额、权限、审计日志必须配齐。
本节论文与规范
本节资料
- Chameleon: Plug-and-Play Compositional Reasoning with LLMs 论文2304.09842进阶
GPT-4 作为认知控制器，即插即用地编排知识检索、程序执行等异构模块，完成科学问答等复杂任务。与 HuggingGPT 对照阅读，可看清「控制器编排」的两条技术分岔：认知型模块组合与模型市场调度。
- Executable Code Actions Elicit Better LLM Agents 论文2402.01030进阶官方指定
系统论证「可执行代码」是比 JSON 函数调用更强的 agent 动作表示：代码动作天然支持组合、控制流与变量复用。在 17 个模型上实证，12/17 同时拿下单步与多步双料冠军，并催生 OpenHands（原 OpenDevin）框架。本讲 CodeAct 板块的核心文献。
让 LLM 当总控，调度 Hugging Face 上百个专家模型：任务解析→模型选择→任务执行→响应生成四阶段流水线。「LLM as controller」编排范式的代表，也是理解「一个 agent 管一群工具」与单工具调用差别的最好入口。
- What Are Tools Anyway? A Survey from the Language Model Perspective 论文2403.15452入门官方指定
从语言模型视角系统回答「什么是工具」：给出统一的形式化定义，把工具知识与事实性知识、动作性知识区分开，并建立覆盖工具创造、选择、使用的统一分析框架。本讲「工具定义」板块（p.3-5）的概念地基即出自此文，是官方指定的第一篇入门读物。
AI 生成 · 仅供参考，与课程方无关。选中正文里的任何一段也能直接问我（解释一下 / 举个例子）。
本详解以 CMU 11-768 AI Agents (Fall 2026) 课程大纲为参考框架独立撰写，AI 辅助起草、人工抽审。 涉及的官方课件、论文与课程材料版权归原所有方，讲义为站内镜像、其余外链原文出处； 观点与文字（除标注引用外）为作者原创。