Contexte : agents IA, découvrez les conteneurs de tâches

Les conteneurs de tâches sont désormais disponibles pour tous sur Upsun Cloud, ce qui te permet d’exécuter des agents IA aux côtés du reste de ton application. L’agent s’exécute sous forme de conteneur au sein de ton projet Upsun Cloud, à côté de l’application sur laquelle il travaille, avec le même accès à ton environnement et à tes données que tout ce qui y est déployé. C’est le cycle de vie qui est nouveau : il s’adapte au comportement des charges de travail des agents au lieu de les forcer à se faire passer pour des serveurs.

Quelques précisions d’emblée :

Il s’agit d’un guide pratique. Si tu souhaites une présentation plus générale des fonctionnalités, lis d’abord « Conteneurs de tâches : exécution jusqu’à la fin sur Upsun ».

Le conteneur de tâches est, par conception, une primitive d’exécution épurée. Il n’y a ni passerelle IA, ni LLM géré, ni interface d’orchestration superposée : tu fournis le code de l’agent, les clés LLM et le déclencheur. C’est un choix délibéré : un environnement d’exécution flexible reste utile quel que soit le modèle, le framework ou le modèle d’agent que tu utilises, plutôt que de te verrouiller dans ce que nous aurions intégré.

Avant de commencer

Tu auras besoin :

• Un projet Upsun.
• Un runtime d’agent de ton choix. Il peut s’agir d’un framework comme LangChain, LlamaIndex ou AutoGen, ou d’un code développé en interne appelant directement une API LLM. Upsun ne limite pas ce choix.
• Une clé API pour le fournisseur de LLM que tu comptes utiliser. Enregistre-la comme variable de projet sensible dans Upsun, et non dans le code.
• Une réponse claire à la question « qu’est-ce qui doit déclencher cet agent ? ». La réponse détermine tout ce qui va suivre.

Si tu n’as pas encore de réponse à cette question, c’est par là qu’il faut commencer. Un agent IA sans déclencheur clairement défini est un processus qui cherche une excuse pour s’exécuter ; un agent avec un déclencheur précis est un élément d’infrastructure.

La structure d’un agent IA sur Upsun Cloud

Un agent peut s’exécuter dans un conteneur d’application ou un « worker », mais un conteneur de tâches offre généralement le meilleur modèle d’exécution. Définis l’agent comme une tâche, et il s’accompagnera de :

• Il est défini comme une entrée de premier niveau sous tasks: dans .upsun/config.yaml, au même titre que applications: et services:.
• Il dispose de sa propre image de conteneur et de sa propre étape de compilation, indépendantes de l’application. Tu peux installer n’importe quel environnement d’exécution Python, Node ou autre dont tu as besoin sans toucher à l’application principale.
• Il accède aux services du projet (bases de données, caches, files d’attente) via le modèle de relations standard.
• Il démarre lorsqu'il est déclenché via l'API Upsun Cloud, s'exécute jusqu'à la fin et est automatiquement supprimé lorsque la commande se termine.
• Il intègre d’emblée des délais d’expiration, des limites de ressources et la journalisation des activités.
• Un conteneur isolé, avec le même niveau d’isolation réseau que tes applications.

Le modèle mental à retenir : un agent est un bout de code chargé d’effectuer une tâche, pas un serveur. Considère-le comme une tâche ponctuelle qui, par hasard, appelle un LLM, et la plupart des questions de conception se résoudront d’elles-mêmes.

Exemple concret : un agent de triage des tickets d'assistance

Pour concrétiser tout ça, la suite de cet article te présente un agent de tri des tickets d’assistance. Le scénario :

Lorsqu’un nouveau ticket arrive, lance un agent qui lit son contenu, le classe selon tes catégories d’assistance, rédige une réponse et la renvoie vers le ticket pour qu’un humain puisse la relire ou l’envoyer.

Ce même modèle est généralisable. Remplace « triage des tickets » par « révision de code », « résumé d’incident » ou « contrôle de la qualité des données », et la structure ne change pratiquement pas.

Étape 1 : Définis l’agent comme une tâche

Dans « .upsun/config.yaml », ajoute un bloc « tasks: » au niveau supérieur. La tâche doit avoir un nom, une image de conteneur, une étape de build et une commande. Tu trouveras les références exactes des champs dans la documentation sur les conteneurs de tâches ; la structure conceptuelle est la suivante :

applications:
  api:
    # your long-running API

services:
  postgres:
    type: postgresql:16

tasks:
  ticket-triage-agent:
    type: python:3.14
    run:
      command: python agent.py

Trois choix sont importants ici. Choisis l’image de base minimale dont ton agent a besoin. Un agent Python utilisant une petite bibliothèque cliente LLM n’a pas besoin d’une image lourde, et un démarrage plus rapide signifie une réponse de bout en bout plus rapide. Installe les dépendances de ton agent pendant l’étape de construction plutôt qu’au moment de l’exécution, pour que la tâche soit prête à s’exécuter dès son lancement. Et veille à ce que la commande d’exécution soit un script unique et idempotent. Si l’agent doit réessayer, il doit le faire proprement, sans refaire le travail ni laisser quoi que ce soit à moitié terminé.

Étape 2 : Configurer le déclencheur

Sur Upsun Cloud, les tâches sont déclenchées via l’API de la plateforme, la console ou l’interface en ligne de commande (CLI). Pour le scénario de tri des tickets, le déclencheur est un webhook provenant de ton système de tickets qui se déclenche lorsqu’un nouveau ticket est créé.

Il existe deux modèles courants pour transformer un webhook en appel de tâche. Ton API existante peut recevoir directement le webhook GitHub, valider la signature, extraire le contexte pertinent (numéro de PR, dépôt, SHA de la base et de la tête), puis appeler l’API de Upsun Cloud pour lancer la tâche avec ces valeurs en paramètres. Ou bien, un gestionnaire léger dédié peut être créé uniquement pour recevoir les webhooks et lancer les tâches, ce qui est utile si tu veux garder l’application principale exempte de chemins de code liés à l’agent.

Pour un agent de triage des tickets, le premier modèle suffit généralement. Le gestionnaire ne fait que vingt lignes de code ; c’est dans l’agent lui-même que se déroule le travail intéressant.

Si ton déclencheur est une planification plutôt qu’un événement (un agent de nettoyage nocturne, par exemple), la même tâche peut être lancée depuis une application cron ou un planificateur externe. L’agent ne sait pas et ne se soucie pas de savoir lequel l’a appelé.

Étape 3 : Gérer les identifiants avec les autorisations de charge de travail

L’agent aura besoin d’identifiants, et il en existe deux types qui doivent être gérés différemment.

Les identifiants externes, comme la clé API de ton fournisseur de LLM et un jeton GitHub, sont stockés en tant que variables de projet Upsun Cloud. Ils sont accessibles à la tâche au moment de l’exécution sous forme de variables d’environnement. Traite-les comme n’importe quel autre secret : limités au projet, renouvelés régulièrement, jamais validés dans le dépôt.

Les identifiants de la plateforme Upsun Cloud, pour tous les cas où l’agent doit appeler lui-même l’API d’Upsun Cloud, relèvent des autorisations de charge de travail. La tâche demande à Upsun Cloud un jeton à courte durée de vie et à portée restreinte au moment de l’exécution, utilise ce jeton, puis le laisse expirer. Il n’y a pas d’identifiant de plateforme à longue durée de vie à renouveler, ni de secret partagé susceptible de fuiter dans les journaux.

Pour un agent de tri des tickets qui se contente de lire un ticket et d’y répondre, tu n’auras peut-être pas besoin d’autorisations de charge de travail du tout. Elles deviennent utiles dès que l’agent a besoin d’informations ou de fonctionnalités au niveau de la plateforme : interroger Upsun Cloud pour obtenir des métadonnées d’environnement, déclencher une tâche suivante ou marquer les résultats avec le contexte de la branche. La documentation sur les autorisations de charge de travail explique le flux de requêtes.

Étape 4 : Définis des limites avant de le laisser tourner sans surveillance

C’est l’étape que la plupart des tutoriels sur les agents sautent. Ne la saute pas.

Définis un délai d’expiration strict pour l’agent. La valeur par défaut est d’une heure, mais pour un agent de tri des tickets, tu devrais la réduire. Si une exécution n’est pas terminée au bout de cinq minutes, c’est qu’il y a un problème, et la bonne solution est de faire échouer la tâche et de l’enregistrer dans le journal plutôt que de la laisser continuer. Sans délai d’expiration, une boucle incontrôlée ou un appel LLM bloqué épuisera les ressources du conteneur jusqu’à ce qu’une intervention extérieure y mette fin.

Définis l'allocation de CPU et de mémoire du conteneur en fonction de la charge de travail réelle. Un agent effectuant un raisonnement via un LLM passe la plupart du temps à attendre la réponse de l'API du modèle ; il a donc rarement besoin d'une allocation importante.

Les agents exécutent des commandes générées par le modèle, et pour l’instant, les conteneurs de tâches n’offrent pas de limitation des sorties réseau ; tu ne peux donc pas encore restreindre l’accès réseau sortant d’une tâche à des points de terminaison spécifiques. En attendant que cette fonctionnalité soit disponible, considère les identifiants détenus par l’agent comme la véritable limite : ne lui accorde que l’accès dont il a besoin, car le conteneur lui-même ne limitera pas les destinations auxquelles il peut accéder. Associe ça à un bac à sable intégré au conteneur, comme bubblewrap, pour contrôler plus étroitement ce que le processus de l’agent peut réellement faire.

Chaque exécution de tâche dispose de son propre conteneur isolé, avec le même espace de noms et la même isolation réseau que tes applications. Pour un agent exécutant des commandes générées par un modèle, associe ça à un bac à sable intégré au conteneur, comme bubblewrap, afin de restreindre davantage le système de fichiers et les appels système visibles par le processus de l’agent. Par défaut, rien ne persiste entre les exécutions ; donc tout ce qui doit être conservé doit aller vers un service (Postgres, stockage d’objets), et non sur le disque local.

Une autre limite à prendre en compte : par défaut, Upsun Cloud exécute jusqu’à trois tâches simultanément par projet. Si ton dépôt reçoit un afflux de pull requests, les déclencheurs supplémentaires sont mis en file d’attente jusqu’à ce qu’un créneau se libère, plutôt que d’échouer d’emblée. Ça ne pose généralement pas de problème pour un agent de triage des tickets, puisque quelques minutes de retard dans une réponse ont rarement de l’importance, mais ça vaut le coup de le savoir avant qu’un après-midi chargé ne te fasse croire que quelque chose ne fonctionne pas.

C’est en maîtrisant ces points qu’on distingue un agent que tu peux laisser tourner tout seul de celui dont tu dois t’occuper en permanence.

Étape 5 : Rends les exécutions de l’agent vérifiables

La journalisation des activités est intégrée. La tâche enregistre ce qui a été exécuté, quand et avec quel statut. Ça couvre la vue opérationnelle.

Ce qu’elle ne couvre pas, c’est la vue interne de l’agent : quelles invites il a générées, quels outils il a appelés, quelles réponses de modèle il a reçues et ce qu’il a décidé de faire. Pour ça, tu dois instrumenter l’agent toi-même. Au minimum, enregistre les données d’entrée reçues par l’agent (numéro de PR, chemins d’accès aux fichiers, SHA des commits), chaque appel au LLM (le modèle, un hachage de la requête, la longueur de la réponse et le coût si tu le suis), chaque action externe effectuée par l’agent (appel d’API, commentaire publié, fichier écrit) et le résultat final.

Transmets ces données à l’outil d’observabilité que tu utilises déjà. Le but est de pouvoir reconstituer les exécutions de l’agent a posteriori, car le comportement des LLM évolue, et tu voudras savoir ce qu’un agent a réellement fait dans trois semaines.

Étape 6 : Lance-le et observe

Une fois la tâche définie, le déclencheur configuré, les identifiants en place et les limites fixées, ouvre une pull request et laisse l'agent s'exécuter. Surveille le journal d'activité. Lis les commentaires qu'il publie. Ajuste la prompt, les limites et les conditions de déclenchement au fur et à mesure que tu apprends.

Les dix premières exécutions sont les plus précieuses. Elles te permettent de savoir si ton périmètre est bien défini, si l’agent accède à des éléments auxquels il ne devrait pas avoir accès, et si la consigne fonctionne comme prévu sur des données réelles. Considère ce premier lot comme une phase d’étalonnage, pas comme un lancement.

Au-delà du tri des tickets : d’autres modèles d’agents

La présentation ci-dessus est générale. Voici quelques autres modèles d’agents qui s’intègrent parfaitement au conteneur de tâches :

• Agent de nettoyage nocturne. Déclenché par cron, il parcourt les environnements et les branches du projet, et supprime tout ce qui date de plus d’un seuil configurable. Il utilise les autorisations de charge de travail pour appeler l’API Upsun Cloud.
• L’agent d’investigation des incidents. Déclenché lorsqu’une métrique dépasse un seuil. Il extrait les logs pertinents, résume l’incident et publie un résumé sur un canal de chat. Utile pour fournir plus rapidement le contexte à l’ingénieur de garde.
• Agent de qualité des données. Déclenché une fois la tâche ETL nocturne terminée. Il lit des échantillons des nouvelles données, signale les anomalies et publie les résultats sur un tableau de bord.

Dans chaque cas, le principe est le même : un déclencheur arrive, l’agent s’exécute jusqu’au bout, le conteneur est supprimé. Ce qui change, c’est l’invite, les outils et la destination du résultat.

Ce que ça couvre

Le conteneur de tâches fournit l’environnement d’exécution ; c’est toi qui apportes l’agent : ton propre framework, ta connexion au LLM et la gestion des invites. C’est un choix délibéré. Les frameworks d’agents et les modèles d’orchestration évoluent d’un mois à l’autre, et une primitive qui ne t’enferme pas dans une technologie est bien meilleure que celle qui le fait.

Prêt à te lancer ? Rends-toi sur la documentation des conteneurs de tâches sur developer.upsun.com pour commencer.

Foire aux questions (FAQ)

Dois-je utiliser un framework d’agent spécifique ? 
Non. Le conteneur de tâches est indépendant de tout framework. Utilise LangChain, LlamaIndex, AutoGen, les SDK d’OpenAI ou d’Anthropic directement, ou ton propre code.

L’agent peut-il accéder à d’autres parties de mon projet Upsun cloud ? 
Oui. Les tâches ont accès aux services du projet (bases de données, caches, files d’attente, stockage d’objets) via des relations standard, de la même manière qu’une application ou un worker.

Comment l’agent communique-t-il avec l’API de Upsun Cloud ? 
Grâce à des autorisations de charge de travail. La tâche demande un jeton à durée de vie courte et à portée restreinte au moment de l’exécution, et l’utilise pour appeler l’API. Il n’y a pas d’identifiants de plateforme à longue durée de vie dans l’environnement de l’agent.

Que se passe-t-il si l’agent s’exécute plus longtemps que le délai d’expiration ? 
La tâche est interrompue et l’échec est consigné dans le journal d’activité. Le délai d’expiration par défaut est d’une heure ; le maximum est d’un jour. Définis le délai d’expiration sur une valeur qui couvre largement l’exécution légitime la plus lente tout en empêchant les boucles incontrôlées.

Est-ce que je peux exécuter plusieurs agents dans le même projet ? 
Oui. Chaque agent a sa propre entrée dans tasks:, avec sa propre image, son étape de compilation et sa commande.

Combien d’exécutions d’agents peuvent avoir lieu en même temps ? 
Trois par défaut, par projet. Les déclencheurs supplémentaires sont mis en file d’attente jusqu’à ce qu’un créneau se libère, au lieu d’échouer.

Où puis-je voir ce que l’agent a réellement fait ? Les journaux 
d’activité affichent l’état au niveau des tâches et les journaux en continu. Les décisions internes à l’agent (invites, appels d’outils, réponses du modèle) doivent être consignées depuis le code de l’agent. Ces deux points de vue sont importants.