人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱【免费下载链接】smolagents smolagents: a barebones library for agents that think in code.项目地址https://gitcode.com/gh_mirrors/smo/smolagents点击查看免费下载smolagents 的核心设计是让大语言模型用代码编写动作的代码智能体Code Agent这意味着 LLM 生成的 Python 代码默认会在你的环境中运行。本指南聚焦这一特性带来的安全挑战与解决方案先深入剖析仓库中从零构建的LocalPythonExecutor本地沙箱解释器的实现原理与防护边界再逐步讲解 E2B、Blaxel、Modal、Docker 四种远程沙箱的配置与部署方式最后给出方案选型与生产级最佳实践。读完本文你将掌握如何在本地与远程两种模式下安全地运行 LLM 生成代码。为什么是代码智能体用代码而非 JSON 表达动作在智能体领域行业标准做法是让 LLM 输出包含工具名称和参数的 JSON作为动作工具调用。而多项研究如Executable Code Actions Elicit Better LLM Agents等表明让 LLM 直接编写代码来执行动作效果显著优于 JSON 格式的工具调用。为什么代码更好因为编程语言本身就是为表达计算机可以执行的动作而设计的。相比 JSON 片段代码具有四个难以替代的优势组合性Composability你能像定义 Python 函数一样在动作中嵌套其他动作或定义一组动作以便后续复用——JSON 则很难做到这一点对象管理Object management如何用 JSON 存储generate_image这类动作的输出代码可以直接引用内存中的对象通用性Generality代码天生就是为了表达任何计算机能做的事在 LLM 训练语料库中的表示海量高质量代码早已包含在 LLM 的训练语料中让其写代码等于直接利用了这一优势。正是基于这一理念smolagents 强调构建Python 智能体并把大量精力投入到构建安全的 Python 解释器上——这就是本指南的核心主题。安全威胁模型LLM 生成代码的风险从何而来默认情况下CodeAgent会在你的环境中运行 LLM 生成的代码这天然带有风险。恶意代码的执行可能通过以下几种途径发生普通 LLM 失误Plain LLM errorLLM 远非完美可能在尝试帮助你时无意间生成有害命令。这种风险概率较低但已观察到 LLM 尝试执行潜在危险代码的实例供应链攻击Supply chain attack运行不受信任或被篡改的 LLM可能使系统暴露于有害代码生成。使用知名模型和可信推理基础设施时风险极低但在理论上依然存在提示注入Prompt injectionagent 浏览网页时可能进入包含恶意指令的网站从而将攻击注入 agent 的记忆公共 agent 被利用Exploitation of publicly accessible agents暴露给公众的 agent 可能被恶意行为者构造对抗性输入加以滥用利用其执行能力造成意外后果。一旦恶意代码被执行无论出于意外还是蓄意都可能破坏文件系统、滥用本地或云端资源、消耗 API 服务甚至危及网络安全。需要清醒认识到在智能体自主性agency的光谱上代码智能体给予 LLM 的自主权远高于其他低自主性方案这必然与更高的风险相伴而行。第一道防线本地沙箱解释器 LocalPythonExecutor 的防护原理为了加筑第一层安全smolagents 中的代码执行不是由普通 Python 解释器完成的而是从零重建了一个更安全的LocalPythonExecutor实现位于 src/smolagents/local_python_executor.py。它的工作方式很特别先加载代码的抽象语法树AST然后**逐操作operation by operation**解释执行并始终遵守如下规则导入白名单机制默认禁止一切导入除非该模块被用户显式加入授权列表子模块访问限制默认禁止访问子模块每个子模块也必须显式授权或者可以传numpy.*这类通配符来同时放行numpy及其全部子包如numpy.random、numpy.a.b。注意一些看似无害的包也可能暴露危险子模块例如random._os操作次数上限限制基本操作的总计数防止无限循环与资源膨胀未预定义操作即报错任何未在自定义解释器中显式定义的操作都会抛出异常。白名单模块与计数阈值的源码实现从源码可以确认这些防护的具体数值与机制默认授权模块BASE_BUILTIN_MODULES定义在 src/smolagents/utils.py仅包含 11 个安全的基础标准库collections、datetime、itertools、math、queue、random、re、stat、statistics、time、unicodedataLocalPythonExecutor.__init__会把用户传入的additional_authorized_imports与上述默认列表取并集作为authorized_imports并调用_check_authorized_imports_are_installed()提前校验支持*与os.*这类通配写法若本机未安装会直接抛出InterpreterError解释器内置三项硬性阈值单次代码执行最大操作数MAX_OPERATIONS 10000000、while 循环最大迭代次数MAX_WHILE_ITERATIONS 1000000、执行超时上限MAX_EXECUTION_TIME_SECONDS 30秒见 src/smolagents/local_python_executor.py。evaluate_ast每处理一个 AST 节点都会递增_operations_count计数器并在超过阈值时中断evaluate_attribute对__dunder__属性访问直接报Forbidden access to dunder attributeevaluate_import则通过check_import_authorized逐级比对导入路径。实战验证四个防护示例你可以直接实例化LocalPythonExecutor亲自验证这些防护与原文档一致的可运行示例from smolagents.local_python_executor import LocalPythonExecutor # 设置自定义执行器授权包 numpy custom_executor LocalPythonExecutor([numpy]) # 用于美化打印错误的工具函数 def run_capture_exception(command: str): try: custom_executor(command) except Exception as e: print(ERROR:\n, e) # 1. 未定义的命令直接不可用 harmful_command !echo Bad command run_capture_exception(harmful_command) # ERROR: invalid syntax (unknown, line 1) # 2. 除非显式加入 additional_authorized_imports否则 os 不会被导入 harmful_command import os; exit_code os.system(echo Bad command) run_capture_exception(harmful_command) # ERROR: Code execution failed at line import os due to: InterpreterError: Import of os is not allowed. # Authorized imports are: [statistics, numpy, itertools, time, queue, collections, math, random, re, datetime, stat, unicodedata] # 3. 即使包已授权其潜在危险的子模块同样被拦截 harmful_command import random; random._os.system(echo Bad command) run_capture_exception(harmful_command) # ERROR: Code execution failed at line random._os.system(echo Bad command) due to: # InterpreterError: Forbidden access to module: os # 4. 无限循环会在 N 次操作后被强制中断 harmful_command while True: pass run_capture_exception(harmful_command) # ERROR: Code execution failed at line while True: pass due to: # InterpreterError: Maximum number of 1000000 iterations in While loop exceeded必须认清的边界本地沙箱并非万无一失这些防护使解释器比标准 Python 解释器安全得多官方已在多种用例中使用且从未观察到对环境造成损害。但请务必注意任何本地 Python 沙箱都不可能做到完全安全。例如如果你授权了像Pillow这样处理图像的无害包LLM 可能生成创建数千张大图填满硬盘的代码其他高级逃逸技术还可能利用授权包内部的深层漏洞。使用可信推理提供商的知名 LLM 时恶意攻击风险很低但并非为零。对于高安全要求的应用或使用可信度较低的模型时应转向下一节的远程沙箱方案。两种沙箱思路仅隔离代码片段还是隔离整个 agent 系统远程沙箱化有两种主要路径安全属性与能力各不相同仅将代码片段放入沙箱Approach 1只把 agent 生成的 Python 代码片段放进沙箱执行其余 agent 系统仍留在本地环境。通过executor_typeblaxel、executor_typee2b、executor_typemodal或executor_typedocker即可简单启用。它的局限是暂不支持多 agentmanaged agents且仍需要在本地环境与沙箱之间传递状态数据将整个 agent 系统放入沙箱Approach 2把 agent、模型、工具整体运行在沙箱环境中。隔离更彻底但需要更多手工配置且可能要把敏感凭据如 API key传入沙箱。从源码看executor_type是CodeAgent初始化时的一个参数类型为Literal[local, blaxel, e2b, modal, docker]默认local见 src/smolagents/agents.py。agents.py会校验取值local走LocalPythonExecutor其余取值路由到 src/smolagents/remote_executors.py 中对应的远程执行器类传入不支持的值会抛出ValueError: Unsupported executor type。所有远程执行器都继承自RemotePythonExecutor基类共享additional_imports、日志与allow_pickle参数——其中allow_pickle默认False以保证只使用安全的 JSON 序列化因为 pickle 反序列化可能执行任意代码。E2B 沙箱隔离容器中的远程代码执行为获得最大程度的安全性可以使用 smolagents 与 E2B 的集成在隔离容器中运行代码使代码完全无法影响本地环境。安装与准备注册 E2B 账户获取 API Key将E2B_API_KEY配置到环境变量可使用python-dotenv管理安装依赖包pip install smolagents[e2b]快速开始只需在初始化CodeAgent时传递executor_typee2b。注意应把所用工具的全部依赖项加入additional_authorized_imports执行器会在沙箱内自动安装它们from smolagents import CodeAgent, VisitWebpageTool, InferenceClientModel agent CodeAgent( tools[VisitWebpageTool()], modelInferenceClientModel(), additional_authorized_imports[requests, markdownify], executor_typee2b, ) agent.run(What was Abraham Lincolns preferred pet?)更简洁的推荐写法是配合上下文管理器使用确保任务结束后沙箱立即被清理from smolagents import InferenceClientModel, CodeAgent with CodeAgent(modelInferenceClientModel(), tools[], executor_typee2b) as agent: agent.run(Can you give me the 100th Fibonacci number?)使用with语句上下文管理器可保证 E2B 沙箱在 agent 完成任务后立即被清理也可以手动调用 agent 的cleanup()方法。工作原理与多 agent 限制从源码src/smolagents/remote_executors.py可以看到E2BExecutor在初始化时通过e2b_code_interpreter.Sandbox创建沙箱run_code_raise_errors调用sandbox.run_code(code)执行代码随后解析执行日志与结果支持识别FinalAnswerException判定最终答案并处理 jpeg/png 图片等特殊输出格式cleanup()则调用sandbox.kill()销毁资源。整个过程中模型调用仍发生在本地只有生成的代码被发送到沙箱执行最后只把输出返回本地。关于多 agent 的现状由于任何对被管理 agent 的调用都需要模型请求而沙箱方案不会向远程沙箱转移密钥模型调用会缺少凭据。因此该方案目前暂不兼容多 agent 场景官方正在推进解决。若必须在 E2B 中运行多 agent需要把整个 agent 应用完全放进 E2B 沙箱内运行通过e2b_code_interpreter.Sandbox创建沙箱、在沙箱内pip install smolagents、并通过sandbox.run_code在传递了HF_TOKEN环境变量的沙箱里执行完整的多 agent 代码。Blaxel 沙箱毫秒级启动的远程执行Blaxel 提供从休眠状态快速启动的虚拟机启动时间低于 25ms闲置后自动缩容归零且保持内存状态非常适合需要快速、安全代码执行的 agent 应用。安装与快速开始pip install smolagents[blaxel]from smolagents import InferenceClientModel, CodeAgent with CodeAgent(modelInferenceClientModel(), tools[], executor_typeblaxel) as agent: agent.run(Can you give me the 100th Fibonacci number?)工作方式与 E2B 类似每次agent.run()开始时把 agent 状态发送到服务端模型在本地调用生成的代码发送到沙箱执行仅返回输出。同样建议用with上下文管理器或手动cleanup()清理沙箱。BlaxelExecutorsrc/smolagents/remote_executors.py默认配置为 4096MB 内存、blaxel/jupyter-notebook镜像并支持通过region、ttl等参数定制部署区域与存活时间。Modal 沙箱云端函数平台的沙箱执行安装与快速开始pip install smolagents[modal]from smolagents import InferenceClientModel, CodeAgent with CodeAgent(modelInferenceClientModel(), tools[], executor_typemodal) as agent: agent.run(What is the 42th Fibonacci number?)ModalExecutorsrc/smolagents/remote_executors.py会在 Modal 沙箱中部署jupyter_kernel_gateway与ipykernel并通过加密端口与 WebSocket 通道执行代码。agent 状态与InferenceClientModel生成的代码会被发送到 Modal 沙箱中安全执行。同样推荐上下文管理器或cleanup()清理。Docker 沙箱自建容器的完全掌控如果你希望完全掌控隔离环境Docker 是最灵活的自托管选择。安装与快速开始先在系统上安装 Docker安装依赖pip install smolagents[docker]与前面一致在初始化时传入executor_typedockerfrom smolagents import InferenceClientModel, CodeAgent with CodeAgent(modelInferenceClientModel(), tools[], executor_typedocker) as agent: agent.run(Can you give me the 100th Fibonacci number?)从源码看DockerExecutorsrc/smolagents/remote_executors.py默认在127.0.0.1:8888上运行基于jupyter_kernel_gateway的 Jupyter 内核网关容器通过 WebSocket 通道接收代码并回传输出它支持image_name、build_new_image、container_run_kwargs、dockerfile_content等参数定制镜像与运行行为。使用with上下文管理器时容器会在任务结束后被停止并移除。Docker 高级用法自建沙箱运行多 agent若要在 Docker 中运行多 agent 系统需要自行在沙箱内配置自定义解释器。首先准备一个精简且以低权限运行的 DockerfileFROM python:3.10-bullseye # 安装构建依赖 RUN apt-get update \ apt-get install -y --no-install-recommends \ build-essential \ python3-dev \ pip install --no-cache-dir --upgrade pip \ pip install --no-cache-dir smolagents \ apt-get clean \ rm -rf /var/lib/apt/lists/* # 设置工作目录 WORKDIR /app # 以受限权限运行 USER nobody # 默认命令 CMD [python, -c, print(Container ready)]然后创建沙箱管理器负责构建镜像、创建带安全约束的容器并执行代码import docker import os from typing import Optional class DockerSandbox: def __init__(self): self.client docker.from_env() self.container None def create_container(self): try: image, build_logs self.client.images.build( path., tagagent-sandbox, rmTrue, forcermTrue, buildargs{}, # decodeTrue ) except docker.errors.BuildError as e: print(Build error logs:) for log in e.build_log: if stream in log: print(log[stream].strip()) raise # 创建带安全约束与日志的容器 self.container self.client.containers.run( agent-sandbox, commandtail -f /dev/null, # 保持容器运行 detachTrue, ttyTrue, mem_limit512m, cpu_quota50000, pids_limit100, security_opt[no-new-privileges], cap_drop[ALL], environment{ HF_TOKEN: os.getenv(HF_TOKEN) }, ) def run_code(self, code: str) - Optional[str]: if not self.container: self.create_container() # 在容器中执行代码 exec_result self.container.exec_run( cmd[python, -c, code], usernobody ) # 收集全部输出 return exec_result.output.decode() if exec_result.output else None def cleanup(self): if self.container: try: self.container.stop() except docker.errors.NotFound: # 容器已被移除这是预期情况 pass except Exception as e: print(fError during cleanup: {e}) finally: self.container None # 清除引用 # 使用示例 sandbox DockerSandbox() try: # 定义你的 agent 代码 agent_code import os from smolagents import CodeAgent, InferenceClientModel # 初始化 agent agent CodeAgent( modelInferenceClientModel(tokenos.getenv(HF_TOKEN), providertogether), tools[] ) # 运行 agent response agent.run(Whats the 20th Fibonacci number?) print(response) # 在沙箱中运行代码 output sandbox.run_code(agent_code) print(output) finally: sandbox.cleanup()注意这里的资源与权限约束内存上限 512MB、CPU 配额、进程数限制、no-new-privileges安全选项、丢弃全部 Linux capabilities并以nobody用户执行——这些都是生产级容器隔离的关键实践。沙箱使用最佳实践以下关键实践适用于 Blaxel、E2B、Modal 与 Docker 沙箱资源管理设置内存与 CPU 上限实现执行超时监控资源使用安全以最小权限运行禁用不必要的网络访问密钥一律通过环境变量传递不要硬编码进代码或镜像环境保持依赖最小化固定包版本若使用基础镜像定期更新清理始终确保资源被正确清理尤其是 Docker 容器避免悬空容器持续占用资源。仓库中提供了完整可运行的多执行器示例 examples/sandboxed_execution.py其中用同一个任务一只全速奔跑的猎豹穿过巴黎艺术桥需要多少秒分别演示了executor_typeblaxel、docker、e2b、modal四种配置是快速上手的绝佳参考。两种安全方案的对比与选型方案 1仅将代码片段放入沙箱优点通过executor_typeblaxel/e2b/modal/docker一个参数即可启用配置简单无需向沙箱转移 API key对本地环境有更好的保护Blaxel 的休眠技术可提供低于 25ms 的快速启动缺点暂不支持多 agent被管理的 agent仍需在本地环境与沙箱之间传递状态仅覆盖特定代码执行环节。方案 2将整个 agent 系统放入沙箱优点支持多 agent对整个 agent 系统实现完全隔离对复杂 agent 架构更灵活缺点需要更多手工配置可能需要向沙箱传递敏感 API key由于操作更复杂潜在延迟更高。选型建议对于大多数架构相对简单的应用方案 1 在安全性与易用性之间取得了良好平衡对于需要完全隔离的复杂多 agent 系统方案 2 虽然配置更繁琐但能提供更强的安全保证。同时务必牢记任何方案都无法做到 100% 安全——从本地的LocalPythonExecutor白名单解释器到远程的容器与虚拟机沙箱每一层防护都在提高攻击成本选择时应综合评估你的威胁模型、模型可信度与部署复杂度。相关参考如需进一步了解代码智能体的设计理念可阅读 agent 介绍 与 smolagents 导览多 agent 的编排细节可参考 多智能体示例。赞分享人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱【免费下载链接】smolagents smolagents: a barebones library for agents that think in code.项目地址https://gitcode.com/gh_mirrors/smo/smolagents点击查看免费下载相关推荐smolagents Python 代码执行器完全指南从本地安全解释器到远程沙箱Blaxel / E2B / Modal / Dockersmolagents Python 代码执行器完全指南从本地安全解释器到远程沙箱Blaxel / E2B / Modal / Docker smolage人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱smolagents 安全代码执行实战从 LocalPythonExecutor 本地沙箱到 E2B、Blaxel、Modal 与 Docker 远程隔离smolagents 安全代码执行实战从 LocalPythonExecutor 本地沙箱到 E2B、Blaxel、Modal 与 Docker 远程隔离 s人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱smolagents 安全代码执行完全指南从本地 AST 沙箱到 E2B、Modal、Blaxel 与 Docker 远程隔离smolagents 安全代码执行完全指南从本地 AST 沙箱到 E2B、Modal、Blaxel 与 Docker 远程隔离 smolagents 的核心设人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考