Guía de inicio rápido de ejecución de código

Vista previa

Esta función está sujetas a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Las funciones previas a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

En esta página se muestra cómo hacer llamadas directas a la API Agent Engine Code Execution para ejecutar código no fiable en un entorno aislado. Las llamadas directas a la API son útiles cuando no quieres que el framework del agente coordine las llamadas por ti o si quieres integrar la ejecución de código con otros frameworks de agentes.

En esta guía de inicio rápido, realizarás las siguientes tareas:

• Crear una instancia de Agent Engine para acceder a Ejecución de código
• Crear un entorno aislado de ejecución de código
• Listar y obtener entornos de pruebas (opcional)
• Ejecutar código en un entorno aislado
• Ejecuta más código con el mismo entorno aislado. Ten en cuenta que el sandbox mantiene su estado automáticamente.
• Limpieza

Antes de empezar

Configura tu proyecto y tu entorno.

Configurar el proyecto

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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 (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 Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. 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 (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 Vertex AI API.

Roles required to enable APIs

To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains the serviceusage.services.enable permission. Learn how to grant roles.

Enable the API

Nota: Para habilitar APIs, necesitas el permiso serviceusage.services.enable. Si no tienes este permiso, pide a tu administrador que te conceda el rol Administrador de uso de servicios (roles/serviceusage.serviceUsageAdmin).

Obtener los roles necesarios

Para obtener los permisos que necesitas para usar Vertex AI Agent Engine, pide a tu administrador que te asigne el rol de gestión de identidades y accesos Usuario de Vertex AI (roles/aiplatform.user) en tu proyecto. Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

También puedes conseguir los permisos necesarios a través de roles personalizados u otros roles predefinidos.

Configurar un entorno

En esta sección se presupone que has configurado un entorno de desarrollo de Python o que usas un entorno de ejecución con un entorno de desarrollo de Python (como Colab).

Instalar bibliotecas

Instala el SDK de Vertex AI:

  pip install google-cloud-aiplatform>=1.112.0

Autenticarse en Vertex AI

Para autenticarte:

Shell local

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Crear una instancia de Agent Engine

Para usar Ejecución de código, primero debes crear una instancia de Agent Engine. No es necesario que implementes un agente para usar Ejecución de código. Si no se realiza ninguna implementación, la creación de una instancia de Agent Engine 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

Haz los cambios siguientes:

• PROJECT_ID: tu ID de proyecto Google Cloud .
• LOCATION: la Google Cloud región de tu Agent Engine.

Crear un entorno aislado

Crea un espacio aislado para la ejecución de código.

operation = client.agent_engines.sandboxes.create(
    spec={"code_execution_environment": {}},
    name=agent_engine_name,
    config=types.CreateAgentEngineSandboxConfig(display_name=SANDBOX_DISPLAY_NAME)
)

sandbox_name = operation.response.name

Haz los cambios siguientes:

• SANDBOX_DISPLAY_NAME: el nombre legible del entorno de zona de pruebas de ejecución de código.

También puedes configurar los ajustes del sandbox, como el lenguaje de programación y la configuración de la máquina:

operation = client.agent_engines.sandboxes.create(
    spec={
        "code_execution_environment": {
            "code_language": "LANGUAGE_JAVASCRIPT",
            "machine_config": "MACHINE_CONFIG_VCPU4_RAM4GIB"
        }
    },
    name=agent_engine_name,
    config=types.CreateAgentEngineSandboxConfig(display_name=sandbox_display_name),
)

sandbox_name = operation.response.name

Durante la vista previa, solo se admiten LANGUAGE_PYTHON y LANGUAGE_JAVASCRIPT. Si no se especifica machine_config, la configuración predeterminada es 2 vCPU y 1,5 GB de RAM. Si especificas MACHINE_CONFIG_VCPU4_RAM4GIB, el sandbox tendrá 4 vCPUs y 4 GB de RAM.

Listar y obtener entornos de pruebas (opcional)

Lista todas las sandboxes asociadas a la instancia de Agent Engine especificada:

sandboxes = client.agent_engines.sandboxes.list(name=agent_engine_name)

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Este es el resultado de ejemplo:

SandboxEnvironment(
  create_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC)),
  display_name='test_sandbox',
  name=SANDBOX_NAME,
  spec=SandboxEnvironmentSpec(
    code_execution_environment=SandboxEnvironmentSpecCodeExecutionEnvironment()
  ),
  state=<State.STATE_RUNNING: 'STATE_RUNNING'>,
  update_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC))
)

Para obtener un sandbox ya creado, sigue estos pasos:

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

pprint.pprint(sandbox)

Este es el resultado de ejemplo:

SandboxEnvironment(
  create_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC)),
  display_name='test_sandbox',
  name=SANDBOX_NAME,
  spec=SandboxEnvironmentSpec(
    code_execution_environment=SandboxEnvironmentSpecCodeExecutionEnvironment()
  ),
  state=<State.STATE_RUNNING: 'STATE_RUNNING'>,
  update_time=datetime.datetime(2025, 9, 7, 3, 42, 17, 93656, tzinfo=TzInfo(UTC))
)

Ejecutar código en un entorno aislado

Para ejecutar el código, llama a execute_code:

python_code = """
lines = []
with open("input.txt", "r") as input:
    for line in input:
        lines.append(line)
"""
input_data = {
    "code": python_code,
    "files": [{
        "name": "input.txt",
        "content": "aGVsbG8="
    }]
}

response = client.agent_engines.sandboxes.execute_code(
    name = sandbox_name,
    input_data = input_data
)
pprint.pprint(response)

Este es el resultado de ejemplo:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{"msg_err":"","msg_out":"","output_files":[]}',
      mime_type='application/json'),
  ]
)

Ten en cuenta lo siguiente:

• execute_code restablece el tiempo de vida (TTL) del sandbox.
• Los archivos deben insertarse en la solicitud y codificarse en Base64.
• Cada solicitud o respuesta puede contener archivos de hasta 100 MB.

Ejecutar más código en un entorno aislado

Para demostrar que la zona de pruebas mantiene su estado, ejecuta más código en la misma zona de pruebas:

python_code = """
with open("output.txt", "w") as output:
    for line in lines:
        output.write(line + "World\n")
"""
input_data = {"code": python_code}

response = client.agent_engines.sandboxes.execute_code(
    name = sandbox_name,
    input_data = input_data
)

pprint.pprint(response)

Este es el resultado de ejemplo:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
        "output_files":[{"content":"SGVsbG9Xb3JsZAo=", "name":"output.txt"}],
      }',
      mime_type='application/json',
    ),
  ]
)

La respuesta incluye un archivo que debe decodificarse. A continuación, se muestra un ejemplo de cómo decodificar el resultado:

import base64
import json

if response.outputs[0].mime_type=="application/json":
    json_output = json.loads(response.outputs[0].data.decode("utf-8"))
    output_file_content = json_output.get("output_files")[0].get("content")
    print(output_file_content.b64decode(output_file_content))

Este es el resultado de ejemplo:

b'HelloWorld\n'

Limpieza

Para limpiar los recursos creados por esta guía de inicio rápido, elimina tu sandbox y tu instancia de Agent Engine.

client.agent_engines.sandboxes.delete(name=sandbox_name)
agent_engine.delete()

Siguientes pasos

• Solución de problemas de ejecución de código