11 · 代码执行与沙箱

给 Agent 一双手，但戴上手套

📚 系列导航：这是《Agent 开发进阶》的第 11 篇（共 24 篇）。上一篇你把知识库接成了 agent 的工具，这一篇给它加一件大杀器——执行代码的能力，外加配套的手套：沙箱、限额与进出管制。下一篇：12 · 人机协作。

你八成试过让模型直接算数或汇总表格：十次里总有两三次，数字对得让你不敢用。于是你想给 agent 一个"执行 Python"的工具，又心里发毛——万一它生成一句删库的代码呢？两种顾虑都对：代码执行是 agent 能力上限的分水岭，也是最容易出事故的工具。这一篇只干一件事：给你的 agent 接上代码执行能力，并把它锁进一个跑不出来的沙箱。

看完这一篇，你会拿到：

• 一条"什么活交给代码、什么活留给模型"的分工判据
• 一个三档沙箱选型梯度：受限解释器 / 容器 / 云沙箱
• 一份可直接照抄的资源限制清单：超时、内存、网络白名单、文件隔离
• 一次在沙箱里跑通的 CSV 数据分析（含验收标准）

---

01 为什么代码执行是"万能工具"

模型口算 38×47 会翻车，但让它写一段算 38×47 的代码，几乎不会错。这就是代码执行的价值来源：模型算不准，但写得出算得准的代码。打个比方，靠谱的会计不心算报表，而是掏出计算器——会算是一回事，敢签字是另一回事。落地判据：凡是确定性计算——CSV/Excel 分析、精确计算、格式转换、批量文件操作——一律让模型写代码、由代码出结果。

💡 一句话总结：把"算"的活从模型手里拿走交给代码，模型只做它擅长的"写"。

02 沙箱梯度：从受限解释器到云沙箱

先立铁律：本地直接 exec 模型生成的代码不是可选项，是事故预定。隔离方案三档，按投入从轻到重：受限解释器（进程内限制 import 和内置函数，防君子不防小人，只适合表达式级计算）；容器隔离（主流：一次性容器用完即毁，文件系统天然隔离）；云沙箱服务（托管隔离环境，最省心但引入外部依赖，2026 上半年方案演进快，以官方文档为准）。我的判断：个人项目也从容器档起步，第一档直接跳过。

💡 一句话总结：隔离强度按风险选档，但"零隔离裸跑"这一档不存在。

03 资源限制：给沙箱上四道锁

进了沙箱不等于安全。四道锁：超时（防死循环空转）、内存上限（防一行代码吃光宿主机）、网络默认断开（白名单放行，防乱装依赖和数据外传）、文件系统隔离（只能看见挂载给它的目录）。

# 伪代码：沙箱执行封装，参数以所选沙箱方案官方文档为准
result = sandbox.run(
    code=generated_code,
    timeout_s=30,           # 超时熔断
    memory_mb=512,          # 内存上限
    network="deny",         # 默认断网
    mounts={"/data": "ro"}, # 输入只读挂载
)

预期输出：正常时拿到 stdout 与 exit_code=0；越限时拿到超时/内存错误——把错误当 observation 回给模型重试。

💡 一句话总结：超时、内存、断网、文件隔离，四道锁一道都不能省。

04 产出物管理：文件怎么进出沙箱

进：输入数据只读挂载，agent 改不坏原件。出：只允许写进指定输出目录，出沙箱前过两道检查——文件类型白名单、大小上限。最关键的一条：结果文件不要整个塞回上下文，让代码同时产出几行统计摘要，摘要进上下文，全量留在磁盘给人看。我见过 200MB 的结果被原样回填，一轮就把上下文吃穿。

💡 一句话总结：数据只读进、白名单出，回上下文的永远是摘要不是全量。

05 动手：沙箱内完成一次 CSV 分析

任务：① 按 02/03 节接好带四道锁的沙箱执行工具；② 丢给 agent 一个千行级 CSV，要求统计行数、按列分组求和、找异常值，产出结果文件加摘要；③ 对照组：同一问题不给代码工具，让模型直接读 CSV 口算。

验收标准：输出目录里有统计结果文件，且摘要数字与你手工核对的一致；附一张对比表——代码执行版 vs 口算版的数字正确率。

两种结果都正常：沙箱版全对、口算版出错，说明分工判据成立，把封装固化成标准工具；如果生成代码反复报错，通常是工具描述没讲清环境里有什么库，回第 05 篇修描述——这也是有价值的诊断。

06 小结

你现在应该能：说清哪些任务该交给代码执行、按风险给项目选对沙箱档位、配齐四道资源锁、管好产出物进出。

能力越大，越要想清楚哪些动作不能让它自己拍板。下一篇 12 · 人机协作：审批门、中断与恢复。

---

📎 实战案例

有位开发者本地直接 exec 模型生成的代码，一句误生成的删除命令干掉了测试目录，重建花了一个下午。换成一次性容器沙箱（30 秒超时、512MB 内存、默认断网）后，agent 跑千行 CSV 分析再没出过越界事故——差的只是一层手套。

踩坑

• 我早期本地裸跑生成代码，一句误生成的 rm 干掉了测试目录，恢复环境花了半天——从此沙箱是铁律。
• 沙箱没断网，agent"自作聪明"pip install 了一个不存在的近似包名——供应链风险是真的，默认断网挡掉九成。
• 我没设超时就上线，一段死循环代码空转了 10 分钟才被手动掐掉——超时 30 秒起步，宁可误杀让模型重试。