Workflows

Un workflow est une définition d'exécution enregistrée sous un nom. Il contient le prompt, le modèle, les fichiers, les connexions, le délai d'expiration et les réglages de shell et d'accès web. Votre code le lance par son nom et n'envoie que ce qui change d'une exécution à l'autre.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "max_cost_micros": 500000
}

Ce qui est enregistré et ce que chaque exécution envoie

Enregistrez un workflow dans le tableau de bord, sous Workflows, avec PUT /v1/workflows/{name} ou avec ephemeral workflows save. Le format d'échange est le JSON ; la CLI lit aussi le YAML. Les noms commencent par une lettre ou un chiffre et peuvent contenir des lettres, des chiffres, _, . et -, jusqu'à 128 caractères.

Remplacer des champs enregistrés

Tout champ parmi prompt, model, files, connections, timeout_seconds, shell et web présent dans la requête d'exécution remplace la valeur enregistrée, pour cette exécution seulement. Les fichiers et les connexions sont remplacés en bloc, en tant que collection entière : ils ne sont jamais fusionnés avec ceux qui sont enregistrés.

{
  "workflow": "investigate-payment",
  "input": { "payment_id": "pay_123" },
  "connections": {},
  "max_cost_micros": 500000
}

Un objet ou un tableau vide vide la collection pour cette exécution. Pour modifier une seule connexion ou un seul fichier, envoyez la liste complète que l'exécution doit avoir.

Quand les références sont résolues

Un workflow désigne les fichiers et les connexions enregistrées par leur nom. Ephemeral résout ces noms à la création de l'exécution, et l'exécution conserve le résultat. Un nom de fichier correspond à l'import le plus récent portant ce nom : importer une nouvelle version de playbook.md change donc ce que lira la prochaine exécution, sans modifier le workflow.

Si un fichier ou une connexion référencé n'existe plus, la requête d'exécution échoue avec 400 et nomme la référence manquante. Rien n'est mis en file d'attente et rien n'est facturé.

Décrire l'entrée et la sortie

Trois champs facultatifs permettent à un workflow de se décrire lui-même, afin que les personnes, d'autres programmes et les agents IA sachent comment l'appeler sans lire son prompt. description dit en une ou deux phrases ce que fait le workflow et quelle entrée il attend (500 caractères au maximum). input_schema est un JSON Schema auquel l'input de l'exécution doit correspondre. output_schema est un JSON Schema auquel la sortie de l'exécution doit correspondre. Les trois sont renvoyés par GET /v1/workflows?detail=true et par l'outil MCP list_workflows, et ils fonctionnent aussi sur une exécution en ligne.

description: Current weather for a city. Input is a city name.
prompt: Look up the current weather for the city in the input and report it.
web: true
input_schema:
  type: object
  required: [city]
  properties:
    city: { type: string }
output_schema:
  type: object
  required: [city, temperature_c, summary]
  properties:
    city: { type: string }
    temperature_c: { type: number }
    summary: { type: string }

L'entrée est vérifiée à la création d'une exécution, qu'elle vienne de l'API, de la CLI, d'un outil MCP ou d'une planification. Si elle ne correspond pas, la requête échoue avec 400 et nomme chaque problème sous la forme d'un chemin et d'une raison, par exemple input.city: required. Rien n'est mis en file d'attente et rien n'est facturé. L'entrée d'une planification est vérifiée quand vous la créez ou la modifiez, puis à chaque lancement ; un lancement qui ne correspond plus est consigné comme la dernière erreur de la planification.

La sortie doit être du JSON conforme à output_schema. L'agent reçoit le schéma et doit répondre uniquement avec le JSON. Si sa réponse ne correspond pas, il reçoit les erreurs exactes et doit la corriger, jusqu'à deux fois. Ephemeral vérifie ensuite à nouveau la sortie : si elle correspond, l'exécution reste succeeded, avec le texte JSON comme sortie et sans bloc de code autour. Sinon, l'exécution se termine en failed avec une error comme output did not match output_schema: output.temperature_c: got string, want number, et le texte de la sortie est conservé pour que vous voyiez ce que l'agent a écrit. Une exécution à rétention zéro des données ne conserve aucun détail dans l'erreur.

Les schémas utilisent JSON Schema draft 2020-12 (un $schema qui désigne le draft 7 ou un plus ancien fonctionne aussi), de 32 Kio au plus chacun, et ne peuvent renvoyer qu'à des définitions du schéma lui-même, comme #/$defs/address. Un schéma invalide est refusé avec 400 à l'enregistrement du workflow ou à la création de l'exécution.

Modifier un workflow

Enregistrer de nouveau un workflow le remplace. Il n'y a pas d'historique des versions. Les exécutions créées avant la modification conservent la définition avec laquelle elles ont été créées ; pour voir exactement ce qu'une exécution a utilisé, lisez sa définition.

La lecture d'un workflow le renvoie sans les identifiants de connexion ni les secrets d'URL. Si vous le réenregistrez en omettant ces champs, les identifiants stockés sont conservés tant que le type d'authentification reste le même.