Exécutions

Une exécution est un agent qui travaille sur une tâche dans sa propre microVM. Vous envoyez un prompt, une entrée JSON, ainsi que les fichiers et les connexions qu'il peut utiliser. Ephemeral la met en file d'attente, démarre une machine neuve, enregistre chaque étape et détruit la machine à la fin de l'exécution.

Ce qui compose une exécution

Chaque exécution a un prompt et, en option, une entrée. Le reste de la définition détermine le modèle utilisé, ce que l'agent peut lire et appeler, sa durée maximale et son budget. Vous pouvez envoyer toute la définition directement, ou désigner un workflow enregistré et n'envoyer que l'entrée.

{
  "prompt": "Find out why this payment failed. Follow the playbook.",
  "input": { "payment_id": "pay_123" },
  "model": "anthropic/claude-haiku-5.5",
  "files": [{ "file": "playbook.md" }],
  "connections": { "payments": { "ref": "payments-api", "allowed_methods": ["GET"] } },
  "timeout_seconds": 120,
  "shell": false,
  "max_cost_micros": 500000
}

Dans la microVM, l'agent peut toujours lire les fichiers que vous avez montés. Avec shell activé, ce qui est le cas par défaut, il peut aussi exécuter des commandes shell et écrire des fichiers dans son répertoire de travail. Chaque connexion accordée ajoute des outils qu'il peut appeler et, avec l'accès web activé, il peut lire des pages, faire des recherches et appeler des API publiques. La machine elle-même n'a pas accès à Internet. Le répertoire de travail disparaît avec la machine : rien n'est transmis à l'exécution suivante.

Cycle de vie

Une exécution passe par les statuts suivants. Les cinq derniers sont finals : une fois l'un d'eux atteint, le statut ne change plus.

Les exécutions sortent de la file d'attente dans l'ordre de leur création. Une installation auto-hébergée en exécute deux à la fois par défaut ; les autres restent en queued. Le délai d'expiration court à partir du moment où l'exécution quitte la file : le temps d'attente n'est donc pas décompté.

Limites

Suivre une exécution

Il existe trois façons de savoir ce que fait une exécution et quand elle se termine.

• Interroger GET /v1/runs/{id} jusqu'à ce que le statut soit final.
• Suivre GET /v1/runs/{id}/events. C'est un flux d'événements serveur (SSE) qui rejoue tout ce qui a été enregistré jusqu'ici, puis continue en direct jusqu'à la fin de l'exécution.
• Définir un callback sur l'exécution. Ephemeral envoie une requête signée à votre serveur lorsque l'exécution atteint un statut final.

Fermer le flux d'événements n'a aucun effet sur l'exécution. Vous pouvez vous reconnecter avec le dernier ID d'événement reçu et reprendre à partir de là.

Types d'événements

Ephemeral retire des événements et de la sortie les valeurs d'identifiants connues, comme les jetons de connexion, avant de les stocker. La référence de l'API détaille le format exact du flux.

Annuler une exécution

POST /v1/runs/{id}/cancel arrête une exécution en statut reserving, queued, starting ou running. Le worker est arrêté et la microVM est terminée. Annuler une exécution déjà terminée ne change rien.

Rétention zéro des données

Définissez zero_data_retention sur true pour une exécution, ou dans un workflow enregistré, lorsque la tâche est sensible. Ephemeral n'enregistre alors rien du contenu de l'exécution : vous ne recevez que la sortie.

• Les événements sont toujours diffusés pendant que l'exécution travaille, avec GET /v1/runs/{id}/events sur n'importe quel moteur. Ils sont conservés dans un stockage transitoire et supprimés quelques minutes après la fin de l'exécution.
• La sortie est renvoyée une seule fois. Le premier GET /v1/runs/{id} après la fin de l'exécution l'inclut et la supprime. Avec un callback, c'est lui qui livre la sortie, et les lectures la laissent en place d'ici là. Dans tous les cas elle est supprimée au plus tard après une heure. output_available et output_expires_at indiquent si elle est encore conservée.
• Les appels au modèle ne vont qu'à des fournisseurs qui ne conservent pas vos données et ne s'en servent pas pour l'entraînement. Un modèle sans fournisseur de ce type est refusé avec 400 avant toute réservation.
• Sur le service hébergé, l'exécution coûte 10 % de plus : le supplément s'applique au calcul, aux appels au modèle et aux requêtes web, compte dans le budget et apparaît dans le détail du coût. Les installations auto-hébergées ne facturent rien en plus.
• Les données transitoires se trouvent dans des tables que toutes les sauvegardes omettent ; une base restaurée ne les contient donc jamais.

Après une exécution

L'exécution conserve sa sortie, son message d'erreur, ses horodatages, ses événements et son coût. Considérez le coût comme définitif lorsque le statut est final et que billing_pending vaut false ; voir budgets et facturation.

Les exécutions terminées sont supprimées 30 jours après leur fin, avec leurs événements. Une exécution est conservée plus longtemps tant que sa facturation, l'envoi de son callback ou le nettoyage de sa microVM sont en attente. Les installations auto-hébergées peuvent modifier la durée de conservation.

Pour relancer la même tâche, récupérez GET /v1/runs/{id}/definition. Cet endpoint renvoie la définition réellement utilisée par l'exécution, sans les identifiants : vous pouvez la relire, fixer un nouveau budget et la soumettre.