Aller au contenu
AdiosDocumentation
Parcourir la documentation

Workflows

Adios Workflows relie API, scripts, bases de données, e-mails, stockage d’objets et agents IA dans une suite d’actions suivies. Lancez une exécution manuellement, à partir d’un webhook ou d’un événement, ou à intervalles réguliers. Ajoutez une approbation humaine avant une action qui nécessite une vérification.

Commencez par un exemple complet : traiter un webhook, envoyer un rapport planifié, ou vérifier avant publication. La présentation des workflows comprend aussi des exemples S3 et de scripts.

Sur cette page : manifeste, déclencheurs, les dix actions, sorties et dépendances, secrets et variables d’environnement, et créer et inspecter.

Manifeste de workflow

Un manifeste de workflow décrit les déclencheurs, le contexte partagé et les étapes ordonnées. Dans un dépôt dédié aux workflows, vous pouvez nommer le fichier adios.yaml. Dans un dépôt d’application, conservez le manifeste de l’environnement d’exécution à la racine du projet et les manifestes de workflow dans un répertoire tel que workflows/.

workflow_id: daily-market-brief
title: Daily market brief
team_id: team-local
enabled: true
version: "1"

triggers:
  - type: schedule
    interval: 24h
  - type: webhook
    event: market.brief.requested

context:
  market_api_url: https://api.example.com
  symbols:
    - AAPL
    - MSFT
    - NVDA

steps:
  - step_id: fetch-prices
    name: Fetch prices
    kind: http
    command:
      method: GET
      url: "{{ .context.market_api_url }}/quotes?symbols=AAPL,MSFT,NVDA"
      headers:
        X-API-Key: secret://MARKET_DATA_API_KEY

  - step_id: select-close
    name: Select close prices
    kind: data-json
    dependencies:
      - fetch-prices
    command:
      from_step: fetch-prices
      path: ".quotes"

  - step_id: publish-brief
    name: Publish brief
    kind: http
    dependencies:
      - select-close
    command:
      method: POST
      url: https://dashboard.example.com/api/market-briefs
      body: "{{ index .steps \"select-close\" \"output\" }}"

Remplacez team-local par l’identifiant de votre équipe, configurez les points de terminaison API et créez MARKET_DATA_API_KEY dans les secrets Adios avant de déployer cet exemple. L’API source attend un en-tête X-API-Key ; sa destination reçoit les cotations sélectionnées au format JSON. La planification s’exécute une fois par jour à 00:00 UTC. Supprimez triggers pour un test uniquement manuel avant d’activer l’envoi récurrent.

Déclencheurs et planification

  • Manuel : lancez une exécution depuis Workflows ou avec adios workflow run. Un workflow sans triggers ne s’exécute que de cette façon.
  • Webhook : utilisez type: webhook et un nom d’événement, par exemple order.created. Les données de l’événement entrant sont disponibles sous .payload.
  • Événement : utilisez type: event et le nom de l’événement interne doivent correspondre.
  • Cron: utilisez type: cron avec une expression à cinq champs telle que cron: "0 8 * * 1-5". Ajoutez timezone: Europe/Berlin pour s’exécuter à une heure locale ; sans lui, cron utilise UTC.
  • Intervalle: utilisez type: schedule avec une durée telle que interval: 1h ou interval: 24h. cron: "@every 1h" équivaut à interval: 1h.
triggers:
  - type: cron
    cron: "0 8 * * 1-5"
    timezone: Europe/Berlin
    concurrency: forbid

Les intervalles s’alignent sur les limites UTC, donc interval: 24h s’exécute une fois par jour à 00:00 UTC, et non 24 heures après votre déploiement. Utilisez cron avec un timezone lorsque vous avez besoin d’une heure locale précise. Le planificateur vérifie les créneaux échus environ toutes les 30 secondes. Les créneaux manqués pendant l’arrêt du planificateur sont ignorés, et non rejoués.

Définissez concurrency: forbid pour ignorer un créneau planifié tant qu’un événement antérieur du même déclencheur est encore en attente ou qu’une exécution attend une approbation. Le créneau ignoré est enregistré comme un événement ignoré. Si une exécution répétée pouvait encore envoyer des rapports ou des écritures en double, dédupliquez dans votre application ou votre destination.

Points de terminaison webhook publics

Définissez public: true sur un webhook ou event pour recevoir des requêtes HTTP provenant de l’extérieur d’Adios :

triggers:
  - type: webhook
    event: order.created
    public: true
    public_path_pattern: /hooks/orders/{order_id}
    public_methods: [POST]
    public_hosts: [api.example.com]
    public_secret_ref: secret://ORDER_WEBHOOK_SECRET
    response_mode: queued_json
  • public_path_pattern est obligatoire. Les segments entre accolades, tels que {order_id}, sont capturés comme paramètres de chemin.
  • public_methods et public_hosts limitent les requêtes concernées. Omettez-les pour accepter n’importe quelle méthode ou n’importe quel hôte.
  • public_secret_ref oblige l’appelant à envoyer la valeur du secret dans l’en-tête X-Workflow-Secret. Les requêtes sans la valeur correspondante sont rejetées.
  • response_mode définit la réponse. queued_json (par défaut) et async_json répondent immédiatement. sync_json et sync_html attend la fin de l’exécution et renvoie sa sortie.

Les dix actions prises en charge

Chaque étape possède un identifiant unique step_id, une kind, et éventuellement dependencies et command. La configuration ci-dessous décrit l’exécution sur la plateforme. Le moteur d’exécution de la CLI locale ne prend en charge qu’une partie de ces actions.

http — Appeler une API

Définissez command.method, url, avec un champ facultatif headers, et body. Le corps de la réponse devient la sortie de l’étape. Utilisez le champ .output pour transmettre du JSON sous forme de texte. Consultez le bloc exemple de webhook.

- step_id: deliver
  kind: http
  dependencies: [order]
  command:
    method: POST
    url: https://api.example.com/orders
    headers:
      X-API-Key: secret://API_TOKEN
    body: "{{ .steps.order.output }}"

request-parser — Extraire les champs de requête

Utiliser command.extract pour construire un objet à partir de sélecteurs comme .payload.order, ou command.path pour sélectionner une valeur. Les métadonnées de la requête, lorsqu’elles sont fournies par le déclencheur, sont accessibles sous .request. L'extraction ne valide pas un schéma.

- step_id: parse
  kind: request-parser
  command:
    extract:
      order: .payload.order

data-json — Sélectionner des valeurs JSON

Utiliser command.from_step avec l'identifiant de l'étape source et path avec la valeur à sélectionner. path: . conserve toute la valeur; .rows[0].orders sélectionne un champ à partir de la première ligne. Vous pouvez également fournir command.input ; sans source, l’action utilise les données de l’exécution. Il s’agit d’un sélecteur, pas d’un moteur d’expressions jq.

bash — Exécuter les commandes shell

Mettez le script dans command: | et son environnement dans le bloc env. Le worker de workflow l’exécute et capture stdout comme sortie de l’étape. Utilisez une sortie stdout en JSON lorsqu’une autre étape a besoin de données structurées.

python — Exécuter un script Python

Utilisez la même structure command et le champ d’étape env comme pour Bash. Lisez les variables avec os.environ et affiche le résultat. Le exemple de script transmet du JSON de Bash à Python et calcule un total de 97 sans identifiants externes.

sql — Interroger PostgreSQL ou MySQL

Définissez command.driver à postgres ou mysql, dsn à un secret de connexion, et query à SQL. Les requêtes de lecture renvoient columns, rows, et row_count, avec un maximum de 100 lignes. Les requêtes qui modifient des données nécessitent write: true et renvoyer rows_affected. Consultez le bloc exemple de rapport.

email — Envoyer un message

Définissez command.provider, from, to, subject, et text ou html, ainsi que les identifiants du fournisseur. Les fournisseurs pris en charge sont smtp, sendgrid, postmark, mailgun, brevo, mailjet, et mailchimp-transactional (également mandrill). SMTP utilise host, port, username, et password; SendGrid utilise api_key. Les autres fournisseurs exigent leurs propres champs d’identifiants et de domaine. Le champ exemple de rapport présente la configuration de SendGrid. Une action réussie confirme l’envoi au fournisseur, sans garantir la livraison dans la boîte de réception.

s3 — Gérer un objet

Définissez command.operation à put, get, head (ou stat), ou delete. Configurez endpoint sous forme de nom d’hôte sans protocole d’URL, region, use_ssl, access_key, secret_key, bucket, et key. Pour les imports, fournissez body et, éventuellement, content_type. Utilisez un bucket existant. Le bloc Exemple d'instantané écrit du JSON sous une clé contenant l’identifiant d’exécution.

wait — Suspendre pour une approbation humaine

Une étape wait crée une demande d’approbation en attente et suspend l’exécution. L’approbation permet aux étapes dépendantes de continuer. Le rejet fait échouer l’étape et arrête l’exécution ; sans réponse, l’approbation reste en attente. Aucun champ de commande ne permet de définir un délai d’attente, d’attribuer un réviseur ou de prévoir une expiration automatique.

- step_id: approve
  kind: wait
  dependencies: [draft]

Faites dépendre l’action protégée de approve. Consultez le bloc exemple d’approbation pour le parcours complet.

agent — Exécuter un agent IA configuré

Une action agent nécessite un identifiant fixé agent_binding_id, agent_binding_revision_id, agent_binding_revision_digest, et workspace_id dans command. L’empreinte doit être sha256: suivi de 64 caractères hexadécimaux. Utilisez les valeurs exactes de la révision de liaison configurée, puis définissez input à la tâche. Le workflow attend que l'agent termine avant de continuer.

La sortie est l’enveloppe de résultat de l’agent au format JSON, comprenant les informations d’exécution et les résultats ; elle ne se limite pas au texte du brouillon. Examinez-la avant de sélectionner un champ ou de transmettre le résultat complet. Le champ exemple d’approbation affiche tous les champs requis.

Dépendances et sorties des étapes

Listez les identifiants des étapes préalables dans dependencies et placez ces étapes plus tôt dans le manifeste. Si une dépendance échoue, l’action qui en dépend ne s’exécute pas. L’environnement d’exécution actuel exécute les étapes de manière séquentielle ; déclarer des étapes indépendantes ne les fait pas fonctionner en parallèle.

Les modèles utilisent la syntaxe des templates Go. Voici quelques valeurs utiles :

  • {{ .context.destination_url }} pour la configuration partagée.
  • {{ .steps.report.output }} pour la chaîne de sortie brute d’une étape, adaptée à un corps JSON.
  • {{ .steps.count.value }} pour sa valeur analysée, adaptée à l’insertion d’un scalaire dans du texte.
  • {{ index .steps "fetch-prices" "output" }} pour un identifiant contenant un trait d’union.
  • {{ .run.ID }} pour l’identifiant de l’exécution actuelle.

Utiliser .output pour transmettre un objet JSON complet sous forme de texte. Le rendu d’un objet analysé via .value ne l’encode pas en JSON. Pour sélectionner un élément d’un tableau, utilisez des chemins tels que .rows[0].orders dans une data-json.

Secrets et variables d'environnement

Pour les actions HTTP, SQL, e-mail et S3, placez secret://NAME directement dans le champ de commande qui a besoin de la valeur. La référence doit occuper l'ensemble du champ: X-API-Key: secret://API_TOKEN est résolu, mais Authorization: "Bearer secret://API_TOKEN" est envoyé tel quel. Pour une authentification bearer, stockez la valeur complète de l’en-tête Bearer … dans un secret et utilisez Authorization: secret://API_AUTHORIZATION.

Les actions Bash et Python reçoivent les variables d’environnement via le champ env de l’étape. Le worker résout les références aux secrets avant de lancer le script :

steps:
  - step_id: fetch
    kind: python
    env:
      API_TOKEN: secret://API_TOKEN
      API_URL: https://api.example.com/data
    command: |
      import os
      import urllib.request

      request = urllib.request.Request(
          os.environ["API_URL"],
          headers={"Authorization": "Bearer " + os.environ["API_TOKEN"]},
      )
      with urllib.request.urlopen(request, timeout=30) as response:
          print(response.read().decode())

Le bloc de premier niveau secrets est conservé par le modèle de données, mais l’environnement d’exécution actuel ne l’utilise pas pour remplir les environnements des étapes ni résoudre des alias. Il n’est nécessaire pour aucun des deux exemples ci-dessus. Les modèles d’étapes peuvent lire le contexte du workflow, les données du déclencheur et de la requête, ainsi que les sorties des étapes précédentes.

Créer et inspecter une exécution

Créez ou mettez à jour ce manifeste depuis le générateur de workflows, l’agent IA ou la CLI des workflows :

adios workflow push "Daily market brief" ./workflows/daily-market-brief.yaml --create
adios workflow run "Daily market brief"
adios workflow runs --workflow "Daily market brief"
adios workflow logs "Daily market brief"

Omettez --create pour mettre à jour un workflow existant. Utilisez adios workflow validate pour vérifier un manifeste avant de le pousser, et adios workflow run --local pour des vérifications rapides sur votre machine. L’exécuteur local ne prend en charge qu’un sous-ensemble des types d’étapes de la plateforme.

Commencez par une exécution manuelle et des données d’exemple. Vérifiez le statut, la sortie et l’erreur de chaque étape dans Workflows avant de connecter une source d’événements réelle ou une planification récurrente. Pour les approbations, testez l’acceptation et le rejet, puis vérifiez que l’étape protégée reste en attente jusqu’à la décision.

Utiliser timeout_seconds sur les étapes HTTP, script, SQL ou agent lorsque la valeur par défaut ne convient pas. Les étapes HTTP, script et SQL ont un délai par défaut de 30 secondes ; les étapes agent, de 30 minutes. Une étape d’attente dépend de son état d’approbation, et non de ce délai.