Cette page explique comment effectuer des appels d'API directs à Code Execution pour exécuter du code non approuvé dans un environnement de bac à sable isolé. Les appels d'API directs sont utiles lorsque vous ne souhaitez pas que le framework d'agent orchestre les appels pour vous ou si vous souhaitez intégrer Code Execution à d'autres frameworks d'agent.
Dans ce guide de démarrage rapide, vous allez effectuer les tâches suivantes :
- Créer une instance Agent Platform pour accéder à Code Execution
- Créer un bac à sable Code Execution
- (Facultatif) Répertorier et obtenir des bacs à sable
- Exécuter du code dans un bac à sable
- Exécuter plus de code à l'aide du même bac à sable. Notez que le bac à sable conserve automatiquement son état.
- Effectuer un nettoyage
Pour en savoir plus sur l'utilisation de Code Execution avec le kit de développement d'agent (ADK), consultez l'outil Code Execution.
Avant de commencer
Configurez votre projet et votre environnement.
Configurer votre projet
- Connectez-vous à votre Google Cloud compte. Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $de crédits sans frais pour exécuter, tester et déployer des charges de travail.
-
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.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.-
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.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enablepermission. Learn how to grant roles.
Obtenir les rôles requis
Pour obtenir les autorisations nécessaires à l'utilisation de Vertex AI Agent Engine, demandez à votre administrateur de vous accorder le rôle IAM Utilisateur Agent Platform (roles/aiplatform.user) sur votre projet.
Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.
Vous pouvez également obtenir les autorisations requises avec des rôles personnalisés ou d'autres rôles prédéfinis.
Configurer votre environnement
Cette section suppose que vous avez configuré un environnement de développement Python, ou que vous utilisez un environnement d'exécution avec un environnement de développement Python (tel que Colab).
Installer les bibliothèques
Installez le SDK Vertex AI :
pip install google-cloud-aiplatform>=1.112.0Authentifier
Pour vous authentifier :
Shell local
gcloud init
gcloud auth application-default login
Colab
from google.colab import auth
auth.authenticate_user()
Créer une instance Agent Platform
Pour utiliser Code Execution, commencez par créer une instance Agent Platform. Vous n'avez pas besoin de déployer un agent pour utiliser Code Execution. Sans déploiement, la création d'une instance Agent Platform ne devrait prendre que quelques secondes.
import vertexai
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
agent_engine = client.agent_engines.create()
agent_engine_name = agent_engine.api_resource.name
Remplacez les éléments suivants :
PROJECT_ID : ID de votre Google Cloud projet.
LOCATION : région de votre instance Agent Platform. Google Cloud Consultez les régions compatibles.
Créer un bac à sable
Créez un bac à sable pour l'exécution de code.
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
Remplacez les éléments suivants :
SANDBOX_DISPLAY_NAME: nom lisible de l'environnement de bac à sable d'exécution de code.
Vous pouvez également configurer les paramètres du bac à sable, tels que le langage de programmation et la configuration de la machine :
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"),
)
Remplacez les éléments suivants :
PROJECT_ID : ID de votre Google Cloud projet.
LOCATION : région de votre instance Agent Platform . Google Cloud Consultez les régions compatibles.
INSTANCE_ID : ID de votre instance Agent Platform.
Seuls LANGUAGE_PYTHON et LANGUAGE_JAVASCRIPT sont compatibles. Si machine_config n'est pas spécifié, la configuration par défaut est de 2 processeurs virtuels et 1,5 Go de RAM. Si vous spécifiez MACHINE_CONFIG_VCPU4_RAM4GIB, le bac à sable dispose de 4 processeurs virtuels et de 4 Go de RAM.
(Facultatif) Répertorier et obtenir des bacs à sable
Répertoriez tous les bacs à sable associés à l'instance Agent Engine spécifiée :
sandboxes = client.agent_engines.sandboxes.list(name=agent_engine_name)
for sandbox in sandboxes:
pprint.pprint(sandbox)
Voici un exemple de résultat :
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))
)
Pour obtenir un bac à sable existant :
sandbox = client.agent_engines.sandboxes.get(name=sandbox_name)
pprint.pprint(sandbox)
Voici un exemple de résultat :
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))
)
Exécuter du code dans un bac à sable
Pour exécuter du code, appelez 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
)
Voici un exemple de résultat :
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"
}
)
]
)
Veuillez noter les points suivants :
execute_coderéinitialise la valeur TTL (Time To Live) du bac à sable.- Le résultat est exprimé en octets bruts.
- Chaque requête ou réponse peut contenir jusqu'à 100 Mo de fichiers.
Exécuter plus de code dans un bac à sable
Pour montrer que le bac à sable conserve son état, exécutez plus de code dans le même bac à sable :
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)
Voici un exemple de résultat :
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 réponse inclut un fichier qui doit être décodé. Voici un exemple de décodage du résultat :
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))
Voici un exemple de résultat :
b'HelloWorld\n'
Effectuer un nettoyage
Pour nettoyer les ressources créées par ce guide de démarrage rapide, supprimez votre bac à sable et votre instance Agent Platform.
client.agent_engines.sandboxes.delete(name=sandbox_name)
agent_engine.delete()