Guida di avvio rapido di Esegui il codice

Questa pagina mostra come effettuare chiamate API dirette a Vertex AI Agent Engine Code Execution per eseguire codice non attendibile in un ambiente sandbox isolato. Le chiamate API dirette sono utili quando non vuoi che il framework dell'agente orchestri le chiamate per te o se vuoi integrare l'esecuzione di codice con altri framework dell'agente.

In questa guida rapida, eseguirai le seguenti attività:

• Crea un'istanza di Vertex AI Agent Engine per accedere all'esecuzione di codice
• Crea una sandbox di esecuzione del codice
• (Facoltativo) Elenca e ottieni sandbox
• Esegui il codice in una sandbox
• Esegui più codice utilizzando lo stesso sandbox. Tieni presente che la sandbox mantiene automaticamente il proprio stato.
• Esegui la pulizia

Per ulteriori informazioni sull'utilizzo dell'esecuzione di codice con Agent Development Kit (ADK), consulta Strumento di esecuzione di codice con Vertex AI Agent Engine.

Prima di iniziare

Configura il progetto e l'ambiente.

Configura il progetto

Accedi al tuo account Google Cloud . Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $di crediti senza costi per l'esecuzione, il test e il deployment dei workload.

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.

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 role (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

Nota: per abilitare le API, devi disporre dell'autorizzazione serviceusage.services.enable. Se non disponi di questa autorizzazione, chiedi all'amministratore di concederti il ruolo Amministratore utilizzo servizi (roles/serviceusage.serviceUsageAdmin).

Ottenere i ruoli richiesti

Per ottenere le autorizzazioni necessarie per utilizzare Vertex AI Agent Engine, chiedi all'amministratore di concederti il ruolo IAM Vertex AI User (roles/aiplatform.user) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Configura l'ambiente

Questa sezione presuppone che tu abbia configurato un ambiente di sviluppo Python o che tu stia utilizzando un runtime con un ambiente di sviluppo Python (ad esempio Colab).

Installare le librerie

Installa l'SDK Vertex AI:

  pip install google-cloud-aiplatform>=1.112.0

Autenticarsi in Vertex AI

Per autenticarti:

Shell locale

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Crea un'istanza di Vertex AI Agent Engine

Per utilizzare l'esecuzione del codice, crea prima un'istanza di Vertex AI Agent Engine. Non è necessario eseguire il deployment di un agente per utilizzare l'esecuzione di codice. Senza il deployment, la creazione di un'istanza di Vertex AI Agent Engine dovrebbe richiedere alcuni secondi.

import vertexai

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

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

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto Google Cloud .

• LOCATION: La regione Google Cloud per l'istanza di Vertex AI Agent Engine. Consulta Regioni supportate per Vertex AI Agent Engine.

Crea una sandbox

Crea una sandbox per l'esecuzione del codice.

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

Sostituisci quanto segue:

• SANDBOX_DISPLAY_NAME: il nome leggibile dell'ambiente sandbox di esecuzione del codice.

Puoi anche configurare le impostazioni della sandbox, come il linguaggio di programmazione e la configurazione della macchina:

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/AGENT_ENGINE_ID',
   config=types.CreateAgentEngineSandboxConfig(
       display_name=sandbox_display_name, ttl="3600s"),
)

Sostituisci quanto segue:

• PROJECT_ID: l'ID progetto Google Cloud .

• LOCATION: La regione Google Cloud per l'istanza di Vertex AI Agent Engine. Consulta Regioni supportate per Vertex AI Agent Engine.

• AGENT_ENGINE_ID: l'ID dell'istanza di Vertex AI Agent Engine.

Sono supportati solo LANGUAGE_PYTHON e LANGUAGE_JAVASCRIPT. Se machine_config non è specificato, la configurazione predefinita è 2 vCPU e 1,5 GB di RAM. Se specifichi MACHINE_CONFIG_VCPU4_RAM4GIB, la sandbox ha 4 vCPU e 4 GB di RAM.

(Facoltativo) Elenca e ottieni sandbox

Elenca tutte le sandbox associate all'istanza di Agent Engine specificata:

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

for sandbox in sandboxes:
    pprint.pprint(sandbox)

Ecco l'output di esempio:

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

Per ottenere una sandbox esistente:

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

pprint.pprint(sandbox)

Ecco l'output di esempio:

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

Esegui il codice in una sandbox

Per eseguire il codice, chiama 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
)

Ecco l'output di esempio:

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"
        }
    )
  ]
)

Tieni presente quanto segue:

• execute_code reimposta la durata (TTL) del sandbox.
• L'output è in byte non elaborati.
• Ogni richiesta o risposta può contenere fino a 100 MB di file.

Esegui altro codice in una sandbox

Per dimostrare che la sandbox mantiene il suo stato, esegui altro codice nella stessa sandbox:

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)

Ecco l'output di esempio:

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 risposta include un file che deve essere decodificato. Ecco un esempio di come decodificare l'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))

Ecco l'output di esempio:

b'HelloWorld\n'

Esegui la pulizia

Per eseguire la pulizia delle risorse create da questa guida rapida, elimina la sandbox e l'istanza di Vertex AI Agent Engine.

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

Passaggi successivi

• Risoluzione dei problemi di esecuzione del codice