Gerenciar sandboxes

Nesta página, mostramos como gerenciar o ciclo de vida dos ambientes de sandbox usando o SDK do Python. É possível listar sandboxes, ver os detalhes, pausar e retomar ou excluir quando não forem mais necessários.

Antes de começar

Para gerenciar sandboxes, você precisa dos seguintes papéis no projeto:

  • Usuário da Agent Platform (roles/aiplatform.user)

Gerencie sandboxes

É possível listar, ver detalhes, pausar, retomar e excluir ambientes de sandbox associados a uma instância da Plataforma de Agentes. Com os recursos de pausa e retomada, é possível cancelar a programação de recursos de computação para sandboxes inativos e reativá-los mais tarde, sem perder o estado do sistema de arquivos ou a identidade da conexão. Para alterar a configuração de um sandbox atual, exclua-o e crie um novo.

Listar sandboxes

Para listar todos os sandboxes associados a uma instância da Agent Platform:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
instance_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID'

sandboxes = client.sandboxes.list(name=instance_name)

for sandbox in sandboxes:
    print(sandbox.name)

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região do Google Cloud da instância da plataforma de agentes. Consulte as regiões com disponibilidade.
  • INSTANCE_ID: o ID da instância da plataforma de agentes.

Ver detalhes do sandbox

Para ver a configuração e o status de um sandbox específico:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

sandbox = client.sandboxes.get(name=sandbox_name)
print(sandbox)

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região do Google Cloud da instância da plataforma de agentes. Consulte as regiões com disponibilidade.
  • INSTANCE_ID: o ID da instância da plataforma de agentes que contém seu sandbox.
  • SANDBOX_ID: o ID do sandbox atual.

A saída inclui detalhes como horário de criação, estado (por exemplo, STATE_RUNNING) e a especificação do sandbox.

Pausar um sandbox

Pausar um sandbox libera os recursos de computação dele, preservando o estado do disco e os metadados de conexão. Os sandboxes pausados custam significativamente menos do que os em execução e podem ser retomados em segundos. Use a pausa quando um sandbox estiver inativo por um período prolongado, mas você quiser preservar o estado da sessão e a identidade da conexão para uso posterior.

Os sandboxes pausados têm as seguintes características:

  • Manter o ID do sandbox, os metadados de conexão e qualquer endpoint do Private Service Connect.
  • Manter todo o estado do sistema de arquivos no contêiner no momento da pausa.
  • Transição para STATE_PAUSED. As solicitações para o endpoint do plano de dados vão retornar erros até que você retome o serviço.

Para pausar um sandbox em execução, execute o seguinte código:

import agentplatform

client = agentplatform.Client(project='PROJECT_ID', location='LOCATION')
sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

pause_operation = client.sandboxes.pause(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_PAUSED.
    },
)
paused_sandbox = pause_operation.response
print(f"Sandbox {paused_sandbox.name} state: {paused_sandbox.state}")  # STATE_PAUSED

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região do Google Cloud da instância da plataforma de agentes. Consulte as regiões com disponibilidade.
  • INSTANCE_ID: o ID da instância da plataforma de agentes que contém seu sandbox.
  • SANDBOX_ID: o ID do sandbox atual.

Retomar um sandbox

Retomar um sandbox pausado coloca a computação dele on-line novamente. O sandbox mantém o mesmo ID, endpoint de conexão (incluindo qualquer anexo de serviço do Private Service Connect) e estado do sistema de arquivos que tinha no momento da pausa. As solicitações do plano de dados podem ser feitas para o sandbox novamente assim que a operação de retomada for concluída.

Para retomar um sandbox pausado, execute o seguinte código:

sandbox_name = 'projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID/sandboxEnvironments/SANDBOX_ID'

resume_operation = client.sandboxes.resume(
    name=sandbox_name,
    config={
        "wait_for_completion": True,  # Optional. Blocks until the sandbox reaches STATE_RUNNING.
    },
)
resumed_sandbox = resume_operation.response
print(f"Sandbox {resumed_sandbox.name} state: {resumed_sandbox.state}")  # STATE_RUNNING

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud .
  • LOCATION: a região do Google Cloud da instância da plataforma de agentes. Consulte as regiões com disponibilidade.
  • INSTANCE_ID: o ID da instância da plataforma de agentes que contém seu sandbox.
  • SANDBOX_ID: o ID do sandbox pausado.

Excluir um sandbox

Para excluir explicitamente um ambiente de sandbox e liberar recursos:

client.sandboxes.delete(name=sandbox_name)
print("Sandbox deleted.")

Monitoramento e geração de registros de auditoria

Quando você gerencia e executa comandos em sandboxes, a plataforma de agentes registra a atividade no nível da API nos Registros de auditoria do Cloud com o nome de serviço aiplatform.googleapis.com e o tipo de recurso monitorado audited_resource:

  • Registros de atividade do administrador (ADMIN_WRITE): registrados automaticamente para mutações do ciclo de vida do plano de controle, incluindo CreateSandboxEnvironment, PauseSandboxEnvironment, ResumeSandboxEnvironment, SnapshotSandboxEnvironment e DeleteSandboxEnvironment (exigindo permissões do IAM aiplatform.sandboxEnvironments.*).
  • Registros de acesso a dados (ADMIN_READ): gravados quando ativados para operações de leitura de metadados, incluindo GetSandboxEnvironment e ListSandboxEnvironments.
  • Registros de acesso a dados (DATA_WRITE): gravados quando ativados para execução de comandos do plano de dados e chamadas de autorização de acesso, incluindo ExecuteSandboxEnvironment, BidiExecuteSandboxEnvironment, AuthorizeSandboxEnvironmentAccess e ExecuteCode. Para recursos protegidos pelo VPC Service Controls, os payloads de solicitação e resposta são omitidos dos registros de auditoria.

Lembre-se dos seguintes limites de observabilidade e detecção de ameaças:

  • Atividade de processo e stream no contêiner: os Registros de Auditoria do Cloud registram a solicitação de API que inicia a execução do comando ou autoriza uma conexão, mas não registram processos filhos individuais gerados dentro do contêiner, modificações no sistema de arquivos ou frames interativos subsequentes enviados por uma sessão aberta do WebSocket, do Chrome DevTools Protocol (CDP) ou do PTY.
  • Registros de contêiner stdout e stderr: a coleta automática do Cloud Logging para o Agent Runtime (como reasoning_engine_stdout e reasoning_engine_stderr) se aplica apenas à instância pai ReasoningEngine e não coleta automaticamente registros de recursos filhos do sandbox. A resposta ao comando (stdout, stderr e códigos de saída) é retornada na resposta de execução ao agente pai, em que é possível inspecionar e gravar entradas estruturadas no Cloud Logging.
  • Detecção de ameaças e inspeção de rede: os sandboxes aplicam a contenção por meio do isolamento do kernel do gVisor e de uma identidade sem privilégios no sandbox, sem credenciais de ambiente do Google Cloud . Para monitorar comportamentos anômalos ou saídas de rede não autorizadas, combine os registros de auditoria do DATA_WRITE com a detecção de anomalias do agente no agente pai e encaminhe a saída do sandbox por uma interface do Private Service Connect com registros de fluxo de VPC, registro de regras do Cloud Next Generation Firewall (Cloud NGFW) e inspeção do Secure Web Proxy. Para mais detalhes, consulte Limites de segurança, identidade e observabilidade.