Donnez à un agent d'IA un accès en écriture à votre projet d'API et il peut causer de réels dommages. Pas intentionnellement ; les agents font simplement ce que l'invite suggère. Demandez-lui de « nettoyer les points de terminaison utilisateur » et il pourrait supprimer une route active dont vous dépendez toujours. Demandez-lui de « mettre à jour le schéma » et il peut écraser un modèle de données que trois autres points de terminaison référencent. L'agent n'a aucune idée de ce qui est déployé en production. Il ne voit que les ressources qu'il est autorisé à toucher, et il les touche.
C'est une nouvelle catégorie de risques. Lorsqu'un humain effectuait ces modifications, il hésitait avant de supprimer un point de terminaison. Un agent exécutant une boucle depuis votre terminal n'hésite pas. Il exécute la commande, reçoit une réponse de succès et passe à autre chose. Si cette commande a touché votre branche principale, le changement est déjà en ligne dans votre source de conception.
La solution n'est pas de bloquer les agents. C'est de leur donner un bac à sable dont ils ne peuvent pas s'échapper. L' AI Branch d'Apidog fait exactement cela : chaque modification pilotée par un agent atterrit dans une branche isolée, votre branche source reste intacte, et rien n'atteint la branche principale tant qu'un humain n'a pas examiné le diff et ne l'a pas fusionné. Cet article décrit le flux CLI de bout en bout, puis aborde l'hygiène générale des agents sûrs qui devrait l'entourer. Pour la logique de conception derrière la fonctionnalité, consultez l'article plus détaillé sur AI Branch et les changements plus sûrs pilotés par des agents ; cette pièce est le manuel d'utilisation pratique.
Pourquoi l'accès en écriture d'un agent est dangereux par défaut
La plupart des outils donnent à un agent un seul niveau d'accès : le projet. Si l'agent peut créer un point de terminaison, il peut aussi en supprimer un. S'il peut mettre à jour un schéma, il peut aussi le remplacer par quelque chose d'incompatible. Il n'y a pas d'écart entre « l'agent a proposé un changement » et « le changement est dans votre source de vérité ».
Trois modes de défaillance se manifestent encore et encore :
- Écrasement. L'agent régénère un schéma à partir d'une compréhension partielle de votre API et supprime des champs dont d'autres points de terminaison ont besoin.
- Suppression. L'agent « consolide » les points de terminaison et supprime des routes qui sont toujours appelées par des clients actifs.
- Dérive silencieuse. L'agent effectue des dizaines de petites modifications au cours d'une session. Aucun changement individuel ne semble incorrect, mais la somme diverge discrètement de ce que vous avez déployé.
Aucun de ces cas n'est exotique. Ce sont les résultats normaux d'un agent qui fait son travail sur la mauvaise branche. L'objectif est de rendre la mauvaise branche impossible à atteindre.
La solution principale : une branche d'IA isolée
Une branche d'IA est un type spécial de branche de sprint conçue pour les opérations externes d'IA et de CLI. Lorsque vous en créez une, l'agent y effectue des modifications et les changements y restent. Votre branche source et votre branche principale ne sont pas affectées tant que vous ne décidez pas de fusionner.
Vous la créez depuis la CLI. Installez et authentifiez d'abord l' Apidog CLI :
npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>
Créez ensuite la branche d'IA. La documentation recommande de la nommer avec la date, la branche source et le but afin de la repérer facilement plus tard :
apidog branch create --type ai \
--name "ai/20260708-from-main-user-register" \
--from main \
--project <PROJECT_ID>
Deux choses sont importantes ici. La branche est créée à partir de main, mais sa création ne touche pas main. Et la branche commence vide. Une branche d'IA ne copie pas automatiquement l'ensemble de votre projet en elle-même ; elle ne contient que les ressources que l'agent apporte explicitement. C'est une propriété de sécurité délibérée. L'agent ne peut modifier que ce qu'il a importé, donc le rayon d'action est ce que vous avez défini, pas l'intégralité du projet.
Pour voir l'ensemble complet des drapeaux pour toute commande de branche, exécutez-la avec -h :
apidog branch create -h
Importez les ressources source avant de les modifier
Parce que la branche d'IA est vide, la première tâche de l'agent est d'extraire les ressources spécifiques sur lesquelles il doit travailler. C'est l'étape qui empêche un agent de travailler à l'aveugle. Vous importez le point de terminaison, le schéma ou le document que vous souhaitez modifier, et rien d'autre n'est entraîné.
Dirigez l'agent (ou vous-même) vers les ressources exactes par ID. Apidog CLI utilise des drapeaux d'ID pluriels, séparés par des virgules pour ces opérations :
apidog branch pick-to \
--type ai \
--from main \
--to "ai/20260708-from-main-user-register" \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
Maintenant, la branche d'IA contient une copie des points de terminaison 1 et 2 et du schéma 3 tels qu'ils existent sur main. L'agent travaille sur ces copies. Quoi qu'il leur fasse, les originaux sur main restent inchangés. Si l'agent supprime un point de terminaison ici, il supprime la copie, pas la route active. C'est la différence entre « l'agent a détruit notre API » et « l'agent a détruit une copie de travail que nous pouvons jeter ».
Si vous pilotez cela via un agent de codage, les mêmes commandes s'exécutent à l'intérieur de la boucle de l'agent. L'Apidog CLI renvoie du JSON structuré avec agentHints.nextSteps, afin qu'un agent puisse lire le résultat de chaque commande et décider quoi faire ensuite sans que vous ne traduisiez la sortie pour lui. Le guide apidog-cli dans Cursor montre ce modèle intégré à un éditeur réel.
Laissez l'agent modifier, puis lisez le diff
Une fois les ressources importées, laissez l'agent faire son travail. Il crée, met à jour ou supprime des points de terminaison, des schémas, des documents et des scénarios de test à l'intérieur de la branche d'IA. Chaque écriture est contenue.
Une fois terminé, vous révisez avant toute fusion. Rien dans le flux de la branche d'IA n'est automatique ; la fusion est une décision humaine. Inspectez les changements depuis la CLI ou le client Apidog et confirmez que le diff correspond à ce que vous vouliez réellement. C'est votre porte de garde. Si l'agent est parti en vrille, vous le voyez ici, et la solution est de jeter la branche, non de restaurer la production.
Considérez cet examen comme obligatoire, non facultatif. L'objectif de l'ensemble du flux est qu'un humain examine la sortie de l'agent avant qu'elle ne devienne réelle. Ignorer l'examen annule l'isolation.
Déployez les changements avec une demande de fusion
La manière de fusionner dépend de la protection de la branche cible. C'est là qu'une branche principale protégée est rentable.
Si la branche cible n'est pas protégée, vous pouvez fusionner directement, en nommant les ressources exactes à transférer :
apidog branch merge \
--type ai \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--project <PROJECT_ID>
Si main est protégé, et il devrait l'être, une fusion directe est bloquée. Au lieu de cela, vous ouvrez une demande de fusion et faites passer le changement par une révision :
apidog merge-request create \
--from "ai/20260708-from-main-user-register" \
--to main \
--endpoint-ids 1,2 \
--data-schema-ids 3 \
--reviewer-ids <REVIEWER_USER_IDS> \
--description "AI branch: user register changes" \
--project <PROJECT_ID>
La demande de fusion est le chemin préféré pour tout ce qui est généré par un agent. Elle force le changement à passer par le même flux de révision qu'un contributeur humain. Un coéquipier l'approuve, puis elle est appliquée. L'agent n'écrit jamais sur main de son propre chef ; il ne peut que demander, via une demande de fusion, qu'un humain accepte son travail. Notez que la fusion ne prend en compte que les ID de ressources que vous listez. Si l'agent a touché quelque chose que vous n'aviez pas l'intention de déployer, vous omettez cet ID de la fusion et il reste en arrière.
Cela reflète la façon dont un flux de travail API natif Git gère les contributeurs humains : brancher, proposer, réviser, fusionner. La branche d'IA applique la même discipline à un contributeur non-humain, qui est celui que vous voulez le moins voir écrire directement sur `main`.
Nettoyer les branches fusionnées et abandonnées
Les branches d'IA fusionnées ou abandonnées doivent être archivées rapidement pour maintenir la liste des branches lisible. Une fois qu'une branche est fusionnée ou que vous décidez de ne plus en avoir besoin, archivez-la d'abord, puis supprimez-la :
apidog branch archive "ai/20260708-from-main-user-register" \
--type ai \
--project <PROJECT_ID>
La cadence recommandée est d'une branche d'IA par tâche. Une branche correspond à une seule unité de travail d'agent, est examinée, est fusionnée ou abandonnée, puis est archivée. Cela maintient l'isolation significative ; vous n'examinez jamais une branche qui a accumulé trois sessions d'éditions sans rapport.
Hygiène de l'agent sûr autour de la branche
La branche d'IA gère l'isolation, mais elle fonctionne mieux avec quelques habitudes qui limitent ce qu'un agent peut atteindre en premier lieu.
Utilisez des jetons d'accès à privilège minimum. Le jeton que vous transmettez à apidog login --with-token définit la portée de ce que l'agent peut faire. Donnez à un jeton d'automatisation l'accès aux projets dont il a besoin et rien de plus. Ne donnez pas à un agent votre jeton de propriétaire personnel juste parce que c'était pratique. Si un jeton est divulgué ou si un agent se comporte mal, vous voulez que les dommages soient limités par la portée du jeton.
Protégez votre branche principale. C'est le seul paramètre qui transforme le "revoir avant de fusionner" d'une suggestion en une règle. Avec main protégé, le chemin de fusion directe est fermé et chaque modification de l'agent doit passer par merge-request create. La protection est ce qui rend la demande de fusion non facultative.
Examinez avant de fusionner, à chaque fois. L'isolation ne vous protège que si un humain lit réellement le diff. Intégrez l'examen dans le flux de travail afin qu'il ne puisse pas être ignoré. Un agent qui a été fiable pendant une semaine peut toujours mal interpréter une invite le huitième jour.
Déléguer, puis vérifier. C'est le modèle qui relie tout. Vous déléguez une tâche ciblée à l'agent, le laissez s'exécuter dans sa branche isolée, puis vérifiez le résultat avant qu'il ne fusionne. L'agent fait le travail ; vous possédez l'acceptation. Le même partage apparaît lorsque les agents exécutent des tests : l'agent exécute la suite, vous vérifiez les résultats du faisceau de test et le code de sortie avant de leur faire confiance. Déléguez l'exécution, gardez le jugement.
Si vous versionnez votre spécification API dans Git en même temps que tout cela, le flux de travail de contrôle de version OpenAPI vous offre une deuxième couche d'historique à comparer lorsque quelque chose semble anormal.
Le flux de bout en bout, dans l'ordre
Voici l'ensemble du processus sous forme de séquence que vous pouvez donner à un agent ou exécuter vous-même :
apidog branch create --type aidepuismain. La branche est vide etmainn'est pas touchée.apidog branch pick-toles points de terminaison et schémas spécifiques dont l'agent a besoin. Rien d'autre n'est importé.- Laissez l'agent éditer à l'intérieur de la branche. Chaque écriture est contenue.
- Examinez le diff depuis la CLI ou le client. C'est le portail humain.
apidog merge-request createcontre unmainprotégé. Un coéquipier approuve ; l'agent n'écrit jamais directement sur main.apidog branch archiveune fois fusionnée ou abandonnée.
À aucun moment l'agent n'a de chemin pour écraser ou supprimer un point de terminaison actif sur main. Le pire qu'il puisse faire est d'apporter une mauvaise modification à une copie de travail que vous refusez ensuite de fusionner.
Donnez aux agents de l'espace pour travailler sans leur donner les clés
Les agents sont utiles précisément parce qu'ils agissent sans demander. C'est aussi ce qui rend l'accès en écriture sans restriction dangereux. La réponse n'est pas de ralentir l'agent ; c'est de faire en sorte que ses écritures rapides et sans hésitation atterrissent en toute sécurité. Une branche d'IA isolée, un `main` protégé, des jetons à privilège minimal et un examen obligatoire transforment « l'agent a détruit notre API » en un diff que vous jetez d'un coup d'œil.
Apidog intègre cela pour que vous n'ayez pas à l'assembler à partir d'outils séparés. Prenez l'Apidog CLI, créez une branche d'IA et laissez vos agents éditer une copie au lieu de la chose réelle. Téléchargez Apidog pour essayer le flux de la branche d'IA, et lisez la documentation de la branche d'IA pour la référence complète des commandes avant de l'intégrer à un flux de travail de production.