Code Execution quickstart

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 the resourcemanager.projects.create permission. Learn how to grant roles .

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 .

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

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

Authenticate to Vertex AI

To authenticate:

  gcloud 
 init 
 gcloud 
 auth 
 application 
 - 
 default 
 login 
 

  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_code resets 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 
 () 
 

What's next

• Code Execution troubleshooting