Databricks Sandbox quickstart

Databricks Sandbox esegue il codice in un ambiente separato e serverless, così gli agenti possono eseguire in sicurezza il codice che scrivono. Puoi usare un sandbox da un agente, dal codice Python o da un terminale. Ognuno dei seguenti percorsi funziona autonomamente, quindi scegli quello che corrisponde al tuo modo di lavorare:

• Dai a un agente esistente uno strumento sandbox in modo che l'agente esegue il codice che scrive in un sandbox.
• Usa l'SDK Python per creare sandbox ed eseguire comandi da codice Python.
• Usa la CLI Databricks per creare un sandbox e collegarti tramite SSH.

Per una panoramica del Sandbox Databricks, inclusi dimensione di calcolo, archiviazione e limitazioni, vedi Databricks Sandbox.

Requirements

• L'area di lavoro deve trovarsi in un'area supportata. Consulta Funzionalità con disponibilità regionale limitata.
• Per usare l'SDK, è necessario Python 3.10 o versioni successive.
• Per utilizzare la CLI Databricks, installa la CLI Databricks e autenticala con databricks auth login.

Fornire a un agente esistente uno strumento sandbox per eseguire codice in sicurezza

Usa questo percorso quando costruisci il tuo agente con la CLI Agent Bricks e vuoi che l'agente esegua il codice che scrive, come l'analisi dei dati in Python, senza che quel codice venga eseguito nell'ambiente stesso dell'agente.

Non si crea prima un sandbox. Lo strumento sandbox collega il tuo agente al servizio system.ai.sandbox gestito da Azure Databricks, che esegue il codice dell'agente in un sandbox per te. Configuri solo a quali dati il sandbox può accedere e se può scrivere.

Per aggiungere lo strumento, esegui agentbricks tools add sandbox con uno o più scope che limitano a quali dati il sandbox può accedere:

# 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

Il comando registra lo strumento nel agent.toml del progetto e l'agente invoca la sandbox in fase di esecuzione tramite il servizio MCP system.ai.sandbox. Per impostazione predefinita, il sandbox funziona con i permessi dell'utente che ha inviato la richiesta. Per utilizzare invece l'entità servizio dell'app, aggiungi --auth app. Quando distribuisci con agentbricks deploy, Agent Bricks concede all'entità servizio dell'app l'accesso alle risorse nell'ambito definito per gli strumenti che utilizzano --auth app.

Usa l'SDK Python per creare un sandbox

Usa questo percorso quando vuoi creare sandbox ed eseguire comandi al tuo interno dal tuo codice Python, come un'applicazione o un agente personalizzato che gestisce i propri sandbox. L'SDK Databricks per Python è il modo consigliato per lavorare con sandbox dal codice.

1. Installa o aggiorna l'SDK:

   pip install --upgrade databricks-sdk
   

2. Crea un sandbox:

   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. Esegui un comando nel sandbox. Il comando viene eseguito direttamente, senza uno shell, quindi per eseguire un comando shell, chiama /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. Elimina il sandbox quando hai finito. Eliminare un sandbox rimuove la sua directory principale e interrompe la fatturazione per esso:

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

Per recuperare, elencare, aggiornare, fermare e riavviare sandbox, consulta Crea e gestisci sandbox con l'SDK.

Usa la CLI Databricks per creare un sandbox

Usa questo percorso quando vuoi lavorare in modo interattivo in un sandbox da un terminale. Connettiti a un sandbox tramite SSH per eseguire task di agente più lunghe senza tenere attiva la macchina locale. Ad esempio, puoi guidare un agente di codifica dalla CLI Databricks, oppure collegare un IDE desktop o un harness di agenti come Cursor, Claude o Codex.

Per creare un sandbox e collegarsi ad esso, esegui:

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

Quando ti connetti, la CLI Databricks nel sandbox viene installata e autenticata nello spazio di lavoro in cui è in esecuzione il sandbox. Se nel tuo workspace è configurato Unity Gateway, Azure Databricks configura anche harness di codifica comuni, come Claude e Codex, per usarlo la prima volta che ti connetti. Vedi Creare un servizio di modello personalizzato . Per usare Git dal sandbox, configura le credenziali Git. Consulta Connetti il provider Git a Databricks.

Per tutti i comandi, esegui databricks sandbox -h, oppure vedi il gruppo di comandi sandbox.

Risorse aggiuntive

• Databricks Sandbox
• Crea e gestisci sandbox con l'SDK
• sandbox gruppo di comandi
• Riferimento della sandbox di Databricks SDK per Python