Databricks 沙盒快速入門

Important

這項功能位於 測試版 (Beta) 中。 要在工作區中啟用此功能預覽,請在工作區預覽頁面中選擇 Databricks 沙盒 設定。 請參閱 管理 Azure Databricks 預覽。

Databricks Sandbox 在隔離且無伺服器的環境中執行程式碼,讓代理程式能安全地執行他們所寫的程式碼。 你可以從代理程式、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 建立與管理沙盒。

Note

你無法透過 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 指令群組。

Tip

要在與工作區程式碼和資料相同的環境中執行 Claude Code 或 Codex,建議使用 SSH 隧道連接無伺服器運算或專用叢集。 代理程式已為 Unity Gateway 預先設定。 請參見「在 SSH 會話中執行編碼代理程式」。

其他資源