> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestration

> Provisionner des machines et exécuter automatiquement des workers à mesure que les sessions arrivent dans la file d’attente

Un orchestrateur surveille l’API Outposts pour repérer les sessions en attente sur un outpost, provisionne une VM ou un container 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, récupération des sessions, exécution des workers et arrêt des machines.

Si vous voulez simplement servir des sessions depuis une machine dont vous disposez déjà, commencez par le [quickstart](/fr/onboard-devin/outposts/quickstart) — aucun orchestrateur n’est nécessaire. Si vous utilisez une plateforme prise en charge, une [intégration](/fr/onboard-devin/outposts#integrations) 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](/fr/onboard-devin/outposts/reference).

<Note>
  Vous utilisez Kubernetes ? [devin-outpost-k8s](https://github.com/CognitionAI/devin-outpost-k8s)
  est un opérateur open source qui implémente cette boucle pour vous : il surveille la
  file d’attente, récupère les sessions en attente et exécute chacune
  d’elles sous la forme d’un pod worker sur n’importe quel cluster
  certifié (GKE, EKS, ...). Installez-le avec son chart Helm au lieu de
  développer votre propre orchestrateur.
</Note>

<div id="the-core-flow">
  ## Le flux principal
</div>

<div id="1-register-an-outpost">
  ### 1. Enregistrer un outpost
</div>

Un outpost est une file d’attente de sessions nommée, gérée par plusieurs workers sur votre infrastructure (par exemple, `rhel`, `gpu-h200` ou `my-outpost`). Créez-en un avec `devin worker outpost create` :

```bash theme={null}
devin worker outpost create <name> --platform <platform> --description "..."
```

Une fois enregistré, l’outpost apparaît comme une option de machine dans Devin Cloud (aux côtés d’Ubuntu, Windows, etc.) lors du démarrage d’une session. Les sessions destinées à cet outpost attendent dans sa file d’attente jusqu’à ce qu’un worker les prenne en charge.

<Note>
  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](/fr/onboard-devin/outposts/reference#outposts).
</Note>

<div id="2-watch-the-fleet-api-for-waiting-sessions">
  ### 2. Surveiller la fleet API pour repérer les sessions en attente
</div>

Votre orchestrateur répertorie les sessions en attente pour les outposts qu’il gère :

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&phase=pending"
```

Ensuite, il maintient cette vue à jour grâce à une surveillance par Server-Sent Events (SSE), en reprenant depuis le curseur final de la liste :

```bash theme={null}
curl -N -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?outpost=<outpost_id>&watch=true&cursor=<cursor>"
```

Il s’agit du modèle standard Kubernetes de type `list-then-watch` : parcourez la liste page par page avec le curseur de réponse, puis démarrez une surveillance à partir de l’endroit où la liste s’est arrêtée, en conservant le curseur de chaque événement afin de pouvoir vous reconnecter sans manquer de modifications. La livraison suit une sémantique d’au moins une fois ; effectuez donc un upsert par `metadata.session_id` et acceptez les doublons. Consultez [Lister les sessions en file d’attente](/fr/onboard-devin/outposts/reference#list-queued-sessions) et [Surveiller les modifications](/fr/onboard-devin/outposts/reference#watch-for-changes) pour les paramètres de requête, les formats de réponse et la sémantique complète de la pagination.

<div id="3-claim-before-provisioning">
  ### 3. Prise en charge avant le provisionnement
</div>

Avant de démarrer une machine pour une session, prenez-la en charge de façon atomique afin qu’aucun autre worker ne la récupère. Fournissez un `acceptor_id` — une identité autodéclarée de votre worker :

```bash theme={null}
curl -X POST -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"acceptor_id": "worker-1"}' \
  "https://api.devin.ai/opbeta/outposts/devins/{session_id}/claim"
```

Les prises en charge sont atomiques : 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 dans le délai de prise en charge défini 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](/fr/onboard-devin/outposts/reference#release-a-claim) afin que la session retourne immédiatement dans la file d’attente.

<div id="4-spawn-a-machine-and-run-the-worker">
  ### 4. Lancer une machine et démarrer le worker
</div>

Pour chaque session prise en charge, créez une VM ou un conteneur à partir de votre image. Dans celui-ci, démarrez le worker depuis le répertoire où les dépôts de la session sont déjà clonés :

```bash theme={null}
cd /path/to/repos
devin worker start --session=<session_id> --outpost=<outpost_id> --acceptor-id=<worker_id>
```

Passez le même `--acceptor-id` que celui utilisé pour la prise en charge API, et fournissez le jeton via `--token` ou `DEVIN_OUTPOSTS_TOKEN` (voir la [liste complète des options](/fr/onboard-devin/outposts/reference#devin-worker-start)). Le worker établit une connexion sortante vers le cloud de Devin, marque la session comme prête et commence à exécuter des appels d’outil.

<div id="5-terminate-the-machine-when-the-worker-exits">
  ### 5. Arrêter la machine lorsque le worker s'arrête
</div>

Lorsque `devin worker start` s'arrête, la session est terminée (ou a été suspendue). Arrêtez la VM ou le conteneur. Si votre outpost peut reprendre une session, effectuez un snapshot de la machine avant de l'arrêter afin de pouvoir la restaurer si la session reprend.

Votre orchestrateur peut suivre les sessions qu'il a prises en charge et leurs états :

```bash theme={null}
curl -H "Authorization: Bearer $DEVIN_API_TOKEN" \
  "https://api.devin.ai/opbeta/outposts/devins?phase=claimed&acceptor_id=worker-1"
```

Chaque entrée a un `status.session_status` égal à `pending`, `running`, `suspended` ou `terminated`.

<div id="centralization-free-scheduling">
  ## Planification sans centralisation
</div>

<Note>
  Vous prévoyez d’exécuter plus de \~16 coordinateurs (workers ou orchestrateurs
  qui surveillent un outpost et y prennent des sessions en charge) ? Contactez d’abord l’équipe en charge de votre 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.
</Note>

Vous n’avez pas besoin d’un ordonnanceur central pour exploiter une flotte. L’API de file d’attente est conçue pour que de nombreux workers indépendants puissent servir le même outpost sans avoir à communiquer entre eux :

* **Les prises en charge sont le seul mécanisme de coordination.** Chaque worker surveille la file d’attente 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 une course à la prise en charge est un comportement normal, pas une erreur.
* **Chaque worker a sa propre identité.** `acceptor_id` associe les prises en charge, les renouvellements et la reprise après redémarrage d’un worker à ce worker uniquement. `devin worker start` en génère une automatiquement par machine et la stocke de façon persistante, si bien qu’une flotte n’a besoin d’aucune configuration d’identité. Ne partagez jamais un identifiant d’acceptor (ni un répertoire de données de worker copié) entre plusieurs machines — des workers en conflit se voleront mutuellement leurs prises en charge.
* **Les défaillances se corrigent d’elles-mêmes.** Si un worker s’arrête après avoir pris une session en charge, sa prise en charge expire à la deadline de prise en charge et la session retourne dans la file d’attente 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.

Cela signifie que faire évoluer horizontalement la flotte consiste simplement à exécuter le worker sur davantage de machines pointant vers le même outpost : N machines servent N sessions simultanées, et les autres restent en attente.

<div id="building-a-custom-orchestrator">
  ## Créer un orchestrateur personnalisé
</div>

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` depuis la distribution statique de Devin et lancez-le vous-même avec l’environnement décrit dans la documentation. Consultez [Distribution du binaire distant](/fr/onboard-devin/outposts/reference#remote-binary-distribution) et le [contrat de spawn](/fr/onboard-devin/outposts/reference#spawn-contract) dans la documentation de référence.