Início rápido do Databricks Sandbox

Importante

Esse recurso está em Beta. Para habilitar essa pré-visualização no workspace, opte pela configuração Databricks Sandbox na página de Pré-visualizações do workspace. Consulte Gerenciar visualizações do Azure Databricks.

O Databricks Sandbox roda código em um ambiente isolado e serverless, para que os agentes possam executar o código que escrevem com segurança. Você pode usar um sandbox a partir de um agente, de código Python ou de um terminal. Cada um dos caminhos a seguir funciona de forma independente, então escolha aquele que combina com a sua forma de trabalhar:

Para uma visão geral do Sandbox do Databricks, incluindo tamanho de computação, armazenamento e limitações, veja o Sandbox do Databricks.

Requirements

Dê a um agente existente uma ferramenta sandbox para executar código com segurança

Use este caminho quando você construir seu agente com a CLI Agent Bricks e quiser que o agente execute o código que escreve, como análise de dados em Python, sem que esse código rode no ambiente próprio do agente.

Você não cria um sandbox primeiro. A ferramenta sandbox conecta seu agente ao serviço system.ai.sandbox gerenciado pelo Azure Databricks, que executa o código do agente em um sandbox para você. Você configura apenas quais dados o sandbox pode acessar e se ele pode gravar.

Para adicionar a ferramenta, execute agentbricks tools add sandbox com um ou mais escopos que limitem quais dados o sandbox pode acessar:

# 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

O comando registra a ferramenta no agent.toml do projeto, e o agente chama o sandbox em tempo de execução através do serviço MCP system.ai.sandbox. Por padrão, o sandbox roda com as permissões do usuário que enviou a solicitação. Para usar a entidade de serviço do aplicativo, adicione --auth app. Quando você implanta com agentbricks deploy, o Agent Bricks concede ao principal do serviço do app acesso aos recursos com escopo para ferramentas que usam --auth app.

Use o SDK do Python para criar um sandbox

Use esse caminho quando quiser criar sandboxes e executar comandos neles a partir do seu próprio código Python, como uma aplicação ou um agente personalizado que gerencia seus próprios sandboxes. O SDK Databricks para Python é a forma recomendada de trabalhar com sandboxes a partir do código.

  1. Instale ou atualize o SDK:

    pip install --upgrade databricks-sdk

  2. Crie um 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. Execute um comando no sandbox. O comando roda diretamente, sem um shell, então, para executar um comando shell, chame /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. Exclua o sandbox quando terminar. Deletar um sandbox remove seu diretório inicial e interrompe a cobrança por ele:

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

Para obter, listar, atualizar, parar e reiniciar sandboxes, veja Criar e gerenciar sandboxes com o SDK.

Note

Você não pode se conectar via SSH a uma área restrita que você criar com o SDK do Databricks. Para trabalhar em um sandbox de forma interativa a partir de um terminal ou IDE via SSH, crie-o com a CLI do Databricks em vez disso. Veja Use a CLI do Databricks para criar uma área restrita e databricks sandbox ssh.

Use a CLI do Databricks para criar um sandbox

Use esse caminho quando quiser trabalhar em um sandbox de forma interativa a partir de um terminal. Conecte-se a um sandbox via SSH para rodar tarefas de agente mais longas sem manter sua máquina local ativa. Por exemplo, você pode acionar um agente de codificação a partir da CLI do Databricks, ou conectar um IDE de desktop ou um harness de agentes como Cursor, Claude ou Codex.

Para criar um sandbox e se conectar a ele, execute:

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

Quando você se conecta, a CLI do Databricks no sandbox é instalada e autenticada no workspace onde o sandbox roda. Se seu espaço de trabalho tiver o Unity Gateway configurado, o Azure Databricks também configura harnesses de codificação comuns, como Claude e Codex, para usá-lo na primeira vez que você se conectar. Veja Criar um serviço de modelo personalizado . Para usar o Git a partir do sandbox, configure credenciais Git. Consulte Conectar seu provedor Git ao Databricks.

Para todos os comandos, execute databricks sandbox -h, ou veja sandbox grupo de comandos.

Recursos adicionais

  • Última atualização em