CodeAct：让AI Agent直接写下「魔法菜谱」

可视化演示

动态演示CodeAct的核心机制，通过总览/传输/转换/输出四种模式展示关键概念与交互流程。

设计理念：为什么主厨不按按钮？

老主厨收了个徒弟。徒弟第一天就抱怨：「师父，咱们厨房这么多台机器，怎么都不够用？我想做一道松鼠桂鱼，可按钮里只有糖醋和红烧。」老主厨笑了：「傻孩子，真正的厨师从来不是按按钮的，而是写菜谱的。你写下做法，让帮厨照做，就能做任何菜。」这正是 CodeAct 的初心——AI Agent 不该被困在预设的按钮里。

在 AI Agent 的世界里，所谓「动作空间」（Action Space），就是 Agent 所有可能执行的行动集合。传统方法把这个集合设计成十几个固定函数，就像微波炉面板上的按钮。而 CodeAct 用「生成一段可执行的 Python 代码」作为动作，把集合从十几个按钮变成无限可能的菜谱库。为什么这很重要？因为代码本身就是一种通用语言，可以表达任意逻辑：算一个微积分、爬一个网页、改一份 PDF——所有操作都在代码的射程之内。

CodeAct 的核心理念是让大语言模型（LLM）直接输出程序，而不是输出固定格式的 API 调用参数。程序运行时，Agent 就像是在把思考过程「写出来」——每行代码都是思维链的外显。我们可以用公式描述这一动作生成过程：

其中，$a_t$ 表示第 $t$ 步的动作，即一段 Python 代码；$\pi$ 是 Agent 的策略，由 LLM 充当；$\sigma_t$ 是当前上下文状态，包含用户指令、历史对话和执行反馈。

这就像主厨看一眼厨房里的食材和客人的要求（上下文），当场写下一份菜谱（代码），而不是跑到操作面板前翻找有没有对应的按钮。CodeAct 让 Agent 拥有了「自由创作」的底层能力。

代码动作空间：菜谱就是一切

有了「写菜谱」的思路，下一个问题是怎么定义菜谱的范围。传统动作空间是有限的函数列表，而 CodeAct 把动作空间定义为「所有可运行的 Python 程序」。在菜谱的比喻里，这等于说：不只是固定几道菜，蒸、炒、炸、焗、分子料理、融合菜……只要写成步骤，帮厨就能做。

代码动作空间为 Agent 提供了三个关键能力。第一是自由组合：代码可以把多个操作串联起来，比如先读取文件、再清洗数据、最后画图，一个程序搞定，不需要反复调用不同的工具。第二是多步操作：一段代码内部可以有循环、条件、函数调用，这意味着 Agent 可以在一次动作内完成复杂的内部推理。第三是上下文感知：LLM 生成的代码会自然参考上文信息，比如根据之前报错信息调整逻辑。

我们可以把代码动作空间看成一个数学集合：

写成菜谱的好处是，任何复杂的菜都能拆解成步骤；同理，任何复杂任务都能拆解成代码中的语句。你不需要预先给 Agent 配备 1000 个工具按钮，只要给它一个 Python 环境，它就能自己「编」出需要的能力。当然，这也对 Agent 的代码能力提出了更高要求——主厨得真会写菜谱，不能瞎写。

执行反馈：尝一口菜，修改配方

主厨不是写完菜谱就甩手不管了。他会让帮厨做出来，尝一口，咸了加盐，淡了补味，再让帮厨重新做。CodeAct 最迷人的地方就在这里：代码执行后的结果会作为新观察反馈给 Agent，形成闭环。

反馈信息有两种顔色。成功反馈是程序正常运行并输出结果，比如返回一个 DataFrame、下载一张图片、发送一封信——这些结果成为下一步计划的依据。失败反馈则更像是帮厨的抱怨：「菜谱第 3 步写错了，锅里起火啦！」报错信息和异常堆栈告诉 Agent 哪里出了问题，Agent 据此修正代码，再执行，再反馈，直到任务完成。

这个过程用状态转移公式可以表达为：

其中，$\oplus$ 表示「拼接」，即将新观察到的执行结果追加到上下文末尾；$\text{execute}(\cdot)$ 是运行代码并捕获输出、日志和错误信息的函数。

反馈迭代让 Agent 不再「一锤子买卖」。研究显示，CodeAct 在需要多步操作的任务中表现远超单次生成，因为每次反馈都是免费的「经验」。主厨越尝菜，手艺越精；Agent 越跑代码，越接近正确答案。这就是闭环的魅力。

对比传统工具：按钮 vs 菜谱

码农界有句话：不要重复造轮子。所以在 CodeAct 哲学之前，Agent 通常依赖「工具调用」（Tool Calling）：设计者预先写好一批函数，比如 search_web、send_email，Agent 的任务是挑选合适的函数并填好参数。这就像厨房里摆着一排按钮，每个按钮封装好了一道菜的做法。

但传统工具有一个痛处：预设接口是死的。你想让 Agent 用 search_web 搜索三个关键词再聚合结果，函数没这个参数；你想让 Agent 把结果画成散点图再存到某个目录，函数也没这个能力。你只能不断往列表里塞新函数，治标不治本。而 CodeAct 允许 Agent 自己写代码来组合、封装、适配任何需求。

不过，这不是说传统工具一无是处。在安全性要求高、操作被严格限定的场景（比如只允许查余额），按钮反而更稳妥。两种方式的空间关系可以这样看：

这给从业者的启示是：别把工具调用和 CodeAct 看作「谁取代谁」的对立关系。成熟的系统常两者兼用——按钮负责高频稳定操作，代码负责灵活探索。就像高级餐厅里，稳定的例汤用预制按钮，招牌创意菜则靠主厨手写菜谱。

安全考量：厨房里的火与刀

让 Agent 自由写代码并执行，就像给主厨一把锋利的刀。刀能切菜，也能伤人。如果 Agent 被恶意提示注入，或者生成的代码有 os.remove("/") 那种破坏性命令，后果不堪设想。所以安全围裙必须穿上三层。

第一层是沙盒隔离：Agent 的代码在独立容器或受限进程中运行，文件系统、网络、系统调用都受到严格控制。就相当于帮厨在单独的隔音房里操作，砸了东西也影响不到主餐厅。第二层是权限控制：执行环境默认无权限访问敏感数据，需要显式授权。第三层是审计追溯：每一次代码执行都记录日志，包括谁生成的、运行了什么、产生了什么效果，出问题能倒查。安全策略可以形式化为：

安全不是限制，而是保护。主厨刀功越好，越需要练好刀柄握法。CodeAct 的安全研究提示我们：未来 Agent 的能力边界，很大程度上取决于安全执行器的完善程度——把「不可信代码」关进「可信沙盒」，才能让自由与安全兼得。

复杂任务应用：满汉全席的诀窍

为什么我们要大费周章用代码作为动作空间？因为真实世界任务是复杂、非结构化的，远不是两个函数调用能搞定的。想象一桌满汉全席：从前菜、热菜到甜品，每道菜有不同火候、不同顺序。在 CodeAct 之前，Agent 面对这种多阶段任务常常顾此失彼；现在，它可以把整个上菜流程写成一个 Python 脚本，按步执行，根据每步反馈动态调整。

典型场景包括：数据处理——Agent 自动编写 pandas 代码完成数据清洗、特征工程、结果可视化；网页操作——通过 Playwright 等库生成浏览器自动化代码，完成登录、表单填写、信息抓取；科学计算——用于求解复杂方程、模拟物理过程；工作流——把多个工具编排成一个管道，自动按时执行。这些任务都共享一个特征：需要精密的步骤控制与条件判断，正是代码的舒适区。

衡量 CodeAct 优劣的终极指标是任务成功率。理想情况下，Agent 的策略应最大化「代码执行后达成目标」的概率：

主厨的每一道菜都可以被客人打分（成功/失败）。通过反复练习（训练），他逐渐提高拿高分（任务成功）的概率。CodeAct 让 Agent 把「满汉全席」拆成一道道可验证的菜，用代码逐个攻破，最终端出一桌完美宴席。

实践与展望：把魔法厨房开成连锁店

学会了单主厨写菜谱，我们还能做更多。CodeAct 的实践路径大致有三个方面：训练策略——用「代码-执行-反馈」的轨迹数据去微调 LLM，让模型更擅长生成能运行的代码，这就像让主厨不断复盘自己的菜谱；上下文管理——代码执行反馈可能很长，聪明的 Agent 需要摘要与压缩，只保留关键信息，相当于主厨记菜谱时只写要点；可扩展性——多个 Agent 可以共享代码库、协作完成任务，形成「连锁厨房」。

这条技术路线的未来也在逐渐清晰：我们可能会看到 Agent 不只是生成代码，还会维护自己的代码库，自动重构、测试、部署；也可能看到 Agent 之间交换可执行代码作为「加密语言」，就像主厨们互相传秘方。当然，这也带来新的挑战：代码质量评估、跨 Agent 的代码信任、长链路执行的可控性，等等。优化 Agent 自身也是一个「写代码」的过程，用公式表达即：

其中 $\mathcal{D}_{\text{trace}}$ 是本轮收集到的「菜谱-反馈」轨迹数据。

主厨不会因为会做一道菜就满足。他会不断研发新品、训练徒弟、开分店，把魔法厨房发扬光大。CodeAct 的想象空间远不止解决当前任务，而在于让 Agent 具备自我进化的能力——用代码与世界对话，用反馈积累智慧，这就是通用人工智能的一小块地基。

AI 应用场景

Python 演示

import osimport importlib.util class CodeActAgent:    def __init__(self):        self.history = []        self.namespace = {}        self.gc_count = 0     def act(self, code):        """根据当前上下文生成动作（此处简化为直接接受代码）"""        return code     def execute(self, code):        """执行代码，捕获输出与错误，返回反馈"""        self.gc_count += 1        old_stdout = []        try:            exec(code, self.namespace)            result = self.namespace.get("result", "OK")            return ("success", result)        except Exception as exc:            return ("error", str(exc))     def run(self, goal, get_code_fn):        """主循环：生成代码-执行-反馈-迭代，最多 N 轮"""        for i in range(3):            code = get_code_fn(goal, self.history)            self.history.append(("code", code))            status, feedback = self.execute(code)            self.history.append(("feedback", feedback))            print(f"第 {i+1} 轮 状态={status} 反馈={feedback}")            if status == "success" and feedback == goal:                return True        return False def solve_sum(goal, history):    """模拟LLM：根据目标写出加法代码"""    nums = goal[1]    return f"result = {nums[0]} + {nums[1]}" def solve_product(goal, history):    nums = goal[1]    return f"result = {nums[0]} * {nums[1]}" if __name__ == "__main__":    agent = CodeActAgent()    tasks = [("sum", (3, 5)), ("product", (4, 7)), ("sum", (10, 20))]    for task in tasks:        print(f"--- 目标: {task} ---")        agent.run(task[0], lambda g, h, t=task: solve_sum(t, h) if t[0] == "sum" else solve_product(t, h))

1. exec(code, self.namespace)在共享命名空间中执行 Agent 生成的代码，这是 CodeAct 中「帮厨执行菜谱」的核心动作。
2. self.namespace维护一个持久化的代码执行环境，让不同轮次的代码可以共享变量，模拟真实 Agent 的上下文状态。
3. self.history.append(...)把生成代码和执行反馈都存入历史记录，相当于主厨的烹饪日志。
4. except Exception as exc捕获执行异常并返回错误消息，这正是 CodeAct 中「报错反馈」的实现机制。
5. self.gc_count统计代码执行次数，便于观察迭代轮数（避免与内部属性冲突，使用 _count 后缀）。

常见误区

面试题