Guide de démarrage rapide sur l'exécution de code

Preview

Cette fonctionnalité est soumise(s) aux "Conditions des offres de pré-DG" de la section "Conditions générales des Services" des Conditions spécifiques du service. Les fonctionnalités pré-DG sont disponibles "en l'état" et peuvent avoir une prise en charge limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

Cette page explique comment effectuer des appels d'API directs à Agent Engine Code Execution pour exécuter du code non approuvé dans un environnement sandbox 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 Agent Engine pour accéder à l'exécution de code
• Créer un bac à sable d'exécution de code
• Lister et obtenir des bacs à sable (facultatif)
• 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

Avant de commencer

Configurez votre projet et votre environnement.

Configurer votre projet

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

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

Remarque : Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous ne disposez pas de cette autorisation, demandez à votre administrateur de vous attribuer le rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin).

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 la page 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.0

S'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 Agent Engine

Pour utiliser l'exécution de code, commencez par créer une instance 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 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 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=agent_engine_name,
    config=types.CreateAgentEngineSandboxConfig(display_name=sandbox_display_name),
)

sandbox_name = operation.response.name

Pendant la phase Preview, 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.

Lister et obtenir des bacs à sable (facultatif)

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 :

python_code = """
lines = []
with open("input.txt", "r") as input:
    for line in input:
        lines.append(line)
"""
input_data = {
    "code": python_code,
    "files": [{
        "name": "input.txt",
        "content": "aGVsbG8="
    }]
}

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":"","output_files":[]}',
      mime_type='application/json'),
  ]
)

Veuillez noter les points suivants :

• execute_code réinitialise la valeur TTL (Time To Live) du bac à sable.
• Les fichiers doivent être intégrés à la requête et encodés en base64.
• 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("output.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":"",
        "output_files":[{"content":"SGVsbG9Xb3JsZAo=", "name":"output.txt"}],
      }',
      mime_type='application/json',
    ),
  ]
)

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

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

Étapes suivantes

• Résoudre les problèmes d'exécution de code