Pular para o conteúdo principal
Última atualização em

Introdução ao Databricks Sandbox

info

Beta

Este recurso está em Beta. Para habilitar essa prévia de recurso no workspace, opte pela configuração Databricks Sandbox na página Prévias do workspace. Consulte Gerenciar prévias do Databricks.

O Databricks Sandbox executa o 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 de um agente, de um código Python ou de um terminal. Cada um dos caminhos a seguir funciona de forma independente, portanto, escolha aquele que corresponde à forma como você trabalha:

Para obter uma visão geral do Databricks Sandbox, incluindo tamanho do compute, armazenamento e limitações, consulte Databricks Sandbox.

Requisitos​

Dar a um agente existente uma ferramenta de sandbox para executar código com segurança​

Use este caminho ao criar seu agente com o Agent Bricks CLI e quiser que o agente execute o código que ele escreve, como análise de dados em Python, sem que esse código seja executado no próprio ambiente do agente.

Você não precisa criar um sandbox primeiro. A ferramenta de sandbox conecta seu agente ao serviço system.ai.sandbox gerenciado pelo Databricks, que execução 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, execução agentbricks tools add sandbox com um ou mais escopos que limitam quais dados o sandbox pode acessar:

Bash
# 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 default, o sandbox é executado com as permissões do usuário que enviou a solicitação. Para usar o service principal do aplicativo em vez disso, adicione --auth app. Ao implantar com agentbricks deploy, o Agent Bricks concede ao service principal do aplicativo acesso aos recursos com escopo para ferramentas que usam --auth app.

Usar o SDK do Python para criar um sandbox​

Use este caminho quando quiser criar sandboxes e execução de comandos nelas a partir do seu próprio código Python, como um aplicativo ou um agente personalizado que gerencia seus próprios sandboxes. O SDK do Databricks para Python é a maneira recomendada de trabalhar com sandboxes a partir do código.

  1. Instalar ou atualizar o SDK:

    Bash
    pip install --upgrade databricks-sdk

  2. Criar uma sandbox:

    Python
    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. Executar um comando na sandbox. O comando é execução diretamente, sem um shell, portanto para execução um comando shell, chame /bin/bash -c:

    Python
    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. A exclusão de um sandbox remove seu diretório pessoal e interrompe a cobrança por ele:

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

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

Usar a CLI do Databricks para criar uma sandbox​

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

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

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

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

Para todos os comandos, execução databricks sandbox -h ou consulte sandbox grupo de comandos.

Executar o Omnigent em uma sandbox​

Use este caminho quando você trabalhar no Omnigent e quiser que suas sessões de agente sejam executadas em um host de cloud gerenciado em vez de no seu laptop. O Omnigent gerenciado pode usar uma sandbox como o host onde as sessões do seu agente estão em execução. A sandbox continua em execução quando seu laptop está desligado e os modelos são roteados pelo Unity Gateway sem key de API.

  1. Em seu navegador da web, vá para <workspace-url>/omnigent.
  2. Selecione Nova sessão .
  3. Abra o seletor de host e selecione Sandbox .
  4. Descreva uma tarefa no compositor e envie-a para começar a sessão.

Para saber mais sobre hosts e runners, consulte o início rápido do Omnigent.

Recursos adicionais​

Nesta página