文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载导读在 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 GenerationAgent 依据自然语言需求产出可供人使用的源码是否运行、运行是否成功由开发者自行验证。参见仓库中的 Code generation 主题。代码执行Code Execution / REPLAgent 在对话过程中直接执行自己写出的代码读取 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 可以写出候选代码在 REPL 中运行它观察输出是否符合预期例如单元测试断言是否通过、边界用例结果是否正确若失败读取报错信息修正代码后再次运行。这正是 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] } }定义中值得注意的三个设计点描述里写明使用约束例如用print()输出结果、代码需自包含、不要请求交互式输入。REPL 工具是非交互执行的模型若写出input()会导致进程挂起因此必须在描述中提前约束。显式暴露超时参数让超时成为工具接口的一部分模型和宿主程序都能控制资源边界。描述中列举适用场景明确计算、数据处理、验证代码帮助模型判断何时该调用本工具而不是自己硬算或只生成代码。五、典型落地最小可用的 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_outputTrue, textTrue, timeouttimeout_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 主题给出了三条安全准则恰好对应代码执行场景最小权限grant the smallest set of rights代码执行环境只授予完成任务所需的最小权限——只读文件系统、无网络、无敏感环境变量持续监控watch activity记录执行日志、捕获异常输出、监控资源消耗越权即拦截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 工程建议关注点建议超时控制单次执行默认 5–10 秒超时任务级总执行次数设上限输出限制截断过长的 stdout/stderr如 4KB避免撑爆上下文工具定义在描述中明确约束print 输出、自包含代码提升模型调用成功率环境隔离容器化 只读文件系统 网络白名单详见沙箱主题结果回传返回 stdout 与 stderr 的原文报错信息是模型自我修正的关键信号审计全量记录代码与结果便于复现与安全审查总结代码执行 / REPL 工具是 AI Agent 从会写代码迈向会用代码思考的关键一步。它把模型输出与真实运行时连接起来Agent 生成代码 → 执行 → 观察结果 → 修正再执行形成可自我验证的闭环在计算、数据处理与代码校验场景中显著提升可靠性与实战价值。设计这样的工具时清晰的工具定义、稳健的执行环境与严格的沙箱权限缺一不可——前者决定模型能否用对工具后两者决定 Agent 能否在安全边界内放手去试错。工具与 Agent 的关系参见 What are Tools?工具定义规范参见 Tool Definition循环与执行参见 Agent Loop 与 Function Calling安全边界参见 Tool sandboxing / Permissioning赞分享文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载相关推荐LowCodeEngine代码生成器从Schema到可执行代码LowCodeEngine代码生成器从Schema到可执行代码 本文深入解析了LowCodeEngine代码生成器的核心原理与实现机制。系统通过Schema解前端低代码ADK Gemini代码执行工具让智能体编写并运行代码的完整教程ADK Gemini代码执行工具让智能体编写并运行代码的完整教程 ADKAgent Development Kit是一款开源的代码优先Python工具包文档AI Agent实战指南利用Rufus创建Windows 11安装U盘并绕过硬件限制的完整方案实战指南利用Rufus创建Windows 11安装U盘并绕过硬件限制的完整方案 Rufus是一款可靠的开源USB格式化工具专为创建可启动USB驱动器而设计。桌面应用开发工具上一篇如何在10分钟内为Honey Select 2游戏安装完整中文汉化与增强补丁下一篇VisualCppRedist AIO一站式解决Windows C运行库依赖困境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 AI Agent 代码执行与 REPL 工具：让 Agent 从“生成代码“进阶到“运行并验证代码“
文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载导读在 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 GenerationAgent 依据自然语言需求产出可供人使用的源码是否运行、运行是否成功由开发者自行验证。参见仓库中的 Code generation 主题。代码执行Code Execution / REPLAgent 在对话过程中直接执行自己写出的代码读取 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 可以写出候选代码在 REPL 中运行它观察输出是否符合预期例如单元测试断言是否通过、边界用例结果是否正确若失败读取报错信息修正代码后再次运行。这正是 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] } }定义中值得注意的三个设计点描述里写明使用约束例如用print()输出结果、代码需自包含、不要请求交互式输入。REPL 工具是非交互执行的模型若写出input()会导致进程挂起因此必须在描述中提前约束。显式暴露超时参数让超时成为工具接口的一部分模型和宿主程序都能控制资源边界。描述中列举适用场景明确计算、数据处理、验证代码帮助模型判断何时该调用本工具而不是自己硬算或只生成代码。五、典型落地最小可用的 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_outputTrue, textTrue, timeouttimeout_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 主题给出了三条安全准则恰好对应代码执行场景最小权限grant the smallest set of rights代码执行环境只授予完成任务所需的最小权限——只读文件系统、无网络、无敏感环境变量持续监控watch activity记录执行日志、捕获异常输出、监控资源消耗越权即拦截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 工程建议关注点建议超时控制单次执行默认 5–10 秒超时任务级总执行次数设上限输出限制截断过长的 stdout/stderr如 4KB避免撑爆上下文工具定义在描述中明确约束print 输出、自包含代码提升模型调用成功率环境隔离容器化 只读文件系统 网络白名单详见沙箱主题结果回传返回 stdout 与 stderr 的原文报错信息是模型自我修正的关键信号审计全量记录代码与结果便于复现与安全审查总结代码执行 / REPL 工具是 AI Agent 从会写代码迈向会用代码思考的关键一步。它把模型输出与真实运行时连接起来Agent 生成代码 → 执行 → 观察结果 → 修正再执行形成可自我验证的闭环在计算、数据处理与代码校验场景中显著提升可靠性与实战价值。设计这样的工具时清晰的工具定义、稳健的执行环境与严格的沙箱权限缺一不可——前者决定模型能否用对工具后两者决定 Agent 能否在安全边界内放手去试错。工具与 Agent 的关系参见 What are Tools?工具定义规范参见 Tool Definition循环与执行参见 Agent Loop 与 Function Calling安全边界参见 Tool sandboxing / Permissioning赞分享文档教程知识库【免费下载链接】developer-roadmapInteractive roadmaps, guides and other educational content to help developers grow in their careers.项目地址https://gitcode.com/GitHub_Trending/de/developer-roadmap点击查看免费下载相关推荐LowCodeEngine代码生成器从Schema到可执行代码LowCodeEngine代码生成器从Schema到可执行代码 本文深入解析了LowCodeEngine代码生成器的核心原理与实现机制。系统通过Schema解前端低代码ADK Gemini代码执行工具让智能体编写并运行代码的完整教程ADK Gemini代码执行工具让智能体编写并运行代码的完整教程 ADKAgent Development Kit是一款开源的代码优先Python工具包文档AI Agent实战指南利用Rufus创建Windows 11安装U盘并绕过硬件限制的完整方案实战指南利用Rufus创建Windows 11安装U盘并绕过硬件限制的完整方案 Rufus是一款可靠的开源USB格式化工具专为创建可启动USB驱动器而设计。桌面应用开发工具上一篇如何在10分钟内为Honey Select 2游戏安装完整中文汉化与增强补丁下一篇VisualCppRedist AIO一站式解决Windows C运行库依赖困境创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考