Databricks 沙盒快速入门

Important

此功能在 Beta 版中。 要在工作区中启用此功能预览，请选择在工作区预览页面启用 Databricks沙盒 设置。 请参阅 Manage Azure Databricks 预览版。

Databricks 沙盒在一个隔离的无服务器环境中运行代码，因此智能体可以安全地运行他们编写的代码。 你可以从代理、Python 代码或终端中使用沙箱。 以下每条路径都可单独使用，所以选择最适合你工作方式的那条：

有关Databricks沙盒的概述，包括计算规模、存储和限制，请参见 Databricks沙盒。

Requirements

给现有代理一个沙盒工具，安全执行代码

当你用 Agent Bricks CLI 构建代理时，使用这条路径，并且希望代理能运行它写的代码，比如用 Python 进行数据分析，而不让这些代码在代理自身环境中运行。

你无需先创建一个沙盒。 沙箱工具将你的代理连接到 Azure Databricks 托管的system.ai.sandbox服务，后者会在沙盒中帮你运行代理代码。 你只需要配置沙箱可以访问哪些数据，以及是否能写入。

要添加该工具，运行 agentbricks tools add sandbox，并指定一个或多个限制沙箱可访问数据的范围：

# Read one table.
agentbricks tools add sandbox --scope table:samples.nyctaxi.trips

# Read a volume and a workspace folder.
agentbricks tools add sandbox --scope volume:main.default.reports --scope workspace:/Workspace/Shared/data

# Allow writes to a volume.
agentbricks tools add sandbox --scope volume:main.default.output --permission read_write

该命令在项目的 agent.toml 中记录工具，代理在运行时通过 system.ai.sandbox MCP 服务调用沙盒。 默认情况下，沙箱运行时会保留发送请求的用户权限。 要改用应用的服务主体，请添加 --auth app。 当你使用 agentbricks deploy 部署时，Agent Bricks 会授予应用的服务主体访问使用 --auth app 的工具所对应的限定范围资源的权限。

使用 Python SDK 创建一个沙盒

当你想创建沙盒并从你自己的 Python 代码中在其中运行命令时，比如用于管理自己沙盒的应用程序或自定义代理，可以使用这条路径。 Databricks SDK for Python 是推荐的从代码中使用沙盒的方法。

  1. 安装或升级SDK：

    pip install --upgrade databricks-sdk

  2. 创建一个沙盒：

    from databricks.sdk import WorkspaceClient
from databricks.sdk.service.sandbox import Sandbox

w = WorkspaceClient()

created = w.sandbox.create_sandbox(
    sandbox=Sandbox(),
    sandbox_id="my-sandbox",
)
print(created.name)   # "sandboxes/my-sandbox"

  3. 在沙盒中运行命令。 该命令直接运行，无需 shell，因此要运行 shell 命令，请调用 /bin/bash -c：

    from google.protobuf.duration_pb2 import Duration

resp = w.sandbox.execute_command_sync(
    "sandboxes/my-sandbox",
    "/bin/bash",
    args=["-c", "echo hello world && whoami"],
    execution_timeout=Duration(seconds=30),
)
print(resp.exit_code)   # 0
print(resp.stdout)      # "hello world\nsandbox-agent\n"

  4. 完成后删除沙盒。 删除沙盒会移除其主目录并停止对其计费：

    w.sandbox.delete_sandbox("sandboxes/my-sandbox")

要获取、列出、更新、停止和重启沙盒，请参见 “用SDK创建和管理沙箱”。

注释

你无法通过SSH连接到你用Databricks SDK创建的沙盒。 如果想通过 SSH 从终端或 IDE 交互式地在沙箱中工作，则应改用 Databricks CLI 创建该沙箱。 请参阅使用 Databricks CLI 创建沙盒和 databricks sandbox ssh。

用Databricks的CLI创建沙盒

当你想从终端以交互方式在沙盒中工作时，请使用此路径。 通过 SSH 连接到沙箱，以运行耗时更长的代理任务，而无需让本地计算机保持运行。 例如，你可以通过 Databricks CLI 控制编码代理，或者连接桌面集成开发环境（IDE）或代理框架，如 Cursor、Claude 或 Codex。

要创建沙盒并连接到它，请运行：

databricks sandbox create      # create your sandbox
databricks sandbox register    # optional: register SSH keys
databricks sandbox ssh         # SSH to your default sandbox

连接时，沙箱中的 Databricks CLI 会被安装，并向沙箱运行所在的工作区进行身份验证。 如果你的工作区配置了 Unity Gateway，Azure Databricks 还会在你首次连接时，将 Claude 和 Codex 等常用编程工具配置为使用它。 参见 创建自定义模型服务 。 要在沙箱中使用Git，请配置Git凭证。 请参阅将您的 Git 提供商连接到 Databricks。

所有命令请执行 databricks sandbox -h，或参见 sandbox 命令组。

其他资源

  • 上次更新时间为