在 agent-sandbox 沙箱中执行 Python 代码：Jupyter 会话、Shell 安装与结果读取实战-平芜编程栈

AI Agent
后端
MCP 服务
浏览器控制
Agent 评测

【免费下载链接】sandbox

All-in-One Sandbox for AI Agents that combines Browser, Shell, File, MCP and VSCode Server in a single Docker container.

项目地址：https://gitcode.com/gh_mirrors/sandbox103/sandbox

点击查看免费下载

本篇技术指南以仓库 examples/code-execute 示例为骨架，讲解如何通过 agent-sandbox Python SDK 在 All-in-One AI Agent 沙箱内完成「创建 Jupyter 会话 → 执行代码 → 用 Shell 安装依赖 → 二次执行验证」的完整代码执行链路，并深入解读 SDK 中 Jupyter、Shell 与统一代码运行时 API 的参数含义与底层行为。读完本文，你将能独立编写一套可复用的沙箱代码执行流程，并理解会话状态、内核选择与执行结果的解析方式。

示例定位与运行准备

这个示例解决什么问题

code-execute 示例演示的是 agent-sandbox 最核心的能力之一：在隔离沙箱中执行代码并取回结果。它覆盖了三条关键通道：

client.jupyter.*：通过 Jupyter 内核执行 Python 代码，支持会话状态保持；
client.shell.*：通过 Shell 会话执行任意命令（如安装依赖）；
client.sandbox.*：查询沙箱环境上下文（get_context），验证安装是否生效。

说明：该目录下的 README.md 标题沿用了文件操作模板示例的旧名称（Basic File Operations），其正文与目录定位（code-execute）及 main.py 实际演示的代码执行能力不一致，本文以目录名、examples/README.md 的定位说明及 main.py 的真实实现为准。

前置条件

根据 README.md 与 examples/README.md，运行该示例需要：

条件	说明
运行中的沙箱实例	默认地址`http://localhost:8080`，可通过`SANDBOX_BASE_URL`环境变量覆盖
Python 版本	3.11+（SDK 与示例项目均要求`>=3.11`，见 pyproject.toml）
包管理器	uv（示例统一通过`uv run`执行）

沙箱实例可通过仓库根目录的 docker-compose.yaml 一键启动，容器将沙箱服务暴露在宿主机的8080端口，Jupyter Lab 内部端口为8888（JUPYTER_LAB_PORT），并可通过DISABLE_JUPYTER环境变量开关 Jupyter 能力。

项目结构与依赖

示例工程由三个文件组成：入口脚本 main.py、依赖声明 pyproject.toml 与说明文档 README.md。其依赖只有两项：

dependencies = [ "agent-sandbox", "python-dotenv>=1.0.0", ] [tool.uv.sources] agent-sandbox = { path = "../../sdk/python", editable = true }

值得注意：[tool.uv.sources]将agent-sandbox指向仓库内sdk/python目录并以editable（可编辑）模式安装，因此在本地开发 SDK 时可以即时生效，无需重新打包。

运行示例

在 examples/code-execute 目录下直接执行：

uv run main.py

main.py启动时会调用load_dotenv()加载.env文件（main.py），并从环境变量读取沙箱地址，默认回退到http://localhost:8080（main.py）：

sandbox_url = os.getenv("SANDBOX_BASE_URL", "http://localhost:8080") client = Sandbox(base_url=sandbox_url)

预期输出包含两次代码执行的结果文本，例如Code execution result: 1以及沙箱上下文信息（get_context返回的字典内容）。

示例逐步拆解：一次完整的「执行-安装-再执行」流程

main.py 的流程可以拆成五个步骤，覆盖了沙箱代码执行的典型闭环。

步骤 1：创建 Jupyter 会话

session = client.jupyter.create_session( kernel_name="python3", )

create_session会创建一个持久的 Jupyter 内核会话，返回的session.data.session_id是后续保持状态的关键标识。如果不传session_id，服务端会自动生成。

步骤 2：执行第一段代码并写入变量

client.jupyter.execute_code( code="foo=1", kernel_name="python3", session_id=session.data.session_id )

注意这里同时传了kernel_name与session_id：kernel_name用于指定内核（新会话），session_id用于把本次执行路由到已创建的内核上。

步骤 3：在同会话中读取变量，验证状态保持

result = client.jupyter.execute_code( code="print(foo)", session_id=session.data.session_id, kernel_name="python3", ) print("Code execution result:", result.data.outputs[0].text)

第二次执行没有重新定义foo，却能成功print(foo)并输出1，这正是Jupyter 会话状态保持的体现：只要session_id相同，变量、导入的模块都会在内核中持续存在。这是 agent-sandbox 区别于「一次性执行」的关键能力。

步骤 4：通过 Shell 安装 Python 包

client.shell.exec_command(command="pip3.12 install agent-sandbox")

代码执行与 Shell 命令在同一个沙箱容器内共享文件系统与运行时环境，因此可以在 Jupyter 内核之外用 Shell 安装依赖，随后在代码执行中直接使用。

步骤 5：在指定内核中验证安装结果

result = client.jupyter.execute_code( code="""from agent_sandbox import Sandbox sandbox = Sandbox(base_url="http://localhost:8080") context = sandbox.sandbox.get_context() print(context) """, kernel_name="python3.12", ) print("After installed code result:", result.data.outputs[0].text)

这里换用python3.12内核执行——因为上一步pip3.12 install装进的是 Python 3.12 环境。代码段在沙箱内部再次实例化Sandbox客户端并调用sandbox.get_context()读取沙箱环境信息，形成「沙箱内调用沙箱 API」的自引用验证。

Jupyter 代码执行 API 深度解析

client.jupyter由 sdk/python/agent_sandbox/jupyter/client.py 提供，核心方法及其行为如下。

execute_code 参数

参数	类型	说明
`code`	str（必填）	要执行的 Python 代码
`timeout`	int	执行超时秒数
`kernel_name`	str	内核名：`python3`、`python3.10`、`python3.11`、`python3.12`；省略时使用运行时`PYTHON_VERSION`解析出的默认版本
`session_id`	str	会话 ID，用于跨请求保持内核变量状态
`cwd`	str	内核的当前工作目录

根据 client.py 的文档注释，会话在闲置 30 分钟后会自动过期，因此长时间不活动的会话会被服务端回收。

会话生命周期管理

create_session(session_id?, kernel_name?, cwd?)：创建会话，不传session_id时自动生成；
get_info()：查询沙箱内可用内核信息；
list_sessions()：列出所有活跃会话；
delete_session(session_id)：手动清理指定会话；
delete_sessions()：清理全部活跃会话。

建议在 Agent 任务结束时显式调用delete_session，避免会话占用沙箱资源直至 30 分钟自然过期。

执行结果模型

execute_code返回JupyterExecuteResponse（定义见 sdk/python/agent_sandbox/types/jupyter_execute_response.py）：

字段	说明
`kernel_name`	实际使用的内核名
`session_id`	本次执行的会话 ID
`status`	执行状态：`ok`、`error`或`timeout`
`execution_count`	内核执行计数
`outputs`	输出列表（`JupyterOutput`数组）
`code`	回显的被执行代码
`msg_id`	Jupyter 内核消息 ID

每个输出元素是JupyterOutput（sdk/python/agent_sandbox/types/jupyter_output.py），关键字段：

output_type：stream、execute_result、display_data或error；
name：流名称（stdout/stderr）；
text：流输出的文本内容；
data：execute_result/display_data的结构化数据；
ename/evalue/traceback：错误输出时的异常名、异常值与堆栈。

示例中的result.data.outputs[0].text正是取第一条输出的文本内容——对print类输出，就是内核 stdout 的文本。

Shell 通道与统一代码运行时

shell.exec_command

示例用exec_command安装依赖，SDK 端签名见 sdk/python/agent_sandbox/shell/client.py。除了command必填外，还有一组值得掌握的控制参数：

参数	说明
`id`	目标 Shell 会话 ID；不传时自动创建
`exec_dir`	命令工作目录（绝对路径）
`async_mode`	是否异步执行（默认同步）
`timeout`	等待命令完成的最大秒数，超时返回 running 状态
`strict`	工作目录严格校验：`True`时目录不存在直接报错，否则静默回退到会话工作目录
`no_change_timeout`	无新输出超时：在该时间内输出无变化则返回`NO_CHANGE_TIMEOUT`状态
`hard_timeout`	硬超时：到达后强制终止命令并返回`HARD_TIMEOUT`，与`timeout`（仅影响 HTTP 响应时机）不同
`truncate`	输出超过 30000 字符时是否截断（默认`True`）

同时，exec_command支持在Accept头携带text/event-stream时以 SSE 流式返回输出，适合长任务实时观察。

统一代码运行时 code.execute_code

除 Jupyter 与 Shell 外，SDK 还提供面向 Agent 的统一代码执行入口client.code.execute_code（sdk/python/agent_sandbox/code/client.py）：

client.code.execute_code( language="python", # Language 类型，按需分发给 Python / Node.js 等执行器 code="...", timeout=30, cwd="/home/gem", stateful=True, # 开启有状态执行（基于 Jupyter 内核） session_id="...", # stateful=True 时用于跨请求保持状态 )

它的设计意图是屏蔽底层执行器差异：language决定分发给 Python、Node.js 还是未来的语言执行器；stateful=True时基于 Jupyter 内核保存变量状态，session_id跨请求复用。仓库中 examples/openai-integration/main.py 展示了类似的 Agent 集成范式：把jupyter.execute_code/nodejs.execute_code封装成 function calling 工具，由大模型动态生成代码并执行。

实战扩展与最佳实践

稳健地读取与判定执行结果

不要直接假设outputs[0]一定是文本，建议按output_type分支处理：

resp = client.jupyter.execute_code(code="1+1").data if resp.status == "ok": for out in resp.outputs: if out.output_type == "stream" and out.text: print(out.text) elif out.output_type in ("execute_result", "display_data"): print(out.data) else: print(resp.status, [o.evalue for o in resp.outputs if o.output_type == "error"])

status字段（ok/error/timeout）是判断执行成败的第一依据，error输出中的ename、evalue、traceback可用于定位问题。

利用会话状态组织多步任务

对于「写变量 → 依赖上一步结果继续计算」的多步任务，始终复用同一个session_id，避免重复初始化开销。注意 30 分钟闲置过期与显式清理：

session = client.jupyter.create_session(kernel_name="python3.12").data sid = session.session_id # ... 多次 execute_code(session_id=sid) ... client.jupyter.delete_session(session_id=sid)

异步场景

SDK 同时提供异步客户端AsyncSandbox（sdk/python/agent_sandbox/client.py），API 与同步版一一对应，适合在 asyncio 驱动的 Agent 框架中使用。客户端构造时支持自定义timeout（默认 60 秒）、headers与httpx_client（sdk/python/agent_sandbox/client.py），可满足鉴权头注入、超时调优等需求。

小结

agent-sandbox 的代码执行能力由三组 API 协同构成：jupyter.*负责有状态 Python 执行与结果解析，shell.*负责容器内任意命令（含依赖安装、SSE 流式输出），code.execute_code则提供面向 Agent 的统一运行时分发。示例 examples/code-execute/main.py 展示的「创建会话 → 执行 → 安装依赖 → 换内核验证」闭环，是构建代码生成、数据分析、自动安装等 Agent 能力的直接范本，可在此基础上结合 examples/openai-integration/main.py 的 function calling 模式接入任意大模型。