Panduan memulai Eksekusi Kode

Pratinjau

Fitur ini tunduk kepada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dari Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Halaman ini menunjukkan cara melakukan panggilan API langsung ke Eksekusi Kode Agent Engine untuk menjalankan kode yang tidak tepercaya di lingkungan sandbox yang terisolasi. Panggilan API langsung berguna jika Anda tidak ingin framework agen mengatur panggilan untuk Anda atau jika Anda ingin mengintegrasikan Eksekusi Kode dengan framework agen lain.

Dalam panduan memulai ini, Anda akan melakukan tugas-tugas berikut:

• Membuat instance Agent Engine untuk mengakses Eksekusi Kode
• Membuat sandbox Eksekusi Kode
• Mencantumkan dan mendapatkan sandbox (opsional)
• Menjalankan kode di sandbox
• Jalankan lebih banyak kode menggunakan sandbox yang sama. Perhatikan bahwa sandbox secara otomatis mempertahankan statusnya.
• Pembersihan

Sebelum memulai

Menyiapkan project dan lingkungan Anda.

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

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

Catatan: Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda tidak memiliki izin ini, minta administrator untuk memberi Anda peran Service Usage Admin (roles/serviceusage.serviceUsageAdmin).

Mendapatkan peran yang diperlukan

Untuk mendapatkan izin yang Anda perlukan untuk menggunakan Vertex AI Agent Engine, minta administrator Anda untuk memberi Anda peran IAM Vertex AI User (roles/aiplatform.user) di project Anda. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

Anda mungkin juga bisa mendapatkan izin yang diperlukan melalui peran kustom atau peran yang telah ditentukan lainnya.

Menyiapkan lingkungan Anda

Bagian ini mengasumsikan bahwa Anda telah menyiapkan lingkungan pengembangan Python, atau menggunakan runtime dengan lingkungan pengembangan Python (seperti Colab).

Menginstal library

Instal Vertex AI SDK:

  pip install google-cloud-aiplatform>=1.112.0

Melakukan autentikasi ke Vertex AI

Untuk melakukan autentikasi:

shell lokal

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Membuat instance Agent Engine

Untuk menggunakan Eksekusi Kode, buat instance Agent Engine terlebih dahulu. Anda tidak perlu men-deploy agen untuk menggunakan Eksekusi Kode. Tanpa deployment, pembuatan instance Agent Engine akan memerlukan waktu beberapa detik.

import vertexai

client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name

Ganti kode berikut:

• PROJECT_ID: ID project Google Cloud Anda.
• LOCATION: Google Cloud Region untuk Agent Engine Anda.

Membuat sandbox

Buat sandbox untuk eksekusi kode.

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

Ganti kode berikut:

• SANDBOX_DISPLAY_NAME: nama lingkungan sandbox eksekusi kode yang dapat dibaca manusia.

Anda juga dapat mengonfigurasi setelan sandbox seperti bahasa coding dan konfigurasi mesin:

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

Selama Pratinjau, hanya LANGUAGE_PYTHON dan LANGUAGE_JAVASCRIPT yang didukung. Jika machine_config tidak ditentukan, konfigurasi defaultnya adalah 2 vCPU dan RAM 1,5 GB. Jika Anda menentukan MACHINE_CONFIG_VCPU4_RAM4GIB, sandbox akan memiliki 4 vCPU dan RAM 4 GB.

Mencantumkan dan mendapatkan sandbox (opsional)

Mencantumkan semua sandbox yang terkait dengan instance Agent Engine yang ditentukan:

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

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Berikut contoh output-nya:

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

Untuk mendapatkan sandbox yang ada:

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

pprint.pprint(sandbox)

Berikut contoh output-nya:

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

Menjalankan kode di sandbox

Untuk mengeksekusi kode, panggil 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)

Berikut contoh output-nya:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{"msg_err":"","msg_out":"","output_files":[]}',
      mime_type='application/json'),
  ]
)

Perhatikan hal berikut:

• execute_code mereset time to live (TTL) sandbox.
• File harus disisipkan dalam permintaan dan dienkode base64.
• Setiap permintaan atau respons dapat berisi file hingga 100 MB.

Menjalankan lebih banyak kode di sandbox

Untuk mendemonstrasikan bahwa sandbox mempertahankan statusnya, jalankan lebih banyak kode di sandbox yang sama:

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)

Berikut contoh output-nya:

ExecuteSandboxEnvironmentResponse(
  outputs=[
    Chunk(
      data=b'{
        "msg_err":"",
        "msg_out":"",
        "output_files":[{"content":"SGVsbG9Xb3JsZAo=", "name":"output.txt"}],
      }',
      mime_type='application/json',
    ),
  ]
)

Respons menyertakan file yang perlu didekode. Berikut contoh cara mendekode 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))

Berikut contoh output-nya:

b'HelloWorld\n'

Pembersihan

Untuk membersihkan resource yang dibuat oleh panduan memulai ini, hapus instance Agent Engine dan sandbox Anda.

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

Langkah berikutnya

• Pemecahan masalah Eksekusi Kode