Vai al contenuto
AdiosDocumentazione
Riferimento dell'API
IT
Apri la dashboard
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 destinazione riceve le citazioni selezionate come JSON. La pianificazione si ripete ogni 24 ore. Rimuovi triggers per un test esclusivamente manuale prima di abilitare gli invii ricorrenti.

Trigger e pianificazione

  • Manuale: ometti triggers e avvia un’esecuzione da Workflow.
  • 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.
  • Intervallo: usa type: schedule con una durata positiva come interval: 1h o interval: 24h.
  • Cron: lo scheduler attuale supporta @every 1h, * * * * *, e intervalli in minuti, come */5 * * * *. Non interpreta espressioni cron generali del calendario, come 0 8 * * *.

Gli intervalli misurano il tempo trascorso e non sono allineati a un orario specifico. Una nuova pianificazione rilevata può essere eseguita al successivo controllo dello scheduler; riavviarlo azzera il monitoraggio degli intervalli in memoria. Sebbene timezone e concurrency sono campi accettati nel manifest, ma lo scheduler attuale non li applica. Non fare affidamento su concurrency: forbid per impedire esecuzioni sovrapposte.

Per un orario locale fisso, usa uno scheduler esterno per inviare un webhook. Se un’esecuzione ripetuta può generare report o scritture duplicati, implementa la deduplicazione nell’applicazione o nella destinazione.

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 applica questo manifest dal generatore di workflow, dall’agente IA o dalla CLI dei workflow. Il runner locale della CLI è utile per semplici verifiche di sviluppo, ma supporta un sottoinsieme dei tipi di passaggio della piattaforma.

adios workflow deploy ./workflows/daily-market-brief.yaml

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.