This page demonstrates how to make direct API calls to Agent Engine Code Execution to run untrusted code in an isolated sandbox environment.. Direct API calls are useful when you don't want the agent framework to orchestrate calls for you or if you'd like to integrate Code Execution with other agent frameworks.
In this quickstart, you perform the follow tasks:
- Create an Agent Engine instance to access Code Execution
- Create a Code Execution sandbox
- List and get sandboxes (optional)
- Execute code in a sandbox
- Execute more code using the same sandbox. Notice that the sandbox automatically maintains its state.
- Clean up
Before you begin
Set up your project and environment.
Set up your project
- 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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theserviceusage.services.enablepermission. Learn how to grant roles. -
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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 theserviceusage.services.enablepermission. Learn how to grant roles.
Get the required roles
To get the permissions that
you need to use Vertex AI Agent Engine,
ask your administrator to grant you the
Vertex AI User (roles/aiplatform.user)
IAM role on your project.
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Set up your environment
This section assumes that you have set up a Python development environment, or are using a runtime with a Python development environment (such as Colab).
Install libraries
Install the Vertex AI SDK:
pip install google-cloud-aiplatform>=1.112.0Authenticate to Vertex AI
To authenticate:
local shell
gcloud init
gcloud auth application-default login
Colab
from google.colab import auth
auth.authenticate_user()
Create an Agent Engine instance
To use Code Execution, first create an Agent Engine instance. You don't need to deploy an agent to use Code Execution. Without deployment, creating an Agent Engine instance should take a few seconds.
import vertexai
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name
Replace the following:
PROJECT_ID: Your Google Cloud project ID.LOCATION: The Google Cloud region for your Agent Engine.
Create a sandbox
Create a sandbox for code execution.
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
Replace the following:
SANDBOX_DISPLAY_NAME: the human readable name of the code execution sandbox environment.
You can also configure the sandbox settings like coding language and machine config:
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
During Preview, only LANGUAGE_PYTHON and LANGUAGE_JAVASCRIPT are supported. If machine_config is not specified, the default configuration is 2 vCPU and 1.5 GB of RAM. If you specify MACHINE_CONFIG_VCPU4_RAM4GIB, the sandbox has 4 vCPU and 4GB of RAM.
List and get sandboxes (optional)
List all the sandboxes associated with the specified Agent Engine instance:
sandboxes = client.agent_engines.sandboxes.list(name=agent_engine_name)
for sandbox in sandboxes:
pprint.pprint(sandbox)
Here's the sample output:
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))
)
To get an existing sandbox:
sandbox = client.agent_engines.sandboxes.get(name=sandbox_name)
pprint.pprint(sandbox)
Here's the sample output:
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))
)
Execute code in a sandbox
To execute code, call 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)
Here's the sample output:
ExecuteSandboxEnvironmentResponse(
outputs=[
Chunk(
data=b'{"msg_err":"","msg_out":"","output_files":[]}',
mime_type='application/json'),
]
)
Note the following:
execute_coderesets the sandbox's time to live (TTL).- Files must be inlined in the request and base64 encoded.
- Each request or response can contain up to 100MB of files.
Execute more code in a sandbox
To demonstrate that the sandbox maintains its state, execute more code in the same sandbox:
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)
Here's the sample output:
ExecuteSandboxEnvironmentResponse(
outputs=[
Chunk(
data=b'{
"msg_err":"",
"msg_out":"",
"output_files":[{"content":"SGVsbG9Xb3JsZAo=", "name":"output.txt"}],
}',
mime_type='application/json',
),
]
)
The response includes a file that needs to be decoded. Here's an example of how to decode the output:
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))
Here's the sample output:
b'HelloWorld\n'
Clean up
To clean up resources created by this quickstart, delete your sandbox and Agent Engine instance.
client.agent_engines.sandboxes.delete(name=sandbox_name)
agent_engine.delete()