Guía de inicio rápido de la zona de pruebas de la shell

Una zona de pruebas de shell es un contenedor de Linux aislado y administrado que se adjunta a una instancia de Agent Platform. La zona de pruebas ejecuta un comando de shell que envía tu agente y muestra stdout, stderr y un código de salida. No se ejecuta nada en tu propia infraestructura, y el contenedor se destruye cuando se borra la zona de pruebas.

Usa una zona de pruebas de shell cuando un agente necesite ejecutar comandos de shell no confiables o generados, instalar paquetes, manipular archivos o controlar herramientas de línea de comandos sin exponer tu entorno.

Limitaciones

• send_command() y execute_code() no funcionan con las zonas de pruebas de shell. Estos métodos segmentan las zonas de pruebas de ejecución de código y envían cargas útiles de Python, que el contenedor de shell no acepta. Usa /exec con las zonas de pruebas de shell.

Antes de comenzar

Configura tu proyecto y tu entorno.

Configura tu proyecto

Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

• Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
• Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

Enable the Gemini Enterprise Agent Platform API.

Roles required to enable APIs

To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

Enable the API

Obtén los roles necesarios

Para usar la zona de pruebas, necesitas el siguiente rol:

• Usuario de Agent Platform (roles/aiplatform.user) en el proyecto

Instala bibliotecas

Instala el SDK con el módulo de Agent Platform:

pip install "google-cloud-aiplatform[agent_engines]"

Autenticar

Para autenticar con credenciales predeterminadas de la aplicación, haz lo siguiente:

gcloud auth application-default login

Crea una instancia de Agent Platform

Para usar una zona de pruebas de shell, primero crea una instancia de Agent Platform. No necesitas implementar un agente para usar una zona de pruebas de shell. Sin la implementación, la creación de una instancia de Agent Platform debería tardar unos segundos.

import vertexai

client = vertexai.Client(project='PROJECT_ID', location='LOCATION')

agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del Google Cloud proyecto de.

• LOCATION: La Google Cloud región de tu instancia de Agent Platform. Consulta Regiones admitidas.

Crea una zona de pruebas de shell

Debes proporcionar al menos uno de los siguientes elementos cuando crees una zona de pruebas:

• spec con un entorno establecido (shell_environment)
• config.sandbox_environment_template (se crea una plantilla predeterminada si no se especifica) (Para obtener más información, consulta Cómo reutilizar plantillas en zonas de pruebas)
• config.sandbox_environment_snapshot

En el siguiente ejemplo, se pasa shell_environment en la especificación de la zona de pruebas:

engine = (
    "projects/PROJECT_ID/locations/LOCATION"
    "/reasoningEngines/INSTANCE_ID"
)

operation = client.agent_engines.sandboxes.create(
    name=engine,
    spec={"shell_environment": {}},
    config={
        "display_name": "my-shell-sandbox",
        "wait_for_completion": True,
        "ttl": "3600s",
    },
)
sandbox = operation.response
print(sandbox.name, sandbox.state)

Cuando la zona de pruebas esté lista, imprimirá una respuesta similar a la siguiente:

projects/.../sandboxEnvironments/1035360621853409280 SandboxState.STATE_RUNNING

Por lo general, una zona de pruebas alcanza STATE_RUNNING en unos 20 segundos.

Ejecuta un comando

Para ejecutar un comando de shell en la zona de pruebas, usa la función auxiliar execute_bash(), que envía el comando al contenedor:

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="echo hello && whoami && pwd",
)
print(result)

El comando muestra stdout, stderr, returncode y duration_ms:

{'stdout': 'hello\nappuser\n/workspace\n', 'stderr': '', 'returncode': 0, 'duration_ms': 8}

execute_bash() se autentica con tus propias credenciales, por lo que no necesitas una cuenta de servicio ni un JWT firmado.

Opcional: Puedes configurar cwd de forma explícita para elegir el directorio de trabajo y timeout para limitar el tiempo que puede ejecutarse el comando. De lo contrario, la zona de pruebas usa sus propios valores predeterminados (/workspace y el límite de tiempo de la zona de pruebas):

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="pytest -q",
    cwd="/workspace/app",
    timeout=120,
)

Para saber si falla un comando, inspecciona returncode y stderr:

result = client.sandboxes.execute_bash(
    name=sandbox.name,
    command="ls /nope",
)
print(result)

{'stdout': '', 'stderr': "ls: cannot access '/nope': No such file or directory\n", 'returncode': 2, 'duration_ms': 5}

Cuando uses el entorno de contenedor, ten en cuenta lo siguiente:

• Los comandos se ejecutan como el usuario sin privilegios appuser; no hay sudo.
• Cada comando se ejecuta en un shell nuevo, por lo que cd y las variables de shell no se transfieren entre llamadas. Encadénalos en un comando o escribe el estado en un archivo en /workspace.
• El acceso a Internet saliente está desactivado, a menos que la plantilla lo habilite.

Limpia

Para borrar la zona de pruebas y dejar de generar cargos, ejecuta lo siguiente:

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

¿Qué sigue?

• Administrar zonas de pruebas
• Administrar plantillas de zonas de pruebas