Guida di avvio rapido di Esegui il codice

Questa pagina mostra come effettuare chiamate API dirette a Esecuzione del codice 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 Esecuzione del codice con altri framework di agenti.

In questa guida rapida, svolgi le seguenti attività:

  • Crea un'istanza di Agent Platform per accedere a Esecuzione del codice
  • Crea una sandbox di Esecuzione del codice
  • (Facoltativo) Elenca e recupera le sandbox
  • Esegui il codice in una sandbox
  • Esegui altro codice utilizzando la stessa sandbox. Tieni presente che la sandbox mantiene automaticamente il suo stato.
  • Libera spazio

Per saperne di più sull'utilizzo di Esecuzione del codice con Agent Development Kit (ADK), consulta lo strumento Esecuzione del codice.

Prima di iniziare

Configura il progetto e l'ambiente.

Configura il progetto

  1. Accedi al tuo Google Cloud account. Se non hai mai utilizzato Google Cloud, crea un account per valutare il rendimento 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.

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

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Gemini Enterprise Agent Platform 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

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

    Go to project selector

  6. Verify that billing is enabled for your Google Cloud project.

  7. Enable the Gemini Enterprise Agent Platform 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

    8.

Ottieni i ruoli richiesti

Per ottenere le autorizzazioni necessarie per utilizzare Vertex AI Agent Engine, chiedi all'amministratore di concederti il ruolo IAM Utente di Agent Platform (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

In questa sezione si 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).

Installa le librerie

Installa l'SDK Vertex AI:

  pip install google-cloud-aiplatform>=1.112.0

Autentica

Per autenticare:

Shell locale

gcloud init
gcloud auth application-default login

Colab

from google.colab import auth

auth.authenticate_user()

Crea un'istanza di Agent Platform

Per utilizzare Esecuzione del codice, devi prima creare un'istanza di Agent Platform. Non è necessario eseguire il deployment di un agente per utilizzare Esecuzione del codice. Senza il deployment, la creazione di un'istanza di Agent Platform 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' Google Cloud ID progetto.

  • LOCATION: laregione per l'istanza di Agent Platform. Google Cloud Vedi Regioni supportate.

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

Sostituisci quanto segue:

  • PROJECT_ID: l' Google Cloud ID progetto.

  • LOCATION: Laregione per l'istanza di Agent Platform . Google Cloud Vedi Regioni supportate.

  • INSTANCE_ID: l'ID dell'istanza di Agent Platform.

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 recupera le 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 recuperare 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) della 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'

Libera spazio

Per liberare spazio dalle risorse create da questa guida rapida, elimina la sandbox e l'istanza di Agent Platform.

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

Passaggi successivi