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, incluindoCreateSandboxEnvironment,PauseSandboxEnvironment,ResumeSandboxEnvironment,SnapshotSandboxEnvironmenteDeleteSandboxEnvironment(exigindo permissões do IAMaiplatform.sandboxEnvironments.*). - Registros de acesso a dados (
ADMIN_READ): gravados quando ativados para operações de leitura de metadados, incluindoGetSandboxEnvironmenteListSandboxEnvironments. - 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, incluindoExecuteSandboxEnvironment,BidiExecuteSandboxEnvironment,AuthorizeSandboxEnvironmentAccesseExecuteCode. 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
stdoutestderr: a coleta automática do Cloud Logging para o Agent Runtime (comoreasoning_engine_stdoutereasoning_engine_stderr) se aplica apenas à instância paiReasoningEnginee não coleta automaticamente registros de recursos filhos do sandbox. A resposta ao comando (stdout,stderre 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_WRITEcom 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.