Skip to main content
Un orchestrateur surveille l’API Outposts pour détecter les sessions en attente sur un outpost, provisionne une VM ou un conteneur pour chacune d’elles, puis y démarre le worker. Cette page décrit la boucle d’orchestration : interrogation périodique de la file d’attente, prise en charge des sessions, exécution des workers et suppression des machines. Si vous voulez simplement exécuter des sessions sur une machine dont vous disposez déjà, commencez par le quickstart — aucun orchestrateur n’est nécessaire. Si vous utilisez une plateforme prise en charge, une intégration implémente peut-être déjà cette boucle pour vous. Pour la référence complète de l’API et de la CLI, consultez la reference.
Vous utilisez Kubernetes ? devin-outpost-k8s est un opérateur open source qui implémente cette boucle pour vous : il surveille la file d’attente, prend en charge les sessions en attente et exécute chacune d’elles sous forme de pod worker sur n’importe quel cluster certifié (GKE, EKS, …). Installez-le avec son chart Helm au lieu de créer votre propre orchestrateur.

​
Le flux de travail principal

​
  1. Enregistrer un outpost

Un outpost est une file d’attente de sessions identifiée par un nom, gérée par de nombreux workers sur votre infrastructure (par exemple, rhel, gpu-h200 ou my-outpost). Créez-le avec devin worker outpost create:
Une fois enregistré, l’outpost apparaît parmi les options de machine dans Devin Cloud (aux côtés d’Ubuntu, Windows, etc.) au démarrage d’une session. Les sessions qui le ciblent attendent dans sa file d’attente jusqu’à ce qu’un worker les prenne en charge.
Dans la fleet API, les outposts sont représentés par des ressources outposts, dans le périmètre de votre compte (partagées entre toutes ses organisations). Consultez les endpoints des outposts.

​
  1. Point de surveillance de la fleet API pour les sessions en attente

Votre orchestrateur liste les sessions en attente pour les outposts qu’il prend en charge :
Ensuite, il maintient sa vue à jour au moyen d’un point de surveillance SSE (Server-Sent Events), en reprenant depuis le curseur final de la liste :
Il s’agit du schéma standard de Kubernetes consistant à lister puis à surveiller : parcourez la liste page par page à l’aide du curseur de réponse, puis démarrez un point de surveillance là où la liste s’est arrêtée, en conservant le curseur de chaque événement afin de pouvoir vous reconnecter sans manquer de modification. La livraison est garantie au moins une fois ; effectuez donc un upsert par metadata.session_id et acceptez les doublons. Consultez Lister les sessions en file d’attente et Point de surveillance des modifications pour les paramètres de requête, les structures de réponse et la sémantique complète de la pagination.

​
  1. Prise en charge avant le provisionnement

Avant de démarrer une machine pour une session, prenez-la en charge de manière atomique afin qu’aucun autre worker ne la récupère. Transmettez un acceptor_id — un identifiant déclaré par votre worker lui-même :
La prise en charge est atomique : si un autre worker a pris en charge la session en premier, vous recevez un 409. La prise en charge garantit qu’un worker sera prêt avant l’échéance de prise en charge attribuée par le serveur (status.claim_deadline) ; les prises en charge expirées retournent automatiquement dans la file d’attente. Si le provisionnement échoue, libérez la prise en charge afin que la session retourne immédiatement dans la file d’attente.

​
  1. Lancer une machine et exécution du worker

Pour chaque session prise en charge, provisionnez une VM ou un conteneur à partir de votre image. À l’intérieur, procédez à l’exécution du worker depuis le répertoire dans lequel vous souhaitez que la session travaille — ses dépôts se trouvent dans le sous-répertoire repos de ce répertoire, c’est-à-dire $(pwd)/repos/<repo-name> :
Transmettez le même --acceptor-id que celui utilisé pour la prise en charge via l’API, et fournissez le token via --token ou DEVIN_OUTPOSTS_TOKEN (voir la liste complète des options). Le worker établit une connexion vers le cloud de Devin, marque la session comme prête et commence à exécuter des appels d’outil.

​
  1. Arrêter la machine lorsque l’agent d’exécution s’arrête

Lorsque devin worker start s’arrête, la session est terminée (ou suspendue). Arrêtez la VM ou le conteneur. Si votre outpost permet la reprise, créez un snapshot de la machine avant de l’arrêter afin de pouvoir la restaurer si la session reprend.

​
Répertoires à conserver

Une session suspendue peut être reprise plus tard, et elle s’attend alors à retrouver ses fichiers là où elle les a laissés. Restaurez ces répertoires avant de démarrer l’agent d’exécution d’une session reprise : Un snapshot de la machine entière couvre les deux. Si vous ne conservez qu’une partie du système de fichiers (par exemple un volume pour le répertoire personnel), assurez-vous que les deux répertoires s’y trouvent et, lors de la reprise, démarrez l’agent d’exécution dans le même répertoire de travail. Au démarrage d’une session, Devin écrit un petit fichier témoin pour celle-ci dans chacun de ces répertoires : .devin-outpost-stamps/<session_id> dans le répertoire de travail et outpost_stamp dans le répertoire d’état de la session. Si un fichier témoin est absent à la reprise de la session, c’est que le répertoire correspondant n’a pas été conservé ; Devin publie alors dans la session un avertissement indiquant lequel. Une reprise à partir d’une machine vierge n’est pas adaptée à un usage en production : la session perd ses checkouts, son travail non validé et les dépendances installées. Votre orchestrateur peut suivre les sessions qu’il a prises en charge ainsi que leurs états :
Chaque entrée renvoie un status.session_status dont la valeur est pending, running, suspended ou terminated.

​
Planification sans centralisation

Vous prévoyez d’exécuter plus de ~16 coordinateurs (workers ou orchestrateurs qui surveillent un outpost et y prennent en charge des sessions) ? Contactez d’abord votre équipe en charge du compte — des flottes plus importantes amplifient la contention sur les prises en charge et la charge de lecture de la file, et nous voulons nous assurer que l’outpost est correctement dimensionné pour cela.
Vous n’avez pas besoin d’un ordonnanceur central pour faire tourner une flotte. L’API de la file d’attente est conçue pour que de nombreux workers indépendants puissent servir le même outpost sans communiquer entre eux :
  • Les prises en charge sont l’unique mécanisme de coordination. Chaque worker surveille la file de manière indépendante et entre en concurrence pour prendre en charge les sessions en attente. La prise en charge est un compare-and-swap atomique sur le serveur : un seul worker l’emporte, et tous les autres reçoivent un 409 puis passent simplement à la session en attente suivante. Perdre la course à la prise en charge fait partie du fonctionnement normal, ce n’est pas une erreur.
  • Chaque worker a sa propre identité. L’acceptor_id limite à ce seul worker ses prises en charge, ses renouvellements et sa récupération après redémarrage. devin worker start en génère et en conserve automatiquement un par machine, donc une flotte n’a besoin d’aucune configuration d’identité. Ne partagez jamais un ID d’acceptor (ni un répertoire de données de worker copié) entre plusieurs machines — des workers en collision se voleront mutuellement leurs prises en charge.
  • Les défaillances se résorbent d’elles-mêmes. Si un worker s’arrête après avoir pris en charge une session, sa prise en charge expire à l’échéance de prise en charge et la session revient dans la file pour qu’un autre worker la récupère. Aucun suivi de l’état de santé à l’échelle de la flotte n’est nécessaire.
Autrement dit, monter en charge consiste simplement à exécuter le worker sur davantage de machines pointant vers le même outpost : N machines servent N sessions simultanées, et le reste attend dans la file.

​
Créer un orchestrateur personnalisé

Tout ce que fait devin worker start est disponible directement via la fleet API, vous pouvez donc remplacer entièrement la CLI : récupérez le binaire devin-remote à partir de la distribution statique de Devin et lancez-le vous-même avec l’environnement documenté. Consultez Distribution du binaire distant et le contrat de spawn dans la documentation de référence.