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

Vista previa

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles "sin modificaciones" y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En esta página, se muestra cómo realizar llamadas directas a la API de Agent Engine Code Execution para ejecutar código no confiable en un entorno de zona de pruebas aislado. Las llamadas directas a la API son útiles cuando no quieres que el framework del agente coordine las llamadas por ti o si deseas 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:

• Crea una instancia de Agent Engine para acceder a la ejecución de código
• Crea un entorno de pruebas de ejecución de código
• Cómo enumerar y obtener zonas de pruebas (opcional)
• Ejecuta código en una zona de pruebas
• Ejecuta más código con la misma zona de pruebas. Observa que la zona de pruebas mantiene automáticamente su estado.
• Limpia

Antes de comenzar

Configura tu proyecto y tu entorno.

Configura tu 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, pídele a tu administrador que te otorgue el rol de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin).

Obtén los roles necesarios

Para obtener los permisos que necesitas para usar Vertex AI Agent Engine, pídele a tu administrador que te otorgue el rol de IAM de Usuario de Vertex AI (roles/aiplatform.user) en tu proyecto. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Configura tu entorno

En esta sección, se supone que configuraste un entorno de desarrollo de Python o que usas un tiempo de ejecución con un entorno de desarrollo de Python (como Colab).

Instala bibliotecas

Instala el SDK de Vertex AI:

  pip install google-cloud-aiplatform>=1.112.0

Autentica en Vertex AI

Para autenticarte, haz lo siguiente:

Shell local

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Crea una instancia de Agent Engine

Para usar la ejecución de código, primero crea una instancia de Agent Engine. No es necesario implementar un agente para usar la Ejecución de código. Sin la 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

Reemplaza lo siguiente:

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

Crea una zona de pruebas

Crea un entorno de pruebas 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

Reemplaza lo siguiente:

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

También puedes configurar los parámetros de configuración de la zona de pruebas, 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 versión preliminar, solo se admiten LANGUAGE_PYTHON y LANGUAGE_JAVASCRIPT. Si no se especifica machine_config, la configuración predeterminada es 2 CPU virtuales y 1.5 GB de RAM. Si especificas MACHINE_CONFIG_VCPU4_RAM4GIB, la zona de pruebas tendrá 4 CPU virtuales y 4 GB de RAM.

Cómo enumerar y obtener zonas de pruebas (opcional)

Enumera todos los entornos de pruebas asociados con la instancia especificada de Agent Engine:

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

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Este es el resultado de muestra:

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 una zona de pruebas existente, haz lo siguiente:

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

pprint.pprint(sandbox)

Este es el resultado de muestra:

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))
)

Ejecuta código en una zona de pruebas

Para ejecutar 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 muestra:

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 actividad (TTL) del entorno de pruebas.
• Los archivos deben estar intercalados en la solicitud y codificados en base64.
• Cada solicitud o respuesta puede contener hasta 100 MB de archivos.

Ejecuta más código en una zona de pruebas

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 muestra:

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 se debe decodificar. Este es 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 muestra:

b'HelloWorld\n'

Limpia

Para limpiar los recursos creados por esta guía de inicio rápido, borra tu zona de pruebas y la instancia de Agent Engine.

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

¿Qué sigue?

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