En esta página, se muestra cómo realizar llamadas directas a la API para la ejecución de código con el objetivo de 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 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:
- Crea una instancia de Agent Platform para acceder a la ejecución de código
- Crea una zona de pruebas de ejecución de código
- 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. Observa que la zona de pruebas mantiene su estado automáticamente.
- Realiza una limpieza
Para obtener más información sobre el uso de la ejecución de código con el Kit de desarrollo de agentes (ADK), consulta la herramienta de ejecución de código.
Antes de comenzar
Configura tu proyecto y tu entorno.
Configura tu proyecto
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.
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 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 Agent Platform:
pip install google-cloud-agentplatform>=2.0.1Autenticar
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 Platform
Para usar la ejecución de código, primero crea una instancia de Agent Platform. No necesitas implementar un agente para usar la ejecución de código. Sin la implementación, la creación de una instancia de Agent Platform debería llevar unos segundos.
import agentplatform
from agentplatform import types
client = agentplatform.Client(project=PROJECT_ID, location=LOCATION)
remote_agent = client.runtimes.create()
remote_agent_name = remote_agent.api_resource.name
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto de Google Cloud .
LOCATION: Es la región de Google Cloud para 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.sandboxes.create(
spec={"code_execution_environment": {}},
name=remote_agent_name,
config=types.CreateRuntimeSandboxConfig(display_name=SANDBOX_DISPLAY_NAME)
)
sandbox_name = operation.response.name
Reemplaza lo siguiente:
SANDBOX_DISPLAY_NAME: Es el nombre legible por humanos del entorno de zona de pruebas de ejecución de código.
También puedes configurar los parámetros de la zona de pruebas, como el lenguaje de programación y la configuración de la máquina:
operation = client.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.CreateRuntimeSandboxConfig(
display_name=sandbox_display_name, ttl="3600s"),
)
Reemplaza lo siguiente:
PROJECT_ID: Es el ID del proyecto de Google Cloud .
LOCATION: Es la región de Google Cloud para 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 de 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.
Enumera y obtén zonas de pruebas (opcional)
Enumera todas las zonas de pruebas asociadas con la instancia de Agent Engine especificada:
sandboxes = client.sandboxes.list(name=remote_agent_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 una zona de pruebas existente, haz lo siguiente:
sandbox = client.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))
)
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.sandboxes.execute_code(
name = sandbox_name,
input_data = input_data
)
Este es el resultado de ejemplo:
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_coderestablece el tiempo de actividad (TTL) de la zona de pruebas.- El resultado se expresa 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.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":"",
}',
mime_type='application/json',
),
chunk(
data=b"hello world!",
mime_type="text/plain"
attributes={
"file_name":"output2.txt"
}
)
]
)
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 ejemplo:
b'HelloWorld\n'
Realiza una limpieza
Para limpiar los recursos que se crearon en esta guía de inicio rápido, borra la zona de pruebas y la instancia de Agent Platform.
client.sandboxes.delete(name=sandbox_name)
remote_agent.delete()