• 文档
• 教程
• 知识库

导读

在 AI Agent 的能力拼图中，"代码执行 / REPL 工具"承担着一个特殊角色：它让 Agent 不再只是把代码当作文本生成出来，而是可以真正运行代码、观察运行结果，并基于结果修正自己的输出。本文以 developer-roadmap 仓库 ai-agents 学习路径 中的 Code Execution / REPL 主题为骨架，系统讲解 REPL 工具的核心概念、在 Agent 循环中的位置、工具定义与函数调用方式、典型实现模式以及沙箱安全实践，帮助你从"会用代码工具"进阶到"能设计出安全、可靠的代码执行型 Agent"。

一、什么是 REPL 与代码执行工具

REPL 是 Read-Eval-Print Loop（读取–求值–打印–循环）的缩写，它是交互式编程环境最经典的工作方式：读取你输入的一段代码，立即求值执行，打印出结果，然后循环等待下一次输入。Python 交互式解释器、Node.js 的node命令行、Jupyter Notebook 的单元格，都是 REPL 的具体形态。

在 AI Agent 语境下，REPL 被封装为一种工具（Tool）。原文档给出了非常清晰的定义：代码执行或 REPL 工具，让 Agent 运行代码并看到实际结果，而不是仅仅把代码作为文本生成出来。这一句话点出了它与普通"代码生成"的本质区别：

• 代码生成（Code Generation）：Agent 依据自然语言需求，产出可供人使用的源码，是否运行、运行是否成功，由开发者自行验证。参见仓库中的 Code generation 主题。
• 代码执行（Code Execution / REPL）：Agent 在对话过程中直接执行自己写出的代码，读取 stdout/stderr 或返回值，把"运行结果"作为下一步推理的输入。

仓库 What are Tools? 主题指出，工具就是 Agent 可以调用以完成任务的外部技能或资源，例如计算器、数据库、搜索 API。代码执行工具正是这样一类"特殊计算器"：它把任意可编程问题交给真实的解释器或运行时处理，让答案建立在真实执行结果之上，而不是模型对结果的"猜测"。

二、为什么 Agent 需要"亲手运行代码"

原文档概括了三个典型用途：计算、数据处理、验证生成的代码。展开来说，代码执行工具的价值体现在以下几个方面。

2.1 可靠计算：把数值问题交给真实运行时

大语言模型在处理多步算术、大数运算、浮点精度等问题时容易出错。与其让模型口算，不如让它写出一小段代码交给 REPL 执行。例如 Agent 只需生成sum([0.1] * 10)交给 Python 执行，就能得到浮点误差的真实答案0.9999999999999999，并据此做出正确判断。这类"用工具替代模型硬算"的思路，正是 Agent 架构中"用外部工具弥补模型短板"的典型体现。

2.2 数据处理：从"描述"到"产出"

当任务涉及 CSV 过滤、JSON 转换、文本统计、数据聚合时，Agent 可以编写脚本在 REPL 中运行，直接产出处理后的数据、统计指标甚至可视化结果，而不是用自然语言"描述"一个可能不准确的处理过程。结合 API Requests 主题，Agent 还能先通过 API 获取数据，再通过代码执行工具完成本地处理，形成"取数—处理—输出"的完整链路。

2.3 自我验证：从"写代码"到"测试并纠正自己的输出"

这是原文档强调的质变：给 Agent 代码执行工具，能把它从"写代码的东西"变成"能测试并纠正自己输出的东西"。一个没有执行能力的 Agent 只能基于训练记忆推断"这段代码大概是对的"；而拥有 REPL 工具的 Agent 可以：

1. 写出候选代码；
2. 在 REPL 中运行它；
3. 观察输出是否符合预期（例如单元测试断言是否通过、边界用例结果是否正确）；
4. 若失败，读取报错信息，修正代码后再次运行。

这正是 Agent Loop 主题描述的 observe–decide–act 循环在编码任务上的具体化：Agent 通过工具获取"新鲜数据"（运行结果），更新内部状态（发现 bug），执行新动作（修改代码），循环往复直到目标达成。

三、代码执行在 Agent 循环中的位置

仓库 Agent Loop 文档将 Agent 的工作方式概括为一个快速重复的循环：

收集新鲜数据（来自工具、传感器或记忆）→ 更新内部状态并决策（常含规划/推理步骤）→ 执行选定动作（调用 API、写文件、发消息）→ 检查结果并存储新信息 → 带着最新数据再次循环。

把 REPL 工具放入这个循环，得到如下典型流程：

用户提问 → Agent 规划（决定写一段 Python 代码）→ 调用代码执行工具 → 工具在运行时中执行代码并返回 stdout / 报错信息 → Agent 观察输出 → 结果符合预期？是 → 整理答案返回用户 否 → 根据报错修正代码 → 再次调用执行工具

关键点在于：执行结果成为下一轮推理的输入。报错信息（如NameError、TypeError、断言失败）对模型来说是最有价值的"地面真相"（ground truth），比模型凭空推测的"应该能跑"可靠得多。这也意味着代码执行工具应与 Function Calling 机制配合：模型输出结构化的工具调用（函数名 + 参数），宿主程序执行真实函数，再把结果回传给模型继续对话。

四、如何把 REPL 定义成 Agent 工具

要让模型可靠地使用代码执行工具，关键在于清晰、结构化的工具定义。仓库 Tool Definition 主题指出：工具定义描述 Agent 可调用的函数，包括名称、用途和接受的参数，通常用 JSON Schema 这类结构化格式表达；模型依据该定义判断工具何时相关、如何填写参数。定义得越清晰，模型选对工具、填对参数的概率越高。

一个典型的代码执行工具定义（JSON Schema 风格）如下：

{ "name": "execute_python", "description": "在隔离的 Python 运行时中执行一段 Python 代码，并返回标准输出与错误信息。适用于数学计算、数据处理、验证代码片段等场景。代码应使用 print() 输出结果。", "parameters": { "type": "object", "properties": { "code": { "type": "string", "description": "要执行的 Python 源码。注意：不应包含交互式输入请求，代码需自包含。" }, "timeout_seconds": { "type": "integer", "description": "执行超时时间（秒），防止代码陷入死循环。默认 10。", "default": 10 } }, "required": ["code"] } }

定义中值得注意的三个设计点：

1. 描述里写明使用约束：例如"用print()输出结果"、"代码需自包含"、"不要请求交互式输入"。REPL 工具是非交互执行的，模型若写出input()会导致进程挂起，因此必须在描述中提前约束。
2. 显式暴露超时参数：让超时成为工具接口的一部分，模型和宿主程序都能控制资源边界。
3. 描述中列举适用场景：明确"计算、数据处理、验证代码"，帮助模型判断何时该调用本工具，而不是自己硬算或只生成代码。

五、典型落地：最小可用的 Python REPL 工具

结合上文工具定义，下面给出一个教学性质的最小实现（核心模式，可直接放入 Agent 宿主程序中使用）：

import io import sys import contextlib import subprocess def execute_python(code: str, timeout_seconds: int = 10) -> str: """在隔离子进程中执行 Python 代码，返回 stdout 与 stderr。""" # 方案一：子进程隔离（推荐，避免与宿主进程共享状态） proc = subprocess.run( [sys.executable, "-c", code], capture_output=True, text=True, timeout=timeout_seconds, ) if proc.returncode != 0: return f"[执行失败，退出码 {proc.returncode}]\n{proc.stderr}" return proc.stdout def execute_python_inline(code: str) -> str: """方案二：进程内执行（仅用于理解原理，不建议直接用于生产）。""" stdout_buf = io.StringIO() try: with contextlib.redirect_stdout(stdout_buf): exec(code, {"__name__": "__main__"}) return stdout_buf.getvalue() except Exception as exc: # noqa: BLE001 return f"[执行异常] {type(exc).__name__}: {exc}"

5.1 为什么优先选子进程方案

进程内exec()方案虽然直观，却存在致命问题：被执行的代码能访问宿主进程的模块、全局变量甚至环境变量，一次__import__('os').system('...')就能逃逸出沙箱。因此生产实现应尽量采用独立进程/独立运行时执行，并通过 subprocess 捕获输出、限制超时。这正是 Tool sandboxing / Permissioning 主题强调的思路：把 Agent 关在"安全区"内，只允许它执行经批准的有限动作。

5.2 工程化增强清单

在最小实现之上，成熟的代码执行工具通常还要叠加以下能力：

• 超时与资源限制：对 CPU 时间、内存上限、输出字节数设限，防止失控代码耗尽宿主资源；
• 依赖白名单：预置pandas、numpy、requests等常用库，禁止未知模块导入；
• 网络与文件系统隔离：默认拒绝网络访问，仅允许读写白名单目录（可结合 File System Access 主题中"只允许 Agent 触碰正确文件、避免误伤系统"的安全要求）；
• 审计日志：记录每次执行的代码与结果，便于回溯和排查。

六、安全执行：沙箱与权限是前提

原文档将 REPL 工具定位为"让 Agent 测试并纠正自己的输出"，而这一能力同时意味着模型生成的任意代码都会在真实环境中运行——这天然是高风险操作。仓库 Tool sandboxing / Permissioning 主题给出了三条安全准则，恰好对应代码执行场景：

1. 最小权限（grant the smallest set of rights）：代码执行环境只授予完成任务所需的最小权限——只读文件系统、无网络、无敏感环境变量；
2. 持续监控（watch activity）：记录执行日志、捕获异常输出、监控资源消耗；
3. 越权即拦截（block anything outside the plan）：当 Agent 需要超出白名单的访问（如写特定文件、访问外部 API）时，必须显式请求新的许可，而不是静默放行。

落实到工程实践，常见的安全组合包括：

• Docker / 容器隔离：每个任务启动一次性容器，执行完毕后销毁，进程、文件系统、网络全部隔离；
• 受限解释器：在 Python 场景可选用受限执行环境或对 AST 做静态检查，拦截os.system、subprocess、eval等危险调用；
• 超时与并发限制：对单次执行和单任务总执行次数都设上限，防止 Agent 陷入"无限修正"的循环。

七、典型应用场景与工程建议

7.1 典型场景

• 数学与数值验证：积分、矩阵运算、统计检验等交给真实运行时，Agent 负责组织步骤与解读结果；
• 数据处理流水线：Agent 从数据源取数（见 API Requests），写脚本完成清洗、聚合、可视化，再汇报结论；
• 生成代码的自我验证：Agent 写完一段函数或脚本后，自动构造测试用例在 REPL 中运行，断言通过才交付（参见 Code generation 主题中"写测试"的能力维度）；
• 教学与解释：Agent 演示某段代码的执行过程，逐行解释输出，帮助学习者理解程序行为。

7.2 工程建议

总结

代码执行 / REPL 工具是 AI Agent 从"会写代码"迈向"会用代码思考"的关键一步。它把模型输出与真实运行时连接起来：Agent 生成代码 → 执行 → 观察结果 → 修正再执行，形成可自我验证的闭环，在计算、数据处理与代码校验场景中显著提升可靠性与实战价值。设计这样的工具时，清晰的工具定义、稳健的执行环境与严格的沙箱权限缺一不可——前者决定模型能否用对工具，后两者决定 Agent 能否在安全边界内放手去试错。

• 工具与 Agent 的关系：参见 What are Tools?
• 工具定义规范：参见 Tool Definition
• 循环与执行：参见 Agent Loop 与 Function Calling
• 安全边界：参见 Tool sandboxing / Permissioning

• 文档
• 教程
• 知识库