CAMEL Interpreters 代码执行引擎完全指南从进程内安全执行到云沙箱【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camelCAMEL 的 Interpreters 模块为 Agent 提供了一整套代码执行能力让 LLM 生成的代码可以在从进程内、子进程、Docker 容器到云端沙箱的多种环境中安全、灵活地运行。本文以 docs/key_modules/interpreters.md 为主线结合 camel/interpreters 下的真实源码与 test/interpreters 测试用例逐一剖析六大解释器的定位、核心参数、执行原理与选型策略帮助你为 Agent 任务选择最合适的代码执行环境。Interpreters 是什么Agent 的手脚在 CAMEL 多智能体框架中模型负责思考而 Interpreters 负责执行。所谓 Interpreter就是让 Agent 能够动态运行代码片段的执行器它支撑起代码评估、单元测试、任务自动化以及执行→观察结果→修正代码的强化反馈闭环即 ReAct 式循环中的关键一环。选择解释器时核心权衡维度有三个信任程度代码是否可信、隔离级别执行失败或恶意代码对宿主机的影响范围、支持的语言。CAMEL 通过统一的抽象接口屏蔽了这些差异让上层 Agent 可以用完全一致的run(code, code_type)调用方式切换任意执行环境。所有解释器都继承自 camel/interpreters/base.py 中的BaseInterpreter抽象基类该基类定义了四个必须实现的核心方法run(code, code_type) - str执行代码并返回结果字符串失败时应返回足够定位问题的诊断信息并可能抛出InterpreterErrorsupported_code_types() - List[str]声明该解释器支持的语言类型update_action_space(action_space)更新 Python 解释器的动作空间仅进程内解释器有效execute_command(command)执行 shell 命令返回 stdout/stderr。InterpreterError定义在 camel/interpreters/interpreter_error.py它表示可以通过修改或重新生成代码来解决的错误是 Agent 代码修复循环能够持续迭代的语义基础。六大解释器总览与选型速查从 camel/interpreters/init.py 可以确认模块对外暴露了 8 个符号BaseInterpreter、InterpreterError、InternalPythonInterpreter、SubprocessInterpreter、DockerInterpreter、JupyterKernelInterpreter、E2BInterpreter和MicrosandboxInterpreter。其中六大解释器的定位如下解释器执行环境隔离级别支持语言最佳场景InternalPythonInterpreterAgent 进程内AST 解释执行弱依赖白名单机制Python可信代码、快速求值SubprocessInterpreter独立子进程 临时文件中进程隔离Python、Bash、RShell 命令、脚本、进程隔离DockerInterpreterDocker 容器强容器沙箱Python、Bash、R、Node.js不可信代码、依赖隔离、安全实验JupyterKernelInterpreterJupyter/IPython Kernel中独立内核进程Python、Bash多步推理、持久变量、富输出E2BInterpreterE2B 云端沙箱强托管云沙箱Python、Bash、Java、JavaScript、R托管可扩展任务、免本地环境MicrosandboxInterpreter自托管 microsandbox 服务强独立沙箱Python、JavaScript/Node、Bash自托管安全执行、私有化部署InternalPythonInterpreter进程内安全执行InternalPythonInterpreter是 CAMEL 针对LLM 生成代码专门定制的 Python 解释器它不是简单地调用eval/exec而是先通过 Python 的ast模块把代码解析成语法树再逐节点手工解释执行见 camel/interpreters/internal_python_interpreter.py 的_execute_ast方法从而精确控制哪些语法、哪些函数可以被执行。它源自 HuggingFace transformers 的python_interpreter.py实现并在此基础上增加了 import 白名单、for 语句、若干二元/一元运算符、模糊变量匹配等能力。安全机制一action_space动作空间解释器只能执行action_space中列出的函数或这些对象上的成员函数。这模拟了Agent 可执行动作的边界。构造函数参数如下action_space动作名到函数/对象的映射默认空字典allow_builtins为True时自动注入一批安全内建函数print、len、str、int、float、min、max、sum、sorted、range、isinstance、getattr等 35 个左右默认True见 internal_python_interpreter.pyimport_white_listimport 白名单只有在此列表中的模块及其子模块/函数才可导入用.分隔层级unsafe_mode为True时直接走eval()/exec()不做任何安全检查默认Falserequire_confirm执行本地 shell 命令前是否交互确认默认Trueraise_error执行失败时是否抛出InterpreterError默认False为False时返回 traceback 字符串。安全机制二import 白名单与模糊匹配_validate_import方法internal_python_interpreter.py会逐级校验torch.nn.functional这类全名只要路径中的任意一级命中白名单即放行否则拒绝导入。fuzz_state是它的独门特性——当代码引用的变量名与外部变量不完全一致时解释器会用difflib.get_close_matches做模糊匹配。例如fuzz_state中存了变量image生成的代码写input_image也能访问到它见 internal_python_interpreter.py 与测试 test/interpreters/test_python_interpreter.py。状态保持解释器在执行后保存状态state保存确定变量fuzz_state保存模糊变量。execute(code, state, fuzz_state, keep_state)中keep_stateTrue时跨调用保留变量默认False时执行结束即清空。测试test_keep_state0test_python_interpreter.py演示了执行a 42后保留状态第二次用b a能取到 42若第二次keep_stateFalse第三次引用b就会报 The variablebis not defined.。官方文档示例from camel.interpreters import InternalPythonInterpreter # Initialize the interpreter interpreter InternalPythonInterpreter() # Code to execute (should evaluate to a string) python_code Hello from InternalPythonInterpreter! # Run code result_str interpreter.run(codepython_code, code_typepython) print(fResult: {result_str})注意文档中的提示严格安全模式下只允许表达式expression而不允许普通语句statement且要获得输出代码应求值为字符串。安全模式支持的语法由_execute_ast决定赋值、增强赋值、二元/一元运算、比较、函数调用、if、for、import、字典/列表/元组、下标访问、f-string 等均可执行其余语法会抛出InterpreterError见 internal_python_interpreter.py。SubprocessInterpreter子进程隔离执行SubprocessInterpreter把代码写入临时文件再在独立子进程中调用系统解释器执行进程崩溃或资源占用不会拖垮 Agent 主进程。它的核心执行流程是run()→ 临时文件 →run_file()→subprocess.Popen捕获 stdout/stderr → 清理临时文件见 camel/interpreters/subprocess_interpreter.py。参数与语言支持require_confirm执行前是否询问确认默认Trueprint_stdout是否打印标准输出默认Falseprint_stderr是否打印标准错误默认Trueexecution_timeout执行超时秒数默认60 秒超时后进程会被kill()并终止见 subprocess_interpreter.py。从_CODE_TYPE_MAPPING与_CODE_EXTENSION_MAPPINGsubprocess_interpreter.py可以看到它支持Python、Bash、R三种语言且python/py3/python3/py、shell/bash/sh、r/R会被归一化到同一执行通道。几个值得一提的实现细节Python 代码执行前会先用ast解析把文件末尾裸表达式如1 2自动包装成print(repr(...))模拟 REPL 的显示行为若解析失败则回退为直接调用python filesubprocess_interpreter.py所有子进程调用统一使用shellFalse避免 shell 注入风险execute_command除外它需要shellTrue执行任意命令执行前用which/where检查目标命令python/bash/Rscript是否存在于 PATH缺失时抛出InterpreterErrorsubprocess_interpreter.pyupdate_action_space不被支持调用会直接抛RuntimeError。官方文档示例from camel.interpreters import SubprocessInterpreter interpreter SubprocessInterpreter() shell_command echo Hello from SubprocessInterpreter! result_str interpreter.run(codeshell_command, code_typebash) print(fResult: {result_str.strip()})DockerInterpreter容器级完全沙箱当代码不可信或需要任意第三方依赖时Docker 是 CAMEL 的推荐方案。DockerInterpreter在 Docker 容器中运行代码宿主机与容器完全隔离代码对宿主系统零影响。工作原理首次使用时检查 Docker daemon 是否运行is_docker_running()并检查镜像camel-interpreter:latest是否存在不存在则用 camel/interpreters/docker/Dockerfile 现场构建以detachTrue方式启动一个随机命名的常驻容器tail -f /dev/null保持存活代码通过内存中的 tar 包用container.put_archive()拷入容器/tmp通过container.exec_run()在容器内执行对应语言的解释器命令demuxTrue分离 stdout/stderr解释器对象被销毁__del__或显式调用cleanup()时停止并删除容器camel/interpreters/docker_interpreter.py。该镜像基于ubuntu:24.04预装了 Python 3.10venv uv、R、Node.js 22、Poetry并创建了非 root 的devuser用户运行代码进一步降低提权风险见 Dockerfile。语言支持与参数Docker 解释器支持Python、Bash、R、Node.js含 JS/TS是语言覆盖最广的本地沙箱docker_interpreter.py。构造函数参数为require_confirm默认True、print_stdout默认False、print_stderr默认True并依赖dockerPython 包由dependencies_required(docker)装饰器强制检查。官方文档示例from camel.interpreters import DockerInterpreter interpreter DockerInterpreter() python_code_in_docker print(Hello from DockerInterpreter!) result_str interpreter.run(codepython_code_in_docker, code_typepython) print(fResult: {result_str.strip()})前提条件本机必须安装并启动 Docker且当前用户具备 Docker 权限。如果 Docker daemon 未运行初始化会抛出 Docker daemon is not running. Please install/start docker and try again. 的InterpreterError。JupyterKernelInterpreter有状态交互执行对于多步推理、需要跨单元格保留变量、期望富输出图表、图片的场景JupyterKernelInterpreter是最佳选择。它在本地启动一个真正的 Jupyter Kerneljupyter_clientipykernel通过消息协议与内核通信因此天然具备持久会话状态。参数与行为require_confirm、print_stdout、print_stderr与子进程解释器一致run()内部通过client.execute(code)提交代码再循环读取get_iopub_msg()消息直到内核进入idle状态超时 30 秒见 camel/interpreters/ipython_interpreter.pyerror消息 → 拼接 tracebackstream消息 → 追加 stdout 文本execute_result/display_data→ 追加text/plain若数据中包含image/png则以 base64 内嵌 Markdown 图片形式返回——这就是富输出的来源输出会经过_clean_ipython_output()过滤 ANSI 转义序列code_typebash时自动包装为%%bash魔法命令execute_command()则用!command形式执行 shell会话状态跨run()调用保留文档建议在需要时通过重建解释器对象来重置会话避免跨任务的状态串扰。官方文档示例from camel.interpreters import JupyterKernelInterpreter interpreter JupyterKernelInterpreter( require_confirmFalse, print_stdoutTrue, print_stderrTrue ) python_code_in_jupyter_kernel print(Hello from JupyterKernelInterpreter!) result interpreter.run(codepython_code_in_jupyter_kernel, code_typepython) print(result)E2BInterpreter 与 MicrosandboxInterpreter云端与自托管沙箱E2BInterpreter托管云沙箱E2BInterpreter将代码提交到 E2B 的托管云端沙箱执行本地零配置、天然可扩展适合不可信或计算密集的任务。使用前需要安装依赖e2b_code_interpreter设置环境变量E2B_API_KEY必需可选E2B_DOMAIN指定自建端点见 camel/interpreters/e2b_interpreter.py。从_CODE_TYPE_MAPPINGe2b_interpreter.py可见它支持Python、Bash、Java、JavaScript、R。执行结果会智能提取文本输出、stdout/stderr 日志以及结果对象的 PNG/JPEG/SVG/HTML 富表示_repr_png_()等统统以 Markdown 图片或 HTML 形式返回给 Agente2b_interpreter.py。execute_command()委托给self._sandbox.commands.run()可用于在沙箱内安装依赖如pip install numpy。对象销毁时沙箱会被kill()回收。MicrosandboxInterpreter自托管安全沙箱MicrosandboxInterpreter面向需要私有化、自托管安全执行环境的用户连接自部署的 microsandbox 服务。支持PythonPythonSandbox、JavaScript/Node.jsNodeSandbox、Bashshell 命令三类执行通道camel/interpreters/microsandbox_interpreter.py。配置参数与环境变量server_urlmicrosandbox 服务地址默认读取MSB_SERVER_URL兜底http://127.0.0.1:5555api_key认证密钥默认读取MSB_API_KEYnamespace沙箱命名空间默认defaultsandbox_name沙箱实例名不传由 SDK 随机生成timeout单次执行超时秒数默认30 秒。参数优先级遵循用户参数 环境变量 默认值的 SDK 约定见 microsandbox_interpreter.py。每次执行通过async with PythonSandbox.create(...)创建独立沙箱、执行完毕后自动释放天然隔离。execute_command()可用于pip install numpy、npm install express、ls -la /tmp等依赖管理与系统管理任务。最佳实践与故障排查选型建议InternalPythonInterpreter仅用于可信、简单的 Python 代码——它是唯一支持action_space细粒度控制执行边界的解释器Subprocess / Docker需要进程/容器隔离或依赖管理时优先考虑Docker任何不可信代码、或需要额外第三方库时首选容器沙箱E2B追求可扩展、托管、免本地环境风险的云端执行JupyterKernelInterpreter交互式多步逻辑、需要持久会话状态与富输出的场景若 Agent 会动态拼接代码执行务必对用户输入进行校验与消毒这是文档反复强调的安全底线。常见问题Docker 不工作确认 Docker daemon 已启动、当前用户有权限通常需加入docker用户组、镜像camel-interpreter:latest能正常构建E2B 无响应检查E2B_API_KEY是否有效、账户额度是否充足、自定义E2B_DOMAIN是否与 SDK 兼容长任务优先用SubprocessInterpreterexecution_timeout默认 60 秒或DockerInterpreter配合超时控制避免进程挂死Jupyter Kernel 侧也有 30 秒的内置超时会话污染Jupyter/IPython 解释器会保留状态跨任务前记得重建解释器实例以重置会话防止上一次任务的变量干扰本次执行依赖缺失检查目标命令/解释器python、bash、Rscript、node是否在 PATH 中SubprocessInterpreter会据此抛出明确的错误提示。总结CAMEL 的 Interpreters 模块用一个run(code, code_type)统一接口覆盖了从进程内安全 AST 执行到子进程隔离再到容器与云沙箱完全隔离的完整安全梯度。实践中的核心思路是可信代码用 InternalPythonInterpreter 追求速度不可信代码用 Docker/E2B/Microsandbox 追求隔离需要状态与富输出时交给 JupyterKernelInterpreter。这套设计让 Agent 在执行代码 → 观察结果 → 修正再执行的反馈闭环中既能保证运行效率又能守住系统安全的底线。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考