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

En esta página, se muestra cómo realizar llamadas directas a la API de 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 organice las llamadas por ti o si deseas integrar Code Execution con otros frameworks de agentes.

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

  • Crea una instancia de Agent Platform para acceder a Code Execution.
  • Crea una zona de pruebas de Code Execution.
  • Enumera y obtén zonas de pruebas (opcional).
  • Ejecuta código en una zona de pruebas.
  • Ejecuta más código con la misma zona de pruebas. Ten en cuenta que la zona de pruebas mantiene su estado de forma automática.
  • Limpia

Para obtener más información sobre el uso de Code Execution con el Kit de desarrollo de agentes (ADK), consulta la herramienta Code Execution.

Antes de comenzar

Configura tu proyecto y tu entorno.

Configura tu proyecto

  1. 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.

  2. 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.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform 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

  5. 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.

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Gemini Enterprise Agent Platform 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

    8.

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 Usuario de Agent Platform (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 entorno 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

Autenticar

Para autenticar, 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 Platform

Para usar Code Execution, primero crea una instancia de Agent Platform. No es necesario que implementes un agente para usar Code Execution. 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.

  • LOCATION: Es la Google Cloud región de tu instancia de Agent Platform. Consulta las regiones admitidas.

Crea una zona de pruebas

Crea una zona 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='projects/PROJECT_ID/locations/LOCATION/reasoningEngines/INSTANCE_ID',
   config=types.CreateAgentEngineSandboxConfig(
       display_name=sandbox_display_name, ttl="3600s"),
)

Reemplaza lo siguiente:

  • PROJECT_ID: Es el ID del Google Cloud proyecto.

  • LOCATION: Es la Google Cloud región de tu instancia de Agent Platform. Consulta las regiones admitidas.

  • INSTANCE_ID: Es el ID de tu instancia de Agent Platform.

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 tiene 4 CPU virtuales y 4 GB de RAM.

Enumera y obtén zonas de pruebas (opcional)

Enumera todas las zonas de pruebas asociadas con 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 un 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 un 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:

my_code = """
with open("input.txt", "r") as input:
   with open("output.txt", "w") as output:
       for line in input:
           print(line)
           output.write(line)
"""
input_data = {
   "code": my_code,
   "files": [{
       "name": "input.txt",
       "content": b"Hello, world!"
   }]
}


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

Este es un resultado de muestra:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
      }',
      mime_type='application/json',
    ),
    chunk(
data=b"hello world!",
        mime_type="text/plain"
        attributes={
          "file_name":"output.txt"
        }
    )
  ]
)

Ten en cuenta lo siguiente:

  • execute_code restablece el tiempo de actividad (TTL) de la zona de pruebas.
  • El resultado está en bytes sin procesar.
  • 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("output2.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 un resultado de muestra:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
      }',
      mime_type='application/json',
    ),
    chunk(
      data=b"hello world!",
        mime_type="text/plain"
        attributes={
          "file_name":"output2.txt"
        }
    )

  ]
)

La respuesta incluye un archivo que debe decodificarse. 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 un resultado de muestra:

b'HelloWorld\n'

Limpia

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

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

¿Qué sigue?