Vai al contenuto
AdiosDocumentazione
Esplora la documentazione

Flussi di lavoro

I workflow Adios collegano API, script, database, email, archiviazione a oggetti e agenti IA in una sequenza di azioni tracciate. Avvia un’esecuzione manualmente, da un webhook o evento, oppure a intervalli ricorrenti. Aggiungi un’approvazione umana prima di un’azione che richiede una revisione.

Parti da una ricetta completa: elaborare un webhook, inviare un report pianificato, oppure revisione prima della pubblicazione. La panoramica dei workflow include anche esempi di S3 e script.

In questa pagina: manifest, trigger, tutte e dieci le azioni, output e dipendenze, segreti e variabili di ambiente, e creare ed esaminare.

Manifest del workflow

Un manifest di workflow descrive trigger, contesto condiviso e passaggi ordinati. In un repository dedicato ai workflow puoi chiamare il file adios.yaml. In un repository applicativo, mantieni il manifest dell’ambiente di esecuzione dell’app nella directory principale e conserva i manifest dei workflow in una directory come 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\" }}"

Sostituisci team-local con l’ID del tuo team, configura gli endpoint API e crea MARKET_DATA_API_KEY nei segreti Adios prima di distribuire questo esempio. L’API sorgente richiede un’intestazione X-API-Key; la sua destinazione riceve le quotazioni selezionate come JSON. La pianificazione viene eseguita una volta al giorno alle 00:00 UTC. Rimuovi triggers per un test esclusivamente manuale prima di abilitare gli invii ricorrenti.

Trigger e pianificazione

  • Manuale: avvia un’esecuzione da Workflow o con adios workflow run. Un workflow senza triggers viene eseguito solo così.
  • Webhook: usa type: webhook e un nome dell'evento, come order.created. Il payload dell’evento in ingresso è disponibile come .payload.
  • Evento: usa type: event e il nome dell’evento interno devono corrispondere.
  • Cron: usa type: cron con un’espressione a cinque campi come cron: "0 8 * * 1-5". Aggiungi timezone: Europe/Berlin per eseguire a un orario locale; senza, cron usa UTC.
  • Intervallo: usa type: schedule con una durata come interval: 1h o interval: 24h. cron: "@every 1h" equivale a interval: 1h.
triggers:
  - type: cron
    cron: "0 8 * * 1-5"
    timezone: Europe/Berlin
    concurrency: forbid

Gli intervalli si allineano ai confini UTC, quindi interval: 24h viene eseguito una volta al giorno alle 00:00 UTC, non 24 ore dopo la distribuzione. Usa cron con un timezone quando ti serve un orario locale preciso. Lo scheduler controlla gli slot in scadenza circa ogni 30 secondi. Gli slot persi mentre lo scheduler era fermo vengono saltati, non riproposti.

Imposta concurrency: forbid per saltare uno slot pianificato mentre un evento precedente dello stesso trigger è ancora in sospeso o un’esecuzione è in attesa di approvazione. Lo slot saltato viene registrato come evento saltato. Se un’esecuzione ripetuta potrebbe comunque inviare report o scritture duplicati, deduplica nella tua applicazione o nella destinazione.

Endpoint webhook pubblici

Imposta public: true su un webhook o event per ricevere richieste HTTP dall’esterno di 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 è obbligatorio. I segmenti tra parentesi graffe, come {order_id}, vengono acquisiti come parametri di percorso.
  • public_methods e public_hosts limitano le richieste corrispondenti. Omettili per accettare qualsiasi metodo o host.
  • public_secret_ref fa sì che il chiamante invii il valore del segreto nell’header X-Workflow-Secret. Le richieste senza il valore corrispondente vengono rifiutate.
  • response_mode imposta la risposta. queued_json (predefinito) e async_json rispondono subito. sync_json e sync_html attende l’esecuzione e ne restituisce l’output.

Tutte e dieci le azioni supportate

Ogni passaggio ha un identificativo univoco step_id, un kind, e facoltativamente dependencies e command. La configurazione seguente descrive l’esecuzione sulla piattaforma. Il runner locale della CLI implementa solo un sottoinsieme di queste azioni.

http — Chiama un’API

Imposta command.method, url, il campo facoltativo headers, e body. Il corpo della risposta diventa l’output del passaggio. Usa l’output di un passaggio precedente .output per inoltrare JSON come testo. Vedi il workflow ricetta 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 — Estrai campi della richiesta

Usa command.extract per costruire un oggetto da selettori come .payload.order, oppure command.path per selezionare un valore. I metadati della richiesta, quando forniti dal trigger, sono disponibili sotto .request. L'estrazione non convalida uno schema.

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

data-json — Seleziona valori JSON

Usa command.from_step con l’ID del passaggio sorgente e path con il valore da selezionare. path: . mantiene l'intero valore; .rows[0].orders seleziona un campo della prima riga. Puoi fornire anche command.input; senza una sorgente, l’azione usa il payload dell’esecuzione. È un selettore, non un motore di espressioni jq.

bash — Esegui comandi shell

Metti lo script in command: | e il suo ambiente nel blocco del passaggio env. Il worker del workflow lo esegue e acquisisce stdout come output del passaggio. Usa stdout in JSON quando un altro passaggio richiede dati strutturati.

python — Esegui uno script Python

Usa la stessa struttura command e env di Bash. Leggi le variabili con os.environ e mostra il risultato. Il workflow esempio di script passa JSON da Bash a Python e calcola un totale di 97 senza credenziali esterne.

sql — Interroga PostgreSQL o MySQL

Imposta command.driver a postgres o mysql, dsn a un segreto di connessione, e query per SQL. Le query di lettura restituiscono columns, rows, e row_count, con al massimo 100 righe. Le query che modificano i dati richiedono write: true e restituiscono rows_affected. Vedi il ricetta di report.

email — Invia un messaggio

Imposta command.provider, from, to, subject, e text o html, insieme alle credenziali del fornitore. I fornitori supportati sono smtp, sendgrid, postmark, mailgun, brevo, mailjet, e mailchimp-transactional (anche mandrill). SMTP utilizza host, port, username, e password; SendGrid usa api_key. Gli altri fornitori richiedono i propri campi per credenziali e dominio. L’esempio ricetta di report mostra la configurazione SendGrid. Un’azione riuscita conferma l’invio al fornitore, non la consegna nella casella di posta.

s3 — Gestisci un oggetto

Imposta command.operation a put, get, head (o stat), oppure delete. Configura endpoint come nome host senza schema URL, region, use_ssl, access_key, secret_key, bucket, e key. Per i caricamenti, fornisci body e facoltativamente content_type. Usa un bucket esistente. Il workflow esempio di istantanea scrive JSON sotto una chiave contenente l'ID di esecuzione.

wait — Attendi un’approvazione umana

Un passaggio wait crea un’approvazione in sospeso e mette in pausa l’esecuzione. L’approvazione consente ai passaggi dipendenti di continuare. Il rifiuto fa fallire il passaggio e interrompe l’esecuzione; un’approvazione senza risposta resta in attesa. Non esistono campi di comando per ritardi temporizzati, assegnazione dei revisori o scadenza automatica.

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

Fai dipendere l’azione protetta da approve. Vedi il ricetta di approvazione per il flusso completo.

agent — Esegui un agente IA configurato

Un’azione agente richiede un identificativo fissato agent_binding_id, agent_binding_revision_id, agent_binding_revision_digest, e workspace_id in command. Il digest deve essere sha256: seguito da 64 caratteri esadecimali. Usa i valori precisi della revisione configurata del binding, poi imposta input al compito. Il workflow attende che l’agente termini prima di continuare.

L’output è la struttura JSON del risultato dell’agente, incluse le informazioni sull’esecuzione e i risultati; non è soltanto il testo della bozza. Esaminalo prima di selezionare un campo o inoltrare tutto il risultato. Il campo ricetta di approvazione mostra tutti i campi richiesti.

Dipendenze e output dei passaggi

Elenca gli ID dei passaggi precedenti in dependencies e colloca quei passaggi prima nel manifest. Una dipendenza fallita impedisce l’esecuzione dell’azione successiva. L’ambiente attuale esegue i passaggi in sequenza; elencare passaggi indipendenti non li fa eseguire in parallelo.

I modelli usano la sintassi dei template Go. I valori utili includono:

  • {{ .context.destination_url }} per la configurazione condivisa.
  • {{ .steps.report.output }} per la stringa di output originale di un passaggio, adatta a un corpo JSON.
  • {{ .steps.count.value }} per il valore analizzato, adatto a inserire uno scalare nel testo.
  • {{ index .steps "fetch-prices" "output" }} per un ID contenente un trattino.
  • {{ .run.ID }} per l'ID corrente di esecuzione.

Usa .output per passare un oggetto JSON completo come testo. Renderizzare un oggetto analizzato tramite .value non ne esegue la codifica JSON. Per selezionare elementi dagli array, usa percorsi come .rows[0].orders in un data-json.

Segreti e variabili di ambiente

Per le azioni HTTP, SQL, email e S3, inserisci secret://NAME direttamente nel campo di comando che ha bisogno del valore. Il riferimento deve occupare l'intero campo: X-API-Key: secret://API_TOKEN viene risolto, ma Authorization: "Bearer secret://API_TOKEN" viene inviato letteralmente. Per l’autenticazione bearer, conserva il valore completo dell’intestazione Bearer … in un segreto e usa Authorization: secret://API_AUTHORIZATION.

Le azioni Bash e Python ricevono le variabili di ambiente tramite il campo env del passaggio. Il worker recupera i valori dei riferimenti ai segreti prima di avviare lo 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())

Una mappa di primo livello del workflow secrets viene conservata dal modello di dati, ma l’ambiente attuale non la usa per popolare gli ambienti dei passaggi o risolvere alias. Non serve per nessuno dei due schemi sopra. I modelli dei passaggi possono leggere il contesto del workflow, il payload del trigger, i dati della richiesta e gli output dei passaggi precedenti.

Crea ed esamina un’esecuzione

Crea o aggiorna questo manifest dal builder dei workflow, dall’agente AI o dalla CLI dei workflow:

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"

Ometti --create per aggiornare un workflow già esistente. Usa adios workflow validate per controllare un manifest prima di inviarlo, e adios workflow run --local per controlli rapidi sulla tua macchina. Il runner locale supporta solo un sottoinsieme dei tipi di passaggio della piattaforma.

Inizia con un’esecuzione manuale e input di esempio. Controlla stato, output ed errore di ogni passaggio in Workflow prima di collegare una sorgente di eventi reale o una pianificazione ricorrente. Per le approvazioni, prova sia l’approvazione sia il rifiuto e verifica che il passaggio protetto resti in sospeso fino alla decisione.

Usa timeout_seconds nei passaggi HTTP, script, SQL o agente quando il valore predefinito non è adatto. I passaggi HTTP, script e SQL hanno un valore predefinito di 30 secondi; quelli agente di 30 minuti. Un passaggio di attesa dipende dal suo stato di approvazione, non da questo timeout.