Comment utiliser Google AX ? Tutoriel d’installation et de développement du runtime d’orchestration d’agents IA open source

Un agent démarre, mais son espace de travail, ses accès réseau et ses journaux restent difficiles à contrôler.

La solution la plus rapide consiste à suivre le Quickstart officiel de Google AX pour exécuter une tâche isolée, puis à vérifier séparément le bac à sable, le réseau et l’observabilité avant tout pilote à plusieurs tâches.

Cet article s’adresse aux développeurs Go qui construisent un exécuteur d’agents et veulent comprendre les interfaces de Google AX.
Il s’adresse aussi aux équipes SRE et plateforme chargées des espaces de travail, des limites réseau et du suivi des tâches.
Si vous évaluez un environnement distant, vous y trouverez des critères pour décider où développer et où exécuter vos essais.

Dernière vérification : 25 septembre 2026, d’après le dépôt officiel Google AX et son Quickstart, ainsi que les documents officiels sur les concepts, les runners, les manifestes, le réseau et le bac à sable. Les capacités décrites par le projet ne constituent pas, à elles seules, une validation de production pour chaque déploiement.

Ce que Google AX orchestre — et ce qu’il ne remplace pas

Google AX est à aborder comme un runtime destiné à organiser des tâches d’agents, leurs espaces de travail et leur exécution. Il ne faut pas le confondre avec le modèle qui génère les réponses, avec le programme d’agent qui décide des actions, ni avec une application métier prête à être utilisée. La documentation des concepts aide à distinguer ces rôles.

Pour décider si ce projet répond à votre besoin, séparez donc trois responsabilités :

• Le modèle produit ou interprète du contenu. Son choix, son accès et ses paramètres relèvent de votre configuration de modèle.
• L’agent transforme un objectif en actions : il peut appeler des outils ou exécuter un programme selon la logique que vous avez écrite.
• Le runtime prend en charge l’organisation du travail et le contexte d’exécution documentés par AX, notamment autour des tâches, des espaces de travail et des runners.

Cette distinction évite une erreur fréquente lors d’un prototype : croire que l’installation du runtime fournit automatiquement un agent compétent, une politique de sécurité complète ou une infrastructure multi-utilisateur. Vous devrez toujours définir ce que l’agent est autorisé à faire, quelles données lui sont fournies et comment vous contrôlez ses effets.

Trois coûts cachés méritent votre attention avant l’installation. Premièrement, une tâche qui peut écrire dans un répertoire partagé crée un risque de mélange de fichiers entre exécutions. Deuxièmement, un accès réseau nécessaire au développement peut aussi permettre des connexions que votre service ne devrait pas autoriser. Enfin, sans journaux exploitables et corrélés à l’identifiant de la tâche, une exécution échouée peut être difficile à diagnostiquer. Ces limites ne sont pas résolues par le simple fait de lancer un runner.

Première étape : préparer un environnement reproductible

Commencez par le dépôt officiel plutôt que par un exemple recopié dans un tutoriel tiers. Vous pouvez le récupérer ainsi :

git clone https://github.com/google/ax.git
cd ax

Le dépôt et son Quickstart sont les références à suivre pour les dépendances, la version de Go requise et la commande de lancement effectivement maintenue. Ces exigences peuvent évoluer : vérifiez-les dans la version que vous installez au lieu de retenir une version de mémoire ou de reprendre une ancienne commande.

Avant de lancer quoi que ce soit, examinez les points suivants :

• La version de Go et les outils de compilation exigés par le dépôt courant.
• Les services ou programmes externes explicitement nécessaires au parcours Quickstart.
• Les variables d’environnement et les secrets attendus, sans placer de jeton dans un fichier versionné.
• Le répertoire depuis lequel la commande doit être exécutée et les droits nécessaires à cette exécution.
• Les sorties attendues du Quickstart : tâche créée, commande lancée, état final et journaux disponibles.

L’objectif de cette vérification est de distinguer une erreur d’installation d’un problème de tâche. Si un service requis est absent, notez-le avant de modifier les manifestes ou le code de l’agent. Vous garderez ainsi une base de comparaison fiable pour les étapes suivantes.

Le Quickstart officiel est utile pour apprendre le chemin heureux, mais il ne constitue pas une garantie de sécurité ni une recette universelle de déploiement. Avant de préparer des données sensibles, consultez les documents consacrés au bac à sable et à ses mécanismes. Vérifiez aussi quelles protections sont fournies par le projet et lesquelles doivent être configurées par l’opérateur.

Deuxième étape : suivre le cycle d’une tâche

Une première exécution doit vous permettre de répondre à une question simple : pouvez-vous relier l’entrée de la tâche à son espace de travail, à la commande exécutée et au résultat observé ? Le fichier de tâche fourni en exemple donne un point de départ concret. Utilisez-le avec la documentation des champs de manifeste, plutôt que d’inventer des clés ou de supposer que chaque champ est obligatoire.

Procédez dans cet ordre :

1. Choisissez l’exemple officiel le plus proche de votre cas. Relevez le nom de la tâche, ses paramètres et les valeurs de configuration réellement présentes dans le fichier.
2. Identifiez l’espace de travail. Déterminez quels fichiers doivent y être accessibles et d’où ils proviennent. Évitez de copier tout un dépôt ou des secrets simplement parce que cela simplifie le premier essai.
3. Préparez l’entrée. Formulez une tâche test qui produit un effet limité et vérifiable, par exemple lire un fichier de démonstration et créer un résultat dans l’espace prévu.
4. Lancez l’exécution selon le Quickstart. Reprenez les commandes actuelles du dépôt ; conservez la commande utilisée et les éventuelles variables nécessaires pour pouvoir reproduire l’essai.
5. Observez l’exécution et son résultat. Vérifiez les journaux, l’état final et les fichiers créés. Une réponse textuelle de l’agent ne suffit pas si le but de la tâche est aussi de modifier un fichier.
6. Recommencez avec une erreur volontairement maîtrisée. Utilisez une entrée invalide ou une commande qui échoue sans effet externe. Vérifiez si l’échec est visible, si l’espace de travail reste accessible et si le résultat partiel est identifiable.

Cette séquence couvre l’intention derrière une préparation d’espace de travail AX : savoir ce qui entre dans le contexte de la tâche, ce que le processus peut modifier et ce qui reste après son arrêt. Les manifestes définissent des éléments de configuration, mais ne présumez pas qu’ils isolent à eux seuls les fichiers du système hôte. C’est au déploiement de fournir et de vérifier les frontières effectives.

Exemple de scénario : transformer un média sans exposer le répertoire complet

Imaginez une équipe de création qui veut demander à un agent de classer des prises audio ou de préparer des fichiers de travail vidéo. Le besoin est créatif, mais le risque est opérationnel : les sources peuvent être volumineuses, les noms de fichiers révélateurs et les sorties faciles à mélanger entre utilisateurs.

Pour l’essai, fournissez un petit ensemble de médias non sensibles dans un espace dédié, demandez une transformation déterministe et vérifiez que l’agent ne peut écrire que dans la zone prévue. Si un outil de traitement est appelé, identifiez son exécutable et ses dépendances au lieu de laisser l’agent parcourir tout l’environnement. Le même raisonnement s’applique à un projet de design : privilégiez une copie de travail et un résultat contrôlé plutôt qu’un accès en écriture à l’ensemble des fichiers de production.

Ce scénario permet de tester la relation entre le travail demandé, les fichiers d’entrée et les résultats, sans prendre un prototype réussi pour une preuve de confinement. La documentation officielle doit guider les options d’exécution ; les permissions du système, les montages de fichiers et les règles de réseau doivent être vérifiés dans l’environnement réellement retenu.

Troisième étape : brancher votre agent sur un runner

Le runner est le point d’intégration à examiner si vous souhaitez remplacer l’exemple par votre propre programme. Selon la documentation officielle du runner, votre lecture doit se concentrer sur la façon dont le contrôle transmet une tâche et un espace de travail, sur le lancement de la commande et sur les interfaces d’observation prévues.

Pour rester dans le contrat documenté, commencez par une commande d’agent simple. Faites-la accepter l’entrée prévue pour la tâche, travailler dans l’espace fourni et produire un résultat que vous pouvez contrôler. Ne construisez pas immédiatement un répartiteur, une file persistante et un tableau de bord : ces composants peuvent être nécessaires à votre plateforme, mais ne doivent pas être présentés comme des éléments fournis par AX sans confirmation dans la documentation.

Dans votre code d’intégration, isolez les responsabilités. Une fonction ou un adaptateur prépare l’entrée attendue par votre agent ; une autre traite le résultat et le code de sortie ; la couche d’observation associe les événements disponibles à la tâche concernée. Utilisez les noms et les signatures présents dans le document de runner de la version choisie. Si l’API évolue, cette séparation rendra l’adaptation moins risquée qu’un branchement direct dans toute la logique métier.

Vérifiez aussi le comportement aux frontières :

• Que se passe-t-il si l’agent termine sans produire le fichier attendu ?
• La sortie d’erreur est-elle récupérable par l’opérateur ?
• Une tâche interrompue laisse-t-elle des processus enfants ou des fichiers temporaires ?
• Les erreurs de préparation de l’espace sont-elles distinguées des erreurs de l’agent ?
• Les messages affichés à l’utilisateur omettent-ils les secrets et les chemins internes ?

Une intégration est prête pour un essai interne lorsqu’une tâche réussie et une tâche en échec sont toutes deux compréhensibles sans connexion interactive à la machine. Si les seules informations disponibles sont une sortie terminale éphémère, ajoutez la collecte nécessaire dans votre couche d’exploitation avant de multiplier les exécutions.

Quatrième étape : vérifier le bac à sable et le réseau

Ne traitez pas « bac à sable » comme une propriété binaire. La documentation AX sur le bac à sable décrit les mécanismes du projet ; la sécurité effective dépend aussi de l’identité du processus, du système d’exploitation, des droits et des options activées par le déploiement. De même, le document officiel sur la configuration réseau doit être lu avant d’autoriser l’accès aux services externes.

Testez les frontières à partir d’un compte et d’un espace de travail représentatifs du pilote :

• Fichiers : essayez de lire un chemin extérieur à l’espace attendu, puis vérifiez si cette lecture est refusée par les contrôles réellement actifs.
• Écriture : faites tenter à la tâche la création d’un fichier hors de son répertoire de sortie et confirmez le résultat du contrôle.
• Réseau : vérifiez quels domaines ou services doivent être accessibles et appliquez une politique de refus par défaut lorsque votre usage le permet.
• Secrets : inspectez l’environnement du processus et les journaux afin de vérifier qu’aucun jeton non nécessaire n’est transmis ou révélé.
• Diagnostic : si vous activez SSH, VNC ou une autre entrée de débogage, documentez son responsable, son périmètre, ses conditions d’accès et sa désactivation.

Les exemples de documentation n’établissent pas que tous ces contrôles sont actifs dans votre installation. La séparation est essentielle : AX documente ses interfaces et mécanismes ; vous choisissez et configurez les permissions, les règles réseau et les accès d’administration ; vos propres essais confirment ensuite le comportement obtenu. Ne présentez pas une vérification documentaire comme un test d’intrusion ni une commande qui échoue comme une preuve exhaustive d’isolation.

Du poste de développement au pilote contrôlé

Un développeur peut travailler localement pour modifier l’agent et lancer des essais. Une équipe plateforme doit cependant décider où s’exécute le runtime, où résident les données temporaires, comment les tâches sont observées et ce qui se passe en cas d’interruption. Cette décision dépend du système pris en charge par AX et par les mécanismes de bac à sable que vous comptez activer ; ne concluez pas qu’un Mac distant est automatiquement l’hôte adapté à l’exécution du runtime.

Le passage au pilote doit se faire par étapes. Validez d’abord une tâche sans données sensibles, puis une tâche qui échoue de façon contrôlée. Ensuite, vérifiez le nettoyage de l’espace et la conservation des journaux selon votre politique interne. N’introduisez la concurrence qu’après avoir démontré que deux exécutions ne partagent ni fichiers modifiables ni secrets involontairement. Le dépôt ne fournit pas, à lui seul, des garanties de capacité ou de performance applicables à toutes les configurations.

Voici une liste d’acceptation à cocher avant d’ouvrir le pilote :

• [ ] La version de Go et les dépendances correspondent aux instructions du dépôt courant.
• [ ] Le Quickstart a été exécuté avec une entrée non sensible et son résultat est reproductible.
• [ ] Les champs du manifeste utilisés sont ceux décrits par la documentation officielle.
• [ ] Le processus ne dispose que des chemins nécessaires à la tâche.
• [ ] Les règles réseau ont été vérifiées depuis l’environnement où le runner sera exécuté.
• [ ] Les accès de diagnostic sont documentés et désactivables.
• [ ] Une réussite, un échec et une interruption sont repérables dans les journaux.
• [ ] Le nettoyage de l’espace de travail a été vérifié après chaque issue testée.
• [ ] La procédure de reprise ne réutilise pas silencieusement un espace incomplet ou contaminé.
• [ ] Les tâches de plusieurs utilisateurs restent séparées dans les conditions prévues pour le pilote.

Si plusieurs éléments restent inconnus, restez au stade du poste de développement. Une démonstration fonctionnelle prouve qu’un chemin d’exécution est possible ; elle ne prouve pas la protection des données, le nettoyage après incident ou la capacité à absorber une charge variable.

Si votre équipe veut préparer le code et valider son environnement depuis un Mac distant, examinez d’abord la description de l’infrastructure Kvmjet et les nœuds Mac proposés pour votre région. Cela peut convenir à un environnement de développement ou à des essais compatibles avec macOS ; cela ne remplace pas un hôte Linux si le runtime ou son bac à sable l’exige. Un poste local reste plus simple si les essais sont ponctuels, tandis qu’une machine dédiée à long terme peut être préférable pour une charge soutenue ou des besoins matériels permanents.

Questions fréquentes

Comment installer Google AX et lancer une première tâche d’agent ?

Commencez par cloner le dépôt officiel, puis suivez les prérequis et les commandes du Quickstart présents dans sa version actuelle. N’empruntez pas une commande à un exemple ancien : vérifiez les dépendances, la configuration attendue et la sortie décrite dans le dépôt. Lancez ensuite une tâche isolée et conservez ses journaux pour contrôler le résultat.

Comment Google AX prépare-t-il l’espace de travail d’une tâche ?

La tâche et l’espace de travail doivent être considérés comme deux éléments liés du cycle d’exécution. Consultez les manifestes officiels pour connaître les champs pris en charge, puis vérifiez où les fichiers sont créés, quelles données y sont copiées et comment l’espace est nettoyé après succès ou échec. Ne supposez pas que la préparation implique une isolation complète.

Comment relier un agent personnalisé au runner de Google AX ?

Appuyez-vous sur le contrat Task et Workspace présenté dans la documentation du runner. Votre agent reste le programme qui décide quoi faire ; le runner reçoit le travail, prépare son contexte documenté, lance la commande prévue et expose les éléments d’exécution. Commencez par une commande déterministe et rendez visibles les erreurs, la sortie et l’état final.

Quelles limites vérifier avant de déployer Google AX ?

Vérifiez séparément les droits du processus, les chemins accessibles, la politique réseau, les entrées de diagnostic et la suppression des espaces de travail. Le dépôt documente des mécanismes et des options, mais leur activation et leur intégration dépendent de votre déploiement. Un test local réussi ne prouve ni l’étanchéité du bac à sable ni l’aptitude à traiter des tâches concurrentes.

Google AX peut simplifier l’organisation des tâches et de leur exécution, mais il ne dispense pas votre équipe de construire les limites autour du runner : accès aux fichiers trop larges, réseau insuffisamment restreint et journaux difficiles à corréler restent des risques concrets. Pour un essai ponctuel, un poste local peut suffire ; pour développer à distance avec une configuration dédiée, la location d’un Mac Kvmjet peut être une option si le système requis par votre runtime est compatible. Vérifiez ce point avant de choisir l’hôte, puis démarrez par une tâche isolée et un périmètre non sensible.