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 senzatriggersviene eseguito solo così. - Webhook: usa
type: webhooke un nome dell'evento, comeorder.created. Il payload dell’evento in ingresso è disponibile come.payload. - Evento: usa
type: evente il nome dell’evento interno devono corrispondere. - Cron: usa
type: croncon un’espressione a cinque campi comecron: "0 8 * * 1-5". Aggiungitimezone: Europe/Berlinper eseguire a un orario locale; senza, cron usa UTC. - Intervallo: usa
type: schedulecon una durata comeinterval: 1hointerval: 24h.cron: "@every 1h"equivale ainterval: 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_methodsepublic_hostslimitano le richieste corrispondenti. Omettili per accettare qualsiasi metodo o host.public_secret_reffa sì che il chiamante invii il valore del segreto nell’headerX-Workflow-Secret. Le richieste senza il valore corrispondente vengono rifiutate.response_modeimposta la risposta.queued_json(predefinito) easync_jsonrispondono subito.sync_jsonesync_htmlattende 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.