30秒快速回答： CodeAct（Code as Action，代码即行动）是一种让 AI Agent 直接写代码、再执行代码来完成动作的新范式。传统 Agent 调用工具时，大模型输出一段 JSON（
{"name": "search", "arguments": {...}}），由运行时解析后调用对应函数；而 CodeAct 让模型直接输出一段 Python 代码，沙箱执行这段代码来完成任务。循环、条件、变量、算术运算在代码里原生可用，多步任务不再需要一轮轮”JSON 对话”，Hugging Face 的 smolagents、苹果的研究以及多个主流框架在 2026 年纷纷押注这一方向，把它视为 Agent 执行层的下一站。
核心价值一句话： 工具调用从”填表单”进化成”写程序”——Agent 用代码自由组合动作，任务成功率更高、交互轮数更少、能力边界更宽。
为什么 2026 年大家都在讨论 CodeAct？
先看一个典型任务：“找出下载量最高的 3 个文本分类模型，然后计算它们的平均下载量。”
在传统 Function Calling 架构里，Agent 需要这样干活：
第1轮：调用 search_models("text-classification")
→ 返回一堆结果
第2轮：再调用 search_models 换关键词或分页
→ 继续返回
第3轮：调用 add()、divide() 算平均……（如果系统有算术工具）
→ 但多数工具集里根本没有"加法工具"
JSON 工具调用做不了算术、做不了循环、做不了中间变量——每一项能力都要单独注册一个工具，模型每做一个动作都要多烧一轮 token。这就是”N×M 集成困境”在 Agent 内部的版本：工具越多，交互越碎。
CodeAct 让 Agent 直接写一段 Python 解决全部问题：
models = search_models("text-classification", limit=3)
counts = [m.downloads for m in models]
average = sum(counts) / len(counts)
final_answer(average)
一次代码块 = 循环 + 变量 + 算术 + 多次工具调用全搞定。这正是 CodeAct 论文（CodeAct: Executable Code Actions Elicit Better LLM Agents）与 2026 年苹果、Hugging Face 相关研究反复验证的结论：代码是天然的”通用组合层”，工具调用的表达能力上限就是代码语言的表达能力上限。
CodeAct 与 Function Calling 到底差在哪？
| 维度 | Function Calling（JSON 工具调用） | CodeAct（代码即行动） |
|---|---|---|
| 模型输出 | 结构化 JSON（工具名+参数） | 可执行的 Python 代码 |
| 循环/条件 | 需要额外工具或反复多轮 | 代码原生支持 |
| 算术运算 | 多数框架没有算术工具，靠模型口算 | sum() / 表达式直接算 |
| 中间状态 | 靠”对话上下文”传递，易丢 | 变量天然保存 |
| 多步任务交互轮数 | 一步一往返 | 一段代码覆盖多步 |
| 组合复杂动作 | 受限于工具清单 | 函数嵌套、条件分支随意 |
| 安全边界 | 按工具粒度授权 | 必须靠沙箱隔离执行 |
| 代表实现 | OpenAI、LangGraph、CrewAI 等 | smolagents、CodeAct Agent、部分编程 Agent |
核心差异一句话：JSON 是”给系统看的指令”，代码是”给机器跑的程序”。前者每个动作都要模型和系统来回确认，后者把一连串动作打包成一段程序一次性执行。
实测收益（多份 2026 年基准与框架文档的共识）：
- 多步任务的 LLM 交互次数减少约 30%
- 在真实软件工程类任务上的成功率提升最高达 20%
- 代码可复现、可调试、可审计——比黑盒 JSON 调用更容易排查问题
实战：用 smolagents 跑一个 CodeAct Agent
Hugging Face 的 smolagents 是 CodeAct 范式最直观的落地框架，核心就是 CodeAgent：
from smolagents import CodeAgent, HfApiModel, tool
@tool
def search_models(task: str, limit: int = 3) -> list:
"""搜索 Hugging Face 模型，返回模型对象列表"""
# 真实场景这里调用 HF Hub API
return [{"name": f"model-{i}", "downloads": i * 10000} for i in range(limit)]
agent = CodeAgent(
tools=[search_models],
model=HfApiModel(),
max_steps=5,
)
result = agent.run("找出下载量最高的 3 个文本分类模型，然后计算平均下载量")
print(result)
运行时，CodeAgent 会把模型生成的代码块放进受限沙箱（默认 E2B 或本地受限执行器）执行，工具函数以 Python 对象形式直接暴露给模型调用——不是 JSON-RPC，而是真正的”import 进来调用”。
如果你想用更轻的方式理解 CodeAct，可以把它想成：模型拿到一个 Python REPL + 一堆预置函数，它像程序员一样写代码、跑代码、看报错、改代码，直到任务完成。
CodeAct 最大的坑：执行安全
能力越强，风险越大。让模型写代码并执行，等于把”任意代码执行”交给了一个可能产生幻觉的模型。生产落地必须守住三层防线：
| 防线 | 措施 | 说明 |
|---|---|---|
| 沙箱隔离 | E2B、Docker 容器、Firecracker 微虚机 | 代码在隔离环境跑，禁止访问宿主机文件系统与网络 |
| 权限收敛 | 最小化 API Key、只读文件系统、无外网（按需开放） | 即使代码恶意，也拿不到敏感资源 |
| 行为审计 | 记录每次执行代码、输出、耗时 | 可回放、可追踪，出事能定位 |
另外要注意：所有工具输出都要视为不可信输入——代码里可能被注入恶意指令（提示注入），因此”执行前做代码审查/静态扫描”正在成为 CodeAct 框架的标准配置。如果做金融、医疗等高风险场景，建议保留 human-in-the-loop 审批环节。
什么时候该用 CodeAct？
优先选 CodeAct：
- 任务涉及多步数据处理、循环遍历、条件分支（批量分析、ETL、爬取整理）
- 需要算术、统计、格式转换等”通用能力”，不想为每件事注册一个工具
- 你的 Agent 主要跑在沙箱环境里，安全可控
- 需要代码可复现、可审计的场景（数据分析、自动化脚本）
继续用 Function Calling：
- 工具调用是简单的一问一答（查天气、发消息）
- 强合规行业，执行层必须走严格审批流程，不便引入代码执行
- 你的模型对代码生成不够稳（小模型写代码容易翻车）
- 平台只暴露受控 API，不允许任意代码执行
总结与延伸
- CodeAct 的本质：让 AI Agent 用”写代码 + 执行代码”代替”输出 JSON + 系统解析”，把工具调用升级成编程。
- 核心收益：交互轮数减少约 30%、复杂任务成功率提升、能力边界更宽、代码可审计。
- 核心代价：引入任意代码执行风险，必须用沙箱 + 权限收敛 + 审计三件套兜底。
- 选择标准：任务越”程序化”越适合 CodeAct，任务越”一问一答”越适合 Function Calling。
延伸阅读建议： 想深入可以看 CodeAct 原论文（arXiv:2402.01030）、Hugging Face smolagents 官方文档；如果想了解工具调用层协议标准化，可以配合本站的《什么是 MCP 协议？一文读懂 AI 的 USB 接口标准》和《怎么用 Function Calling？让 AI 调用外部工具》一起阅读，正好串起”模型 → 工具 → 协议”的完整链路。