Questa pagina mostra come effettuare chiamate API dirette all'esecuzione di 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 orchestra le chiamate per te o se vuoi integrare l'esecuzione di codice con altri framework dell'agente.
In questa guida rapida imparerai a:
- Crea un'istanza di Agent Platform per accedere all'esecuzione di codice
- Crea una sandbox per l'esecuzione di codice
- (Facoltativo) Elenca e recupera le sandbox
- Esegui il codice in una sandbox
- Esegui più codice utilizzando la stessa sandbox. Nota che la sandbox mantiene automaticamente il suo stato.
- Esegui la pulizia
Per saperne di più sull'utilizzo dell'esecuzione di codice con Agent Development Kit (ADK), consulta Strumento Esecuzione di codice.
Prima di iniziare
Configura il progetto e l'ambiente.
Configura il progetto
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Gemini Enterprise Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Ottieni i ruoli richiesti
Per ottenere le autorizzazioni necessarie per utilizzare Vertex AI Agent Engine, chiedi all'amministratore di concederti il ruolo IAM Agent Platform 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 (come Colab).
Installa le librerie
Installa l'SDK Agent Platform:
pip install google-cloud-agentplatform>=2.0.1Autentica
Per eseguire l'autenticazione:
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 l'esecuzione di codice, crea prima un'istanza di Agent Platform. Non è necessario eseguire il deployment di un agente per utilizzare l'esecuzione di codice. Senza deployment, la creazione di un'istanza di Agent Platform dovrebbe richiedere alcuni secondi.
import agentplatform
from agentplatform import types
client = agentplatform.Client(project=PROJECT_ID, location=LOCATION)
remote_agent = client.runtimes.create()
remote_agent_name = remote_agent.api_resource.name
Sostituisci quanto segue:
PROJECT_ID: l'ID progetto Google Cloud .
LOCATION: la regione Google Cloud per l'istanza di Agent Platform. Consulta Regioni supportate.
Crea una sandbox
Crea una sandbox per l'esecuzione del codice.
operation = client.sandboxes.create(
spec={"code_execution_environment": {}},
name=remote_agent_name,
config=types.CreateRuntimeSandboxConfig(display_name=SANDBOX_DISPLAY_NAME)
)
sandbox_name = operation.response.name
Sostituisci quanto segue:
SANDBOX_DISPLAY_NAME: il nome leggibile dell'ambiente sandbox di esecuzione di codice.
Puoi anche configurare le impostazioni della sandbox, come il linguaggio di programmazione e la configurazione della macchina:
operation = client.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.CreateRuntimeSandboxConfig(
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 Agent Platform. Consulta Regioni supportate.
INSTANCE_ID: l'ID dell'istanza della piattaforma dell'agente.
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 Agent Engine specificata:
sandboxes = client.sandboxes.list(name=remote_agent_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.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.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_codereimposta la durata (TTL) della sandbox.- L'output è in byte non elaborati.
- Ogni richiesta o risposta può contenere fino a 100 MB di file.
Esegui più 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.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 Agent Platform.
client.sandboxes.delete(name=sandbox_name)
remote_agent.delete()