Workflow

Workflow je automatizovaný proces složený z kroků: spouštěč zahájí běh a kroky za ním volají nástroje, spouštějí asistenty, větví se, opakují se ve smyčce, posílají požadavky HTTP, čekají na schválení člověkem a nastavují výsledek. API workflow umožňuje vaší aplikaci vypisovat workflow, spouštět je s živým průběhem, číst minulé běhy, rozhodovat o schváleních, upravovat a publikovat workflow a spouštět publikovaná workflow z veřejné URL webhooku.

Každé volání se provádí jménem uživatele, kterému API klíč patří, s jeho oprávněními, organizacemi a kredity. Běhy spuštěné přes API provádějí koncept workflow (aktuální definici); publikované verze spouštějí plány, webhooky a spouštěče booster záznamů.

Rozsahy a přístup #

Rozsahy se navzájem nezahrnují: klíč, který workflow čte i upravuje, potřebuje oba. Klíč bez požadovaného rozsahu dostane 401 s API key is invalid; viz autentizace.

Kromě rozsahu kontroluje každé workflow, kdo smí co dělat:

Workflow, které patří organizaci, běží v této organizaci (její kredity a úložiště), takže uživatel tam musí být členem s přístupem pro zápis.

Základní pojmy #

Definice #

Definice workflow je orientovaný acyklický graf: seznam uzlů nodes a seznam hran edges.

{
  "nodes": [
    {
      "id": "start",
      "type": "trigger.manual",
      "name": "Start",
      "params": {
        "input_schema": {
          "type": "object",
          "properties": {"customer": {"type": "string"}, "question": {"type": "string"}},
          "required": ["question"]
        }
      },
      "position": {"x": 0, "y": 0}
    },
    {
      "id": "answer",
      "type": "assistant.run",
      "name": "Draft an answer",
      "params": {
        "assistant_id": "3f6c1a2e-8b4d-4e7a-9c1f-2d5e6a7b8c90",
        "prompt": "Answer {{ input.customer }}: {{ input.question }}"
      },
      "position": {"x": 0, "y": 160}
    },
    {
      "id": "result",
      "type": "output",
      "name": "Result",
      "params": {"value": {"answer": "{{ steps.answer.output.text }}"}},
      "position": {"x": 0, "y": 320}
    }
  ],
  "edges": [
    {"source": "start", "target": "answer", "source_handle": null},
    {"source": "answer", "target": "result", "source_handle": null}
  ]
}

Definice má nejvýše 200 uzlů, aspoň jeden spouštěč, žádné cykly a žádné hrany vedoucí do spouštěče. Ke kontrole použijte validaci.

Řetězcové parametry jsou šablony (syntaxe Jinja, vyhodnocované v sandboxu). Mohou číst:

Parametr, který je jediným výrazem {{ expression }}, si zachová nativní typ hodnoty (objekt zůstane objektem); nedefinovaná proměnná je chybou kroku.

Typy uzlů #

Úplný seznam se schématem JSON parametrů každého uzlu a nástroji, které může krok tool.call použít, poskytuje katalog. Přehled:

Koncept a publikovaná verze #

definition uložená u workflow je koncept. Každá jeho změna se uchovává jako revize. Běhy spuštěné přes API (i z aplikace) spouštějí koncept.

Publikování zkopíruje koncept do nové neměnné verze (1, 2, ...) a workflow aktivuje. Dokud je workflow aktivní, jeho automatické spouštěče (plán, webhook, booster záznam) spouštějí běhy publikované verze, a to jménem uživatele, který ji publikoval nebo workflow naposledy aktivoval (run_as). Pozdější úpravy konceptu nemění, co spouštěče spouštějí, dokud znovu nepublikujete.

Stavy běhu #

Běh zaznamenává vstup, stav každého kroku a výsledek. Jeho status:

Kroky se spouštějí, jakmile jsou hotové všechny kroky před nimi, takže nezávislé větve běží paralelně. Krok, jehož všechny vstupní hrany jsou neaktivní (nevybraná větev), je skipped. Selhaný krok s hranou error pokračuje po ní; bez ní běh selže (kroky, které už běží, nejdřív doběhnou).

Běhy se po uplynutí doby uchování (ve výchozím nastavení 90 dní) mažou spolu s konverzacemi a soubory, které jejich kroky vytvořily. Pozastavené běhy se uchovávají, dokud neskončí.

Průběh schválení #

Krok human.approval otevře schválení a běh pozastaví. Rozhodnout o něm mohou uživatel, jehož jménem běh probíhá, a členové organizace workflow jmenovaní v kroku; dostanou upozornění v aplikaci a e-mailem. Schválení zobrazuje titulek, zprávu a volitelně formulář (ploché schéma JSON s předvyplněnými hodnotami). Rozhodnutí (schválení s daty formuláře, nebo zamítnutí) se stane výstupem kroku a běh pokračuje na approved nebo rejected. Schválení, o kterém nikdo včas nerozhodne, vyprší: běh pokračuje na timeout, když je tento výstup připojený, jinak krok selže. Viz schválení.

Soubory ve vstupu běhu #

Pole v input_schema ručního spouštěče deklarované jako {"type": "object", "format": "file"} obsahuje jeden soubor. Ve vstupu běhu ho pošlete buď přímo jako base64:

{
  "invoice": {
    "filename": "invoice-1042.pdf",
    "mime_type": "application/pdf",
    "data": "data:application/pdf;base64,JVBERi0xLjcKJcfsj6IKNSAwIG9iago8PC9MZW5ndGg..."
  }
}

nebo jako id souboru, který uživatel už má ("invoice": "7b1e2c3d-..." nebo {"file_id": "7b1e2c3d-..."}). data je prostý base64 nebo data URL; místo filename lze použít name a místo mime_type lze použít content_type. Platí limit velikosti pro nahrávání a kvóta úložiště.

V běhu se hodnota změní na metadata přílohy souboru, což je i podoba, ve které kroky vracejí soubory:

{
  "file_id": "7b1e2c3d-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "filename": "invoice-1042.pdf",
  "content_type": "application/pdf",
  "file_url": "https://ayeto.ai/api/v1/public/file/read?id=7b1e2c3d-4a5b-4c6d-8e7f-9a0b1c2d3e4f&secret=...",
  "size": 48213
}

file_url soubor stáhne. Soubory poslané jako base64 patří běhu a mažou se spolu s ním; soubor uvedený svým id zůstává uživateli a s během se nemaže. Stejná podoba base64 se přijímá v polích pro soubory ve formuláři schválení a v tělech webhooků.

Limity #

Níže uvedené výchozí hodnoty se mohou v jednotlivých nasazeních lišit.

Objekt workflow #

Workflow vracené endpointy pro čtení, vytvoření a úpravu. Má také společná pole (id, created, updated, permissions, ...).

Výpis a čtení workflow #

find vrací workflow, která uživatel vlastní nebo která jsou s ním sdílená, jako pole workflow, od nejnovějších, pokud neřadíte jinak. count vrací počet odpovídajících workflow jako celé číslo. Oba přijímají obvyklé tělo dotazu (filters, sort_key, sort_order, limit_from, limit_to); pro všechno pošlete {}. Každé workflow přichází s celou definicí, proto dlouhé seznamy stránkujte.

get vrací jedno workflow; id je parametr dotazu a tělo je prázdné.

Užitečné filtry: ["organization_id", "==", "<organization id>"], ["organization_id", "==", null] (osobní), ["active", "==", true], ["name", "regex", "invoice"].

curl -X POST "https://ayeto.ai/api/v3/workflow/find" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": [["active", "==", true]], "sort_key": "updated.timestamp", "sort_order": 1, "limit_from": 0, "limit_to": 20}'

curl -X POST "https://ayeto.ai/api/v3/workflow/get?entity_id=5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a" \
  -H "uni-api-key: $AYETO_API_KEY"

{
  "id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "name": "Customer question",
  "description": "Drafts an answer to a customer question",
  "organization_id": null,
  "definition": {"nodes": ["..."], "edges": ["..."]},
  "sharing": [],
  "group_sharing": [],
  "last_run": {"run_id": "c2a1b0d9-8e7f-4a6b-9c5d-4e3f2a1b0c9d", "status": "success", "finished_at": 1759401234567, "credits": 0.42},
  "published_version": 3,
  "published_at": 1759300000000,
  "active": true,
  "run_as": "0f1e2d3c-4b5a-4968-8776-655443322110",
  "created": {"timestamp": 1759000000000, "user_id": "0f1e2d3c-4b5a-4968-8776-655443322110"},
  "updated": {"timestamp": 1759400000000, "user_id": "0f1e2d3c-4b5a-4968-8776-655443322110"}
}

Workflow, které neexistuje nebo které uživatel nevidí, vrací 404.

Vytvoření workflow #

Vrací vytvořené workflow. Definice se uloží tak, jak byla zadána, i když není platná; před spuštěním ji validujte. Vytvoření workflow zaznamená také jeho první revizi a vytvoří uživateli asistenta builderu.

curl -X POST "https://ayeto.ai/api/v3/workflow/create" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Customer question", "description": "Drafts an answer to a customer question"}'

Úprava workflow #

Změní se jen pole, která pošlete. Organizaci, stav publikování a poslední běh zde změnit nelze. Každá změna definice se zaznamená jako revize; publikovaná verze zůstane, jak byla, dokud workflow znovu nepublikujete. Vrací upravené workflow.

Chcete-li změnit jeden uzel, přečtěte workflow, upravte jeho definition a pošlete ji zpět. Dva klienti, kteří upravují stejné workflow současně, si navzájem přepíší definici.

Smazání workflow #

Smaže workflow se všemi jeho běhy (a konverzacemi a soubory, které vytvořily), jeho revizemi, publikovanými verzemi, spouštěči a asistenty builderu. Vrací id smazaného workflow jako řetězec JSON.

Katalog #

Vrací, z čeho lze workflow sestavovat: každý typ uzlu se schématem JSON jeho parametrů a nástroje, které může volat krok tool.call. Bez těla požadavku.

Validace workflow #

Validuje koncept z pohledu volajícího uživatele (včetně toho, zda uživatel může používat asistenty a booster panely, na které koncept odkazuje).

{
  "valid": false,
  "issues": [
    {"severity": "error", "message": "Node 'answer' has no output 'true' (outputs: default, error)", "node_id": "answer", "edge": {"source": "answer", "target": "result", "source_handle": "true"}},
    {"severity": "warning", "message": "Node 'draft' is not reachable from any trigger and never runs", "node_id": "draft", "edge": null}
  ]
}

valid je false, když existuje aspoň jeden problém se závažností error; chyby blokují běhy i publikování, varování ne.

Spuštění workflow #

Spustí koncept jménem volajícího uživatele a odpoví, když běh skončí nebo se pozastaví.

Požadavek #

Spuštění od spouštěče plánu, webhooku nebo booster záznamu spustí koncept ručně, což se hodí k testování: předejte vstup, který by spouštěč vytvořil, např. {"body": {...}, "query": {}, "headers": {}} u spouštěče webhooku.

Uživatel potřebuje k workflow přístup pro spouštění (viz rozsahy a přístup). Před zahájením běhu se koncept validuje; neplatný koncept se odmítne s 422. Chybějící povinný klíč vstupu požadavek neodmítne: běh se vytvoří a selže na kroku spouštěče (Missing input: <keys>).

Požadavek se vrátí, až běh skončí, což může trvat minuty (až do limitu doby běhu). Pro dlouhé běhy nebo živý průběh použijte streamování. Když krok čeká na schválení, odpověď se vrátí se status: "waiting"; běh dál sledujte pomocí čtení běhu.

Odpověď #

200 OK s během.

Příklady #

curl -X POST "https://ayeto.ai/api/v3/workflow/run" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    "input": {"customer": "Jana Novak", "question": "When will order 1042 be delivered?"}
  }'

import json
import os
import requests

response = requests.post(
    "https://ayeto.ai/api/v3/workflow/run",
    headers={"uni-api-key": os.environ["AYETO_API_KEY"]},
    json={
        "workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
        "input": {"customer": "Jana Novak", "question": "When will order 1042 be delivered?"},
    },
    timeout=1900,
)
response.raise_for_status()
run = response.json()
if run["status"] == "success":
    print(json.loads(run["output_json"]) if run["output_json"] else None)
else:
    print(run["status"], run["error"])

const response = await fetch("https://ayeto.ai/api/v3/workflow/run", {
  method: "POST",
  headers: {
    "uni-api-key": process.env.AYETO_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    workflow_id: "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    input: { customer: "Jana Novak", question: "When will order 1042 be delivered?" },
  }),
});
if (!response.ok) throw new Error((await response.json()).detail);
const run = await response.json();
const output = run.output_json ? JSON.parse(run.output_json) : null;
console.log(run.status, output ?? run.error);

Objekt běhu #

Běh má společná pole a navíc:

created.user_id je uživatel, jehož jménem běh proběhl.

Objekt kroku #

Příklad:

{
  "id": "c2a1b0d9-8e7f-4a6b-9c5d-4e3f2a1b0c9d",
  "workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
  "organization_id": null,
  "version": null,
  "trigger_node_id": "start",
  "trigger_type": "trigger.manual",
  "trigger_depth": 0,
  "automatic": false,
  "input_json": "{\"customer\": \"Jana Novak\", \"question\": \"When will order 1042 be delivered?\"}",
  "status": "success",
  "started_at": 1759401220011,
  "active_since": 1759401220011,
  "finished_at": 1759401234567,
  "steps": [
    {
      "node_id": "start", "node_type": "trigger.manual", "status": "success",
      "started_at": 1759401220020, "finished_at": 1759401220031, "handle": null,
      "output_json": "{\"customer\": \"Jana Novak\", \"question\": \"When will order 1042 be delivered?\"}",
      "output_truncated": false, "text": "", "error": "", "file_ids": [], "conversation_id": null, "iteration": []
    },
    {
      "node_id": "answer", "node_type": "assistant.run", "status": "success",
      "started_at": 1759401220040, "finished_at": 1759401234400, "handle": null,
      "output_json": "{\"text\": \"Dear Jana, order 1042 ships on Friday ...\", \"data\": null, \"files\": []}",
      "output_truncated": false, "text": "Dear Jana, order 1042 ships on Friday ...", "error": "",
      "file_ids": [], "conversation_id": "8e2f4a6c-1b3d-4e5f-8a7b-9c0d1e2f3a4b", "iteration": []
    },
    {
      "node_id": "result", "node_type": "output", "status": "success",
      "started_at": 1759401234410, "finished_at": 1759401234420, "handle": null,
      "output_json": "{\"answer\": \"Dear Jana, order 1042 ships on Friday ...\"}",
      "output_truncated": false, "text": "", "error": "", "file_ids": [], "conversation_id": null, "iteration": []
    }
  ],
  "output_json": "{\"answer\": \"Dear Jana, order 1042 ships on Friday ...\"}",
  "error": "",
  "credits": 0.42,
  "created": {"timestamp": 1759401220000, "user_id": "0f1e2d3c-4b5a-4968-8776-655443322110"}
}

Streamování běhu #

Stejný požadavek jako u spuštění workflow, ale odpověď streamuje události běhu tak, jak nastávají. Běh se na serveru provede až do konce, i když se klient odpojí; výsledek si potom přečtěte pomocí čtení běhu.

Chyby přístupu a validace (žádný přístup, neplatný koncept, příliš velký vstup) se vracejí jako běžná chyba HTTP ještě před zahájením streamu.

Formát přenosu #

Odpověď (Content-Type: text/event-stream) je posloupnost objektů JSON zapsaných jeden za druhým bez oddělovačů (ne řádky SSE data:); viz streamování. Každý objekt je chunk:

{"timestamp": 1759401220012, "data": {"type": "run_start", "run_id": "c2a1b0d9-8e7f-4a6b-9c5d-4e3f2a1b0c9d", "node_id": null, "node_type": null, "status": "running", "handle": null, "text": "", "error": "", "output_json": "", "iteration": []}, "error": null}

• data je událost běhu (níže).
• data: "" je keep-alive chunk, posílaný zhruba každou sekundu, když se nic neděje. Ignorujte ho.
• Chunk s nastaveným error ({"status", "text", "detail"}) hlásí chybu, která stream ukončila.

Události #

Každá událost má pole type, run_id, node_id, node_type, status, handle, text, error, output_json a iteration; která z nich nesou hodnotu, závisí na typu.

Události paralelních větví a položek smyček se prolínají; k jejich rozlišení použijte node_id a iteration.

Příklady #

curl -N -X POST "https://ayeto.ai/api/v3/workflow/run/stream" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a", "input": {"question": "When will order 1042 be delivered?"}}'

Python, rozdělení streamu na objekty JSON pomocí raw_decode:

import json
import os
import requests

decoder = json.JSONDecoder()

def events(response):
    """Yield the run events of a streamed response."""
    buffer = ""
    for piece in response.iter_content(chunk_size=None, decode_unicode=True):
        buffer += piece
        while True:
            buffer = buffer.lstrip()
            if not buffer:
                break
            try:
                chunk, end = decoder.raw_decode(buffer)
            except json.JSONDecodeError:
                break  # incomplete object, wait for more data
            buffer = buffer[end:]
            if chunk.get("error"):
                raise RuntimeError(chunk["error"]["detail"])
            if chunk.get("data"):
                yield chunk["data"]

with requests.post(
    "https://ayeto.ai/api/v3/workflow/run/stream",
    headers={"uni-api-key": os.environ["AYETO_API_KEY"]},
    json={"workflow_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a", "input": {"question": "When will order 1042 be delivered?"}},
    stream=True,
    timeout=(10, 120),
) as response:
    response.raise_for_status()
    response.encoding = "utf-8"
    for event in events(response):
        if event["type"] == "step_end":
            print(f"{event['node_id']}: {event['status']} {event['error']}")
        elif event["type"] == "run_waiting":
            print("paused, waiting for:", event["text"])
        elif event["type"] == "run_end":
            print("run", event["status"], event["output_json"] or event["error"])

JavaScript, rozdělení streamu sledováním složených závorek mimo řetězce:

async function* runEvents(response) {
  const reader = response.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = "";
  while (true) {
    const { value, done } = await reader.read();
    if (done) return;
    buffer += value;
    let depth = 0, inString = false, escaped = false, start = -1, consumed = 0;
    for (let i = 0; i < buffer.length; i++) {
      const c = buffer[i];
      if (inString) {
        if (escaped) escaped = false;
        else if (c === "\\") escaped = true;
        else if (c === '"') inString = false;
      } else if (c === '"') inString = true;
      else if (c === "{") { if (depth++ === 0) start = i; }
      else if (c === "}" && --depth === 0) {
        const chunk = JSON.parse(buffer.slice(start, i + 1));
        consumed = i + 1;
        if (chunk.error) throw new Error(chunk.error.detail);
        if (chunk.data) yield chunk.data;
      }
    }
    buffer = buffer.slice(consumed);
  }
}

const response = await fetch("https://ayeto.ai/api/v3/workflow/run/stream", {
  method: "POST",
  headers: { "uni-api-key": process.env.AYETO_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    workflow_id: "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    input: { question: "When will order 1042 be delivered?" },
  }),
});
if (!response.ok) throw new Error((await response.json()).detail);
for await (const event of runEvents(response)) {
  if (event.type === "step_start") console.log("running", event.node_id);
  if (event.type === "step_end") console.log(event.node_id, event.status, event.error);
  if (event.type === "run_waiting") console.log("paused, waiting for", event.text);
  if (event.type === "run_end") console.log("done", event.status, event.output_json || event.error);
}

Zrušení běhu #

Zruší běh, který je ve stavu waiting nebo queued. Jeho čekající kroky selžou a jejich otevřená schválení se zruší. Zrušit ho může uživatel, jehož jménem běh probíhal, a uživatelé s přístupem pro zápis k workflow. Běh ve stavu running zrušit nelze (422); skončí sám nebo na limitu doby běhu. Vrací zrušený běh.

Běhy #

Tyto endpointy vidí běhy, které proběhly jménem uživatele API klíče: běhy, které uživatel spustil, a automatické běhy workflow, která uživatel publikoval nebo aktivoval. Běhy jiných uživatelů se hlásí jako nenalezené.

find vrací pole běhů a count celé číslo; oba přijímají tělo dotazu. Běhy obsahují všechny své kroky a výstupy, proto vždy stránkujte. get vrací jeden běh (prázdné tělo). delete smaže běh spolu s konverzacemi a soubory, které jeho kroky vytvořily, a s jeho schváleními a vrátí jeho id; smazání pozastaveného běhu ho ukončí.

Užitečné filtry:

curl -X POST "https://ayeto.ai/api/v3/workflow/runs/find" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters": [["workflow_id", "==", "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a"]], "sort_key": "created.timestamp", "sort_order": 1, "limit_from": 0, "limit_to": 10}'

Chcete-li sledovat pozastavený běh nebo běh ve frontě, dotazujte se opakovaně na get, dokud jeho status nebude success, failed nebo cancelled.

Schválení #

Endpointy schválení slouží lidem, kteří rozhodují: může je používat každý uživatel jmenovaný v kroku schválení, bez dalších oprávnění k workflow. API klíč přesto potřebuje rozsah ayeto.workflow.

Objekt schválení #

Společná pole a navíc:

Výpis schválení #

Požadavek:

Vrací {"items": [<approval>, ...], "total": <number>} se schváleními, o kterých uživatel smí rozhodnout (nebo o kterých rozhodl), od nejnovějších. total je počet všech odpovídajících schválení.

Počet čekajících schválení #

Bez těla požadavku. Vrací {"pending": 3}, počet schválení, která čekají na rozhodnutí uživatele. Vhodné pro pravidelné dotazování kvůli odznaku (badge).

Čtení schválení #

Vrací schválení. Získat ho mohou uživatelé, kteří o něm smějí rozhodnout, a uživatelé, kteří mohou číst jeho workflow.

Rozhodnutí o schválení #

Rozhodnout smějí jen uživatelé v assignee_user_ids, a to jen dokud je schválení pending a před expires_at. Data formuláře se validují proti form_schema. Rozhodnutí se stane výstupem kroku schválení:

{
  "decision": "approved",
  "data": {"amount": 1200, "note": "OK for this quarter"},
  "comment": "Approved",
  "decided_by": {"id": "0f1e2d3c-4b5a-4968-8776-655443322110", "email": "jana@example.com", "name": "Jana Novak"},
  "decided_at": 1759405000000,
  "approval_id": "e4d3c2b1-a0f9-4e8d-9c7b-6a5f4e3d2c1b"
}

Běh pokračuje na pozadí jménem uživatele, jehož jménem probíhal (ne jménem toho, kdo rozhodl); jeho stav se změní z waiting na queued a potom na running. Vrací rozhodnuté schválení.

curl -X POST "https://ayeto.ai/api/v3/workflow/approval/decide" \
  -H "uni-api-key: $AYETO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "approval_id": "e4d3c2b1-a0f9-4e8d-9c7b-6a5f4e3d2c1b",
    "decision": "approve",
    "data": {"amount": 1200, "note": "OK for this quarter"},
    "comment": "Approved"
  }'

Publikování a spouštěče #

Tyto endpointy potřebují k workflow přístup pro zápis.

Informace o nasazení #

Vrací stav publikování. Obsahuje URL webhooků i s jejich tajnými klíči, a proto vyžaduje rozsah pro zápis.

Pole spouštěče:

Podepsaný http.request posílá hlavičku X-Ayeto-Signature: sha256=<hex HMAC-SHA256 of the request body> vypočtenou pomocí signing_secret, aby ji přijímající služba mohla ověřit.

Publikování workflow #

Validuje koncept z pohledu volajícího, uloží ho jako další verzi, workflow aktivuje a z volajícího udělá uživatele run_as pro automatické běhy. URL webhooků uzlů spouštěčů, které existovaly už dříve, zůstávají stejné. Vrací informace o nasazení. Neplatný koncept se odmítne s 422.

Aktivace a deaktivace #

Aktivace validuje publikovanou verzi z pohledu volajícího a z volajícího udělá uživatele run_as. Dokud je workflow neaktivní, volání webhooků vracejí 404 a plány se nespouštějí. Vrací informace o nasazení. Když není nic publikováno, selže s 422.

Přegenerování tajného klíče webhooku #

Dá webhooku nový tajný klíč; stará URL okamžitě přestane fungovat. Vrací informace o nasazení s novou URL.

Náhled plánu #

Zkontroluje plán pro uzel trigger.schedule a vypíše jeho příští časy:

{"valid": true, "error": "", "next_runs": [1759471200000, 1759730400000, 1759816800000, 1759903200000, 1759989600000]}

Neplatný plán vrací 200 s valid: false a důvodem v error (chybný počet polí, neznámé časové pásmo, spouštění častěji, než dovoluje nejkratší povolený interval).

Asistent builderu #

Každý uživatel s přístupem pro zápis má k workflow vlastního asistenta builderu: asistenta, který v konverzaci workflow čte, upravuje, testovací spouští a vysvětluje. Tento endpoint vrací buildera volajícího (pokud chybí, vytvoří ho) jako asistenta. Mluvte s ním přes chat s jeho id jako asistentem; k tomu je potřeba klíč s rozsahem pro chat. Jeho úpravy se zaznamenávají jako revize s původem builder.

Revize #

Každá změna definice je revize. Změny, které jen přesouvají uzly a provede je stejný uživatel během tří minut, se slučují do poslední revize. Uchovávají se nejnovější revize (ve výchozím nastavení 100).

Výpis revizí #

Vrací až 100 revizí, od nejnovějších, bez jejich definic:

Čtení revize #

Vrací revizi s její úplnou definicí: společná pole a navíc workflow_id, definition, origin, changes a restored_from.

Obnovení revize #

Stejný požadavek jako u čtení revize. Vrátí definici revize jako koncept; obnovení se zaznamená jako nová revize (původ restore), takže ho lze vrátit zpět. Publikovaná verze se nemění. Vrací upravené workflow.

Export a import #

Export je dokument JSON s definicí konceptu, názvem a popisem. Běhy, revize, publikované verze, stav spouštěčů (tajné klíče webhooků), podpisový klíč, organizace a sdílení se neexportují. Asistenti, na které kroky odkazují, se exportují jen jako id.

Export workflow #

Přes API klíč se hodnoty hlaviček kroků http.request, jejichž název vypadá jako přístupový údaj (obsahuje auth, token, secret, key, password, cookie, signature nebo session), vždy vyprázdní; názvy hlaviček zůstanou. Vyprázdněné cesty jsou uvedeny v secret_keys. Uživatel potřebuje přístup pro zápis, nebo sdílení pro čtení s oprávněním workflow.export.

{
  "version": "1.0",
  "exported_at": 1759405000000,
  "workflow": {
    "name": "Customer question",
    "description": "Drafts an answer to a customer question",
    "definition": {"nodes": ["..."], "edges": ["..."]},
    "from_id": "5d4c3b2a-1f0e-4d9c-8b7a-6f5e4d3c2b1a",
    "secret_keys": ["notify_crm.headers.Authorization"]
  }
}

Import workflow #

Vytvoří nové, nepublikované workflow volajícího a zvaliduje ho. Kroky, které odkazují na něco, co volající nemůže používat (asistent z jiného účtu, vyprázdněné přístupové údaje), import neblokují; jsou nahlášeny, aby je bylo možné opravit.

Formát exportu musí mít stejnou hlavní verzi (1) a definice nejvýše 200 uzlů.

Kopírování workflow #

V jednom volání exportuje koncept a importuje ho jako nové workflow volajícího; odpověď je stejná jako u importu. Uživatel potřebuje přístup pro zápis, nebo sdílení pro čtení s oprávněním workflow.copy. Uživatel s přístupem pro zápis k originálu si přístupové údaje kroků HTTP ponechá; kopie vytvořená díky oprávnění workflow.copy je vynechá.

Webhooky #

Uzel trigger.webhook publikovaného, aktivního workflow má veřejnou URL. Získáte ji z triggers[].url v informacích o nasazení:

https://ayeto.ai/api/v3/workflow/hook/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/Xq3v...secret...

Zacházejte s URL jako s tajným údajem; kdokoli, kdo ji má, může spouštět běhy, které čerpají kredity uživatele run_as. Pokud unikne, přegenerujte ji.

Požadavek #

Pošlete POST s tělem JSON a Content-Type: application/json. Tělo jiného typu obsahu se předá jako text (nebo se zparsuje, pokud je to JSON). API klíč není potřeba.

Vstup běhu (výstup spouštěče, dostupný krokům jako {{ input }}) je:

Kroky ho čtou jako {{ input.body.order_id }}, {{ input.query.source }} a tak dále. Vstup je omezen na 200 000 znaků JSON.

Soubory v těle #

Soubory lze posílat uvnitř těla, v libovolné hloubce (až 32 úrovní):

• objekt s data v base64 a s name nebo filename a bez jiných klíčů než name, filename, content_type, mime_type, data, size;
• řetězec data URL data:<type>;base64,....

Každý soubor se uloží jako soubor běhu (vlastní ho uživatel run_as, podléhá limitu velikosti pro nahrávání a kvótě úložiště) a v těle se nahradí metadaty přílohy ({file_id, filename, content_type, file_url, size}). Nejvýše 10 souborů na volání.

Odpověď #

200 OK, jakmile je běh zařazen do fronty; běh se provádí na pozadí:

{"run_id": "b7c6d5e4-f3a2-4b1c-9d8e-7f6a5b4c3d2e", "status": "queued"}

Běh provádí publikovanou verzi jménem uživatele run_as, který ho vidí přes běhy (trigger_type je trigger.webhook, automatic je true). Jeho vstupu se nedůvěřuje: krok čte soubory uživatele jen tehdy, když je jmenuje sám krok, nikdy proto, že je jmenuje tělo webhooku.

Omezení počtu požadavků #

Každý spouštěč přijme nejvýše 60 volání za minutu, 2 000 za hodinu a 20 000 za den, od libovolného počtu odesílatelů. Navíc platí limit proti zahlcení na IP adresu. Workflow také odmítá nové běhy, dokud má ve frontě 50 běhů (ve výchozím nastavení). Obojí odpovídá 429; odpověď limitu požadavků nese Retry-After (sekundy).

Příklad #

curl -X POST "https://ayeto.ai/api/v3/workflow/hook/9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d/$WEBHOOK_SECRET?source=shop" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": 1042,
    "customer": {"name": "Jana Novak", "email": "jana@example.com"},
    "invoice": {"filename": "invoice-1042.pdf", "content_type": "application/pdf", "data": "JVBERi0xLjcKJcfsj6IK..."}
  }'

Chyby #

Chyby mají tělo JSON {"detail": "..."}. Chyby autentizace, limitů požadavků a serveru jsou popsány v konvencích.

Chyby specifické pro workflow:

Selhání kroku není chybou HTTP: běh se vrátí se status: "failed" a důvodem v error a v error selhaného kroku.