Pular para o conteúdo
AdiosDocumentação
Explorar a documentação

Workflows

Adios Workflows conecta APIs, scripts, bases de dados, e-mail, armazenamento de objetos e agentes de IA em uma sequência de ações rastreadas. Inicie uma execução manualmente, a partir de um webhook ou evento, ou em um intervalo de repetição. Adicione uma aprovação humana antes de uma ação que precisa de revisão.

Comece com um exemplo completo: processar um webhook, enviar um relatório agendado, ou revisar antes de publicar. A visão geral do workflow também inclui exemplos de S3 e scripts.

Nesta página: manifesto, gatilhos, todas as dez ações, saídas e dependências, segredos e variáveis de ambiente, e criar e inspecionar.

Manifesto de workflow

Um manifesto de workflow descreve gatilhos, contexto compartilhado e etapas ordenadas. Em um repositório dedicado a workflows, você pode nomear o arquivo adios.yaml. Em um repositório de aplicativo, mantenha o manifesto do ambiente de execução na raiz do projeto e armazene os manifestos de workflow em um diretório como 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\" }}"

Substitua team-local pelo ID da sua equipe, configure os endpoints da API e crie MARKET_DATA_API_KEY nos segredos Adios antes de implantar este exemplo. A API de origem espera um cabeçalho X-API-Key; o destino recebe as cotações selecionadas em JSON. O agendamento roda uma vez por dia às 00:00 UTC. Remova triggers para um teste somente manual antes de ativar o envio recorrente.

Gatilhos e agendamento

  • Manual: inicie uma execução em Workflows ou com adios workflow run. Um workflow sem triggers só roda desta forma.
  • Webhook: use type: webhook e um nome de evento, como order.created. Os dados do evento de entrada estão disponíveis em .payload.
  • Evento: use type: event e o nome interno do evento devem corresponder.
  • Cron: use type: cron com uma expressão de cinco campos como cron: "0 8 * * 1-5". Adicione timezone: Europe/Berlin para rodar em um horário local; sem ele, o cron usa UTC.
  • Intervalo: use type: schedule com uma duração como interval: 1h ou interval: 24h. cron: "@every 1h" é o mesmo que interval: 1h.
triggers:
  - type: cron
    cron: "0 8 * * 1-5"
    timezone: Europe/Berlin
    concurrency: forbid

Os intervalos se alinham aos limites do UTC, então interval: 24h roda uma vez por dia às 00:00 UTC, não 24 horas depois da implantação. Use cron com um timezone quando precisar de um horário local específico. O agendador verifica os horários pendentes a cada 30 segundos, aproximadamente. Horários perdidos enquanto o agendador estava fora do ar são pulados, não reexecutados.

Defina concurrency: forbid para pular um horário agendado enquanto um evento anterior do mesmo gatilho ainda estiver pendente ou uma execução estiver aguardando aprovação. O horário pulado é registrado como um evento ignorado. Se uma execução repetida ainda puder enviar relatórios ou gravações duplicados, faça a deduplicação no seu aplicativo ou destino.

Endpoints de webhook públicos

Defina public: true em um webhook ou event para receber requisições HTTP de fora do 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 é obrigatório. Segmentos entre chaves, como {order_id}, são capturados como parâmetros de caminho.
  • public_methods e public_hosts limitam quais requisições correspondem. Omita-os para aceitar qualquer método ou host.
  • public_secret_ref faz o chamador enviar o valor do segredo no cabeçalho X-Workflow-Secret. Requisições sem o valor correspondente são rejeitadas.
  • response_mode define a resposta. queued_json (o padrão) e async_json respondem imediatamente. sync_json e sync_html aguardam a execução e retornam a saída dela.

Todas as dez ações compatíveis

Cada etapa tem um identificador único step_id, a kind, e opcionalmente dependencies e command. A configuração abaixo descreve a execução na plataforma. O motor de execução da CLI local implementa apenas parte dessas ações.

http — Chamar uma API

Defina command.method, url, opcional headers, e body. O corpo da resposta se torna a saída da etapa. Use o campo .output para encaminhar JSON como texto. Consulte a exemplo 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 — Extrair campos de requisição

Usar command.extract para criar um objeto a partir de seletores como .payload.order, ou command.path para selecionar um valor. Os metadados da requisição, quando fornecidos pelo gatilho, estão disponíveis em .request. A extração não valida um esquema.

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

data-json — Selecionar valores JSON

Usar command.from_step com o ID do passo de origem e path com o valor a selecionar. path: . mantém todo o valor; .rows[0].orders seleciona um campo na primeira linha. Você também pode fornecer command.input ; sem uma origem, a ação usa os dados da execução. Trata-se de um seletor, não de um motor de expressões jq.

bash — Executar comandos de shell

Coloque o script em command: | e seu ambiente no bloco env. O worker de workflow o executa e captura stdout como saída da etapa. Use stdout em JSON quando outra etapa precisar de dados estruturados.

python — Executar um script Python

Use a mesma estrutura command e o campo de etapa env usada no Bash. Leia as variáveis com os.environ e exibe o resultado. O exemplo de script passa JSON de Bash a Python e calcula um total de 97 sem credenciais externas.

sql — Consultar PostgreSQL ou MySQL

Defina command.driver para postgres ou mysql, dsn para um segredo de ligação, e query para SQL. As consultas de leitura retornam columns, rows, e row_count, com no máximo 100 linhas. Consultas que modificam dados requerem write: true e retornar rows_affected. Consulte a exemplo de relatório.

email — Enviar uma mensagem

Defina command.provider, from, to, subject, e text ou html, junto com as credenciais do provedor. Os provedores compatíveis são smtp, sendgrid, postmark, mailgun, brevo, mailjet, e mailchimp-transactional (também mandrill). SMTP usa host, port, username, e password; SendGrid usa api_key. Outros provedores exigem seus próprios campos de credencial e domínio. A exemplo de relatório mostra a configuração do SendGrid. Uma ação bem-sucedida confirma o envio ao provedor, não a entrega na caixa de entrada.

s3 — Gerenciar um objeto

Defina command.operation para put, get, head (ou stat), ou delete. Configure endpoint como nome de host sem protocolo de URL, region, use_ssl, access_key, secret_key, bucket, e key. Para envios, forneça body e opcionalmente content_type. Use um bucket existente. A exemplo de instantâneo grava JSON sob uma chave que contém o ID da execução.

wait — Pausar para aprovação humana

Uma etapa wait cria uma aprovação pendente e pausa a execução. A aprovação permite continuar as etapas dependentes. A rejeição faz a etapa falhar e interrompe a execução; uma aprovação sem resposta continua aguardando. Não há campos de comando para atrasos cronometrados, atribuição de revisores ou expiração automática.

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

Faça a ação protegida depender de approve. Consulte a exemplo de aprovação para o fluxo completo.

agent — Executar um agente de IA configurado

Uma ação agent exige um identificador fixado agent_binding_id, agent_binding_revision_id, agent_binding_revision_digest, e workspace_id em command. O hash deve ser sha256: seguido de 64 caracteres hexadecimais. Use os valores exatos da revisão de vínculo configurada e defina input para a tarefa. O workflow aguarda o agente terminar antes de continuar.

A saída é o envelope de resultado do agente em JSON, incluindo informações da execução e resultados; não é apenas o texto do rascunho. Inspecione-o antes de selecionar um campo ou encaminhar o resultado completo. A exemplo de aprovação mostra todos os campos obrigatórios.

Dependências e saídas de passos

Liste os IDs das etapas anteriores em dependencies e coloque essas etapas antes no manifesto. A falha de uma dependência impede a execução da ação dependente. O ambiente de execução atual executa as etapas sequencialmente; listar etapas independentes não as faz funcionar em paralelo.

Os modelos usam a sintaxe de templates Go. Valores úteis incluem:

  • {{ .context.destination_url }} para configuração compartilhada.
  • {{ .steps.report.output }} para a string bruta de saída de uma etapa, adequada para um corpo JSON.
  • {{ .steps.count.value }} para seu valor analisado, adequado para inserir um escalar no texto.
  • {{ index .steps "fetch-prices" "output" }} para uma identificação contendo um hífen.
  • {{ .run.ID }} para o ID atual da execução.

Usar .output para passar um objeto JSON completo como texto. Renderizar um objeto analisado por .value não o codifica em JSON. Para selecionar valores de arrays, use caminhos como .rows[0].orders em uma data-json.

Segredos e variáveis de ambiente

Para ações HTTP, SQL, e-mail e S3, coloque secret://NAME diretamente no campo de comando que precisa do valor. A referência deve ocupar todo o campo: X-API-Key: secret://API_TOKEN resolve, mas Authorization: "Bearer secret://API_TOKEN" é enviado literalmente. Para autenticação bearer, armazene o valor completo do cabeçalho Bearer … em um segredo e use Authorization: secret://API_AUTHORIZATION.

As ações Bash e Python recebem variáveis de ambiente pelo campo env da etapa. O worker resolve as referências de segredos antes de iniciar o 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())

O bloco de nível superior secrets é mantido pelo modelo de dados, mas o ambiente de execução atual não o usa para preencher os ambientes das etapas nem resolver aliases. Ele não é necessário para nenhum dos exemplos acima. Os modelos de etapas podem ler o contexto do workflow, os dados do gatilho, os dados da requisição e as saídas das etapas anteriores.

Criar e inspecionar uma execução

Crie ou atualize este manifesto pelo construtor de workflows, pelo agente de IA ou pela CLI de 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"

Omita --create para atualizar um workflow que já existe. Use adios workflow validate para verificar um manifesto antes de enviá-lo, e adios workflow run --local para verificações rápidas na sua máquina. O runner local suporta apenas um subconjunto dos tipos de etapa da plataforma.

Comece com uma execução manual e entradas de exemplo. Inspecione o status, a saída e o erro de cada etapa em Workflows antes de conectar uma fonte real de eventos ou um agendamento recorrente. Para aprovações, teste a aceitação e a rejeição e confirme que a etapa protegida continua pendente até a decisão.

Usar timeout_seconds nas etapas HTTP, script, SQL ou agent quando o padrão não for adequado. Etapas HTTP, script e SQL têm prazo padrão de 30 segundos; etapas agent, de 30 minutos. Uma etapa de espera é controlada pelo estado de aprovação, não por esse prazo.