Vai al contenuto principale
Un orchestratore monitora l’API di Outposts per le sessioni in attesa su un outpost, esegue il provisioning di una VM o di un container per ciascuna e avvia al suo interno il worker. Questa pagina descrive il ciclo di orchestrazione: polling della coda, rivendicazione delle sessioni, esecuzione dei worker e rimozione delle macchine. Se vuoi semplicemente gestire sessioni da una macchina che hai già, inizia dalla guida rapida — non serve alcun orchestratore. Se esegui su una piattaforma supportata, un’integrazione potrebbe già implementare questo ciclo per te. Per la documentazione completa di API e CLI, consulta il riferimento.
Usi Kubernetes? devin-outpost-k8s è un operatore open source che implementa questo ciclo per te: monitora la coda, rivendica le sessioni in attesa ed esegue ciascuna di esse come pod worker su qualsiasi cluster certificato (GKE, EKS, …). Installalo con il suo chart Helm invece di creare il tuo orchestratore.

​
Il flusso principale

​
1. Registra un outpost

Un outpost è una coda di sessioni denominata, gestita da più worker nella tua infrastruttura (ad esempio, rhel, gpu-h200 o my-outpost). Creane uno con devin worker outpost create:
Una volta registrato, l’outpost appare come opzione di macchina in Devin Cloud (insieme a Ubuntu, Windows, ecc.) all’avvio di una sessione. Le sessioni indirizzate a quell’outpost restano in attesa nella sua coda finché un worker non le prende in carico.
Nell’API della flotta, gli outpost sono rappresentati come risorse outposts, nell’ambito del tuo account (condivise tra tutte le sue organizzazioni). Vedi gli endpoint degli outpost.

​
2. Monitora l’API della flotta per individuare le sessioni in attesa

L’orchestratore elenca le sessioni in sospeso per gli outpost che gestisce:
Poi mantiene aggiornata la visualizzazione tramite un monitoraggio con Server-Sent Events (SSE), riprendendo dal cursor finale dell’elenco:
Questo segue il pattern standard di Kubernetes list-then-watch: scorri l’elenco pagina per pagina con il cursore della risposta, quindi avvia un watch dal punto in cui l’elenco si è fermato, salvando il cursore di ogni evento così da poterti riconnettere senza perdere modifiche. La consegna è di tipo at-least-once, quindi esegui l’upsert in base a metadata.session_id e tollera i duplicati. Consulta List queued sessions e Watch for changes per i parametri di query, le strutture di risposta e la semantica completa della paginazione.

​
3. Rivendica prima del provisioning

Prima di avviare una macchina per una sessione, rivendicala in modo atomico, così nessun altro worker potrà prenderla in carico. Passa un acceptor_id, ovvero un’identità autodichiarata del tuo worker:
Le operazioni di rivendicazione sono atomiche: se un altro worker ha già rivendicato la sessione, si riceve un 409. Rivendicare garantisce che un worker sarà pronto entro la scadenza della rivendicazione assegnata dal server (status.claim_deadline); le rivendicazioni scadute tornano automaticamente in coda. Se il provisioning non riesce, rilascia la rivendicazione in modo che la sessione torni immediatamente in coda.

​
4. Avvia una macchina ed esegui il worker

Per ogni sessione rivendicata, esegui il provisioning di una VM o di un container a partire dalla tua immagine. Al suo interno, esegui il worker dalla directory in cui è già stato eseguito il checkout dei repository della sessione:
Passa lo stesso --acceptor-id che hai usato per la rivendicazione tramite API e fornisci il token tramite --token o DEVIN_OUTPOSTS_TOKEN (consulta l’elenco completo dei flag). Il worker si connette al cloud di Devin, contrassegna la sessione come pronta e inizia a eseguire le tool call.

​
5. Terminare la macchina quando il worker termina

Quando devin worker start termina, la sessione è conclusa (o è stata sospesa). Termina la VM o il container. Se il tuo outpost supporta la ripresa, crea uno snapshot della macchina prima di terminarla, così potrai ripristinarla se la sessione riprende. Il tuo orchestrator può tenere traccia delle sessioni rivendicate e del loro stato:
Ogni voce riporta status.session_status con valore pending, running, suspended o terminated.

​
Pianificazione senza centralizzazione

Hai in programma di eseguire più di ~16 coordinatori (worker o orchestratori che monitorano e rivendicano sessioni da un outpost)? Contatta prima il team del tuo account: flotte più grandi aumentano la contesa sulle rivendicazioni e il carico di lettura della coda, e vogliamo assicurarci che l’outpost sia dimensionato adeguatamente.
Non serve un pianificatore centrale per eseguire una flotta. L’API della coda è progettata in modo che molti worker indipendenti possano servire lo stesso outpost senza comunicare tra loro:
  • Le rivendicazioni sono l’unico meccanismo di coordinamento. Ogni worker monitora la coda in modo indipendente e compete per rivendicare le sessioni in attesa. La rivendicazione è un’operazione atomica di compare-and-swap sul server: vince un solo worker, mentre tutti gli altri ricevono un 409 e passano semplicemente alla sessione in attesa successiva. Perdere la corsa alla rivendicazione è un comportamento normale, non un errore.
  • Ogni worker ha una propria identità. acceptor_id limita le rivendicazioni, i rinnovi e il ripristino dopo il riavvio al solo worker a cui appartiene. devin worker start ne genera e memorizza automaticamente uno per ogni machine, quindi una flotta non richiede alcuna configurazione dell’identità. Non condividere mai un acceptor ID (o una directory dati del worker copiata) tra machine diverse: worker in conflitto si sottrarrebbero a vicenda le rivendicazioni.
  • Gli errori si risolvono automaticamente. Se un worker si arresta dopo aver rivendicato una sessione, la sua rivendicazione scade alla claim deadline e la sessione torna nella coda perché un altro worker la possa recuperare. Non è necessario alcun monitoraggio dello stato di salute a livello di flotta.
Questo significa che per scalare orizzontalmente basta eseguire il worker su più machine che puntano allo stesso outpost: N machine servono N sessioni simultanee, mentre le altre restano in attesa.

​
Creare un orchestratore personalizzato

Tutto ciò che fa devin worker start è disponibile direttamente tramite l’API della flotta, quindi puoi sostituire completamente la CLI: scarica il file binario devin-remote dalla distribuzione statica di Devin e avvialo direttamente con l’ambiente documentato. Consulta Distribuzione remota del binario e il contratto di spawn nella documentazione di riferimento.