Cette page explique comment effectuer des appels d'API directs à l'exécution de code Vertex AI Agent Engine pour exécuter du code non fiable 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 l'exécution de code à d'autres frameworks d'agent.
Dans ce guide de démarrage rapide, vous allez effectuer les tâches suivantes :
- Créer une instance Vertex AI Agent Engine pour accéder à l'exécution de code
- Créer un bac à sable d'exécution de code
- (Facultatif) Lister et obtenir des bacs à sable
- Exécuter du code dans un bac à sable
- Exécutez plus de code en utilisant le même bac à sable. Notez que le bac à sable conserve automatiquement son état.
- Effectuer un nettoyage
Pour en savoir plus sur l'utilisation de l'exécution de code avec Agent Development Kit (ADK), consultez Outil d'exécution de code avec Vertex AI Agent Engine.
Avant de commencer
Configurez votre projet et votre environnement.
Configurer votre projet
- Connectez-vous à votre compte Google Cloud . 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 Vertex AI 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 Vertex AI 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 Vertex AI (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.0S'authentifier sur Vertex AI
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 Vertex AI Agent Engine
Pour utiliser l'exécution de code, commencez par créer une instance Vertex AI Agent Engine. Vous n'avez pas besoin de déployer d'agent pour utiliser l'exécution de code. Sans déploiement, la création d'une instance Vertex AI Agent Engine devrait prendre 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 projet Google Cloud .
LOCATION : région Google Cloud de votre instance Vertex AI Agent Engine. Consultez la page Régions disponibles pour Vertex AI Agent Engine.
Créer un bac à sable
Crée un bac à sable pour l'exécution du 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 du code.
Vous pouvez également configurer les paramètres du bac à sable, comme 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/AGENT_ENGINE_ID',
config=types.CreateAgentEngineSandboxConfig(
display_name=sandbox_display_name, ttl="3600s"),
)
Remplacez les éléments suivants :
PROJECT_ID : ID de votre projet Google Cloud .
LOCATION : Google Cloud région de votre instance Vertex AI Agent Engine. Consultez la page Régions disponibles pour Vertex AI Agent Engine.
AGENT_ENGINE_ID : ID de votre instance Vertex AI Agent Engine.
Seuls LANGUAGE_PYTHON et LANGUAGE_JAVASCRIPT sont acceptés. 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) Lister 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 Vertex AI Agent Engine.
client.agent_engines.sandboxes.delete(name=sandbox_name)
agent_engine.delete()