ADK-Python E2B 环境实战在远程沙箱中安全运行数据分析 Agent【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python本指南基于官方示例contributing/samples/environment_and_skills/e2b_environment/讲解如何用 ADK-Python 的E2BEnvironment与EnvironmentToolset构建一个在 E2B 远程沙箱中运行的数据分析 Agent它能在隔离环境里下载公共数据集、按需安装pandas、编写并运行分析脚本全程不触碰宿主机器。读完本文你将掌握 E2B 环境的接入方式、沙箱生命周期与 TTL 机制、EnvironmentToolset的工具集构成以及如何复用会话内的沙箱状态完成多轮数据分析任务。示例概述让 Agent 的代码在沙箱里运行示例是一个小型数据分析 Agentdata_analysis_agent它把EnvironmentToolset绑定到一个E2BEnvironment上。与在本地执行命令不同E2BEnvironment的所有命令与文件操作都发生在一个带公网访问能力的隔离远程沙箱中Agent 收到问题后下载一个公共数据集默认是托管在 Google Cloud Storage 上的世界人口/人口统计学数据集在沙箱内按需安装依赖例如pip install pandas编写一段简短的分析脚本并运行把计算结果含具体数字报告给用户。整个过程完全不触及用户本机因此非常适合安全运行模型生成的代码并保持宿主环境干净。沙箱还带有一个有界存活时间timeout单位为秒来控制额度消耗。从源码看这个能力建立在 ADK 的“环境抽象”之上BaseEnvironment 定义了统一的异步接口initialize()/close()/execute()/read_file()/write_file()E2BEnvironment 是该接口的一个云端实现而EnvironmentToolset则把这些能力包装成可供 LLM 调用的工具。前置条件安装带e2bextra 的 ADK 包pip install google-adk[e2b]如果未安装e2b依赖就使用E2BEnvironment源码 会在创建沙箱时抛出ImportError并提示上述安装命令。设置 E2B API Key可在 https://e2b.dev 获取export E2B_API_KEYyour-api-keyE2BEnvironment的api_key参数默认为None此时会读取E2B_API_KEY环境变量见 构造参数。示例输入与预期输出官方示例提供了三个可验证的输入用于演示沙箱的完整能力输入 1首次会话全流程演示Download the world demographics dataset and tell me which country has the largest population.Agent 会下载数据集、安装pandas、过滤到国家级country-level行并求最大值。预期结果中国CN约 14.4 亿略高于印度IN的约 13.8 亿。输入 2多轮会话复用沙箱状态For the United States, what is the urban vs rural population split?这是上一轮之后的追问。由于沙箱在会话期间持续存在Agent 直接复用已下载的 CSV 与已安装的pandas只需再写一段新脚本运行。预期结果美国城市约 2.707 亿 vs 乡村约 5760 万总人口约 3.31 亿。这正是沙箱“跨轮持久”特性的价值E2BEnvironment在initialize()时创建沙箱、close()时销毁会话内多个 LLM 调用共享同一个工作区见 生命周期实现。输入 3自定义数据集 URLUsing https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv, how many US states are listed?演示如何把 Agent 指向用户自己的数据集 URL 而非默认数据集。架构图数据流上用户的提问进入 AgentAgent 通过EnvironmentToolset在 E2B 沙箱内执行下载、安装、运行等操作沙箱把命令输出回传给 AgentAgent 汇总后作答。环境接入E2BEnvironment EnvironmentToolset示例中的 Agent 是一个独立的Agent没有 workflow 图仅挂载一个EnvironmentToolset其environment为E2BEnvironmentfrom google.adk.integrations.e2b import E2BEnvironment from google.adk.tools.environment import EnvironmentToolset EnvironmentToolset( environmentE2BEnvironment(imagebase, timeout300), )两个核心参数image选择 E2B 模板template默认是公开的base模板对所有用户可用源码中默认值为base见 常量定义。timeout沙箱存活时间的上限秒用于控制额度消耗每次操作都会重置 TTL见下文“TTL 与 keepalive”。默认值为300秒。此外E2BEnvironment还支持两个可选参数api_key显式指定 E2B API Key为None时回退到E2B_API_KEY环境变量env_vars注入到沙箱内部的环境变量字典dict[str, str]。这些参数最终在 _create_sandbox 中透传给AsyncSandbox.create(template..., timeout..., envs..., api_key...)。示例的完整 Agent 定义见 agent.py其系统指令明确约束了工作流程用curl -O/wget下载数据、按需pip install、写脚本、运行并汇报数字遇到命令失败要读错误、修脚本、重试。默认数据集地址为https://storage.googleapis.com/covid19-open-data/v3/demographics.csv。沙箱 TTL 与 keepalive过期自动重建timeout的语义值得单独说明它并不是单条命令的执行超时而是沙箱整体的存活期限每次执行操作前_ensure_sandbox会先检查沙箱是否仍在运行若仍在运行则调用set_timeout(self._timeout)执行keepalive把 TTL 重置为完整时长——因此活跃使用的沙箱永远不会在任务中途过期若已因真正空闲而过期则记录一条警告日志并透明地重建一个全新沙箱继续执行本次操作。需要特别注意的是重建后工作区状态已安装的包和文件会丢失。这也是为什么示例输入 2 强调“沙箱在会话中持久因此可以复用已下载的 CSV 与已安装的 pandas”——一旦沙箱被重建这些状态就需要重新准备。initialize()本身是幂等的重复调用不会重复建沙箱close()会调用sandbox.kill()释放沙箱同样幂等——这些行为都有对应的单元测试覆盖见 test_e2b_environment.py。执行语义非零退出码是正常结果execute()的返回值是ExecutionResultexit_code/stdout/stderr/timed_out源码对异常做了语义化处理见 execute 实现命令非零退出CommandExitException被视为正常结果正常返回退出码与输出不抛异常命令执行超时TimeoutException返回exit_code-1, timed_outTrue文件读取路径会基于沙箱工作目录/home/user解析相对路径_SANDBOX_HOME见 路径解析绝对路径则原样透传。在工具层ExecuteTool 把单条命令包装成一个Execute工具单命令默认执行超时 30 秒DEFAULT_TIMEOUTstdout/stderr 默认最多截断 30000 字符MAX_OUTPUT_CHARS后返回给 LLM非零退出码与超时都会在返回 JSON 中标记为status: error。EnvironmentToolset 注入的系统指令EnvironmentToolset每次 LLM 调用都会注入一段环境级系统指令见 _constants.py 中的 ENVIRONMENT_INSTRUCTION约束模型的使用习惯DO用在单次Execute中串联有依赖的命令读文件始终用ReadFile工具改文件用EditFileDONT不要用Execute跑cat/head/tail不要在同一轮响应中把EditFile/ReadFile与Execute混用不要为有依赖的命令发起多个并行Execute。这套规则让模型在沙箱中的行为更高效、更可预测也解释了示例指令里“优先写脚本执行而非猜测、失败就修脚本重试”的风格。数据集 Schema 说明默认的 GCS 人口统计学 CSV 是带表头的标准 CSV。每一行是一个地区由location_key标识国家级行的location_key是两位 ISO 国家码如US、CN、IN次区域subregion的 key 含下划线如US_CA。Agent 的系统指令中写明了这一结构——尤其要求当问题针对国家时必须过滤掉含下划线的 key——这样生成的脚本才能正确解析并聚合数据。有用的列包括population、population_male、population_female、population_urban、population_rural、population_density等见 agent.py 指令。相关阅读想继续深入可以关注仓库中的这些位置示例本体agent.py 与 README.md环境抽象基类BaseEnvironment 与 ExecutionResult云端实现E2BEnvironment 及其 公开导出工具集实现EnvironmentToolset、ExecuteTool单元测试test_e2b_environment.py覆盖沙箱创建/幂等关闭、keepalive、过期重建、非零退出码、超时与路径解析等行为。如果需要对比仓库还提供了基于本地进程的 local_environment 与代码执行沙箱 code_execution 等示例可以横向理解不同环境的取舍E2B 侧重“远程隔离 公网访问”本地环境则更适合零额外依赖的快速调试。【免费下载链接】adk-pythonAn open-source, code-first Python toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.项目地址: https://gitcode.com/GitHub_Trending/ad/adk-python创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
