Passa al contenuto principale

Avviare server e worker

Avvia il server API e i processi worker su un Runtime durevole, e parla con il server dalla CLI.

Prerequisiti​

  • una cartella config/ con un flow validato, i suoi agenti e i suoi modelli. Vedi Il tuo primo flow.
  • un plugin store e un plugin broker installati per il backend che scegli, per esempio afe-postgres e afe-redis.

Passi​

  1. Nomina uno store e un broker in un manifest Runtime (vedi In produzione).

    Un Runtime rende durevoli ticket e checkpoint. Con un broker permette anche a più processi di dividersi il lavoro. Senza un Runtime, il motore tiene ticket e checkpoint in memoria e li perde quando il processo finisce. Il server non parte senza un Runtime che nomina uno store e un broker.

  2. Esporta il token dell'API, poi avvia il server e i worker.

    Il server non parte senza AFE_API_TOKEN. Ascolta su 127.0.0.1 a meno che tu non passi --host. afe serve è solo API: accetta una richiesta, la valida, registra il ticket e mette in coda il job. Non esegue mai un nodo. I processi afe worker eseguono i job in coda.

    export AFE_API_TOKEN=$(openssl rand -hex 32)
    afe serve -c config/                    # ascolta su 127.0.0.1:8765
    afe worker -c config/                   # in un altro terminale: esegue i ticket in coda
    afe worker -c config/ --concurrency 4   # fino a quattro ticket insieme

  3. Avvia diversi worker sullo stesso store e broker.

    Il lock di un ticket è tenuto dal worker che lo esegue. Due worker non eseguono mai lo stesso ticket insieme. Un job consegnato due volte non apre due volte il ticket, e non ripete mai una chiamata al modello già pagata. Un resume è legato alla richiesta a cui risponde, quindi un resume duplicato non applica mai una risposta obsoleta a una pausa successiva.

    afe serve -c ./config                 # l'API, un processo
    afe worker -c ./config                # esegue i ticket in coda, uno alla volta
    afe worker -c ./config -concurrency 4 # fino a quattro ticket insieme
    afe workers                           # i worker vivi e le metriche della coda

  4. Aggiungi un listener operativo con --ops-port N su afe serve o afe worker.

    Serve /livez, /readyz e /metrics, su 127.0.0.1 a meno che --ops-host non dica altro. Senza --ops-port non ascolta nient'altro (vedi In produzione).

  5. Servi la web UI con afe serve --ui, sullo stesso host e sulla stessa porta dell'API.

    Senza di essa rispondono solo l'API, gli endpoint di autenticazione e /rpc (vedi Web UI).

Comandi​

Gli altri comandi parlano con il server. --url vale di default ws://127.0.0.1:8765/rpc:

ComandoCosa fa
afe validate -c DIRControlla tutti i manifest e stampa tutti i problemi (lavora sui file, senza server).
afe run FLOW -i INPUT.yaml [--revision ID]Avvia un ticket e lo segue finché finisce o aspetta una persona.
afe rerun TICKETAvvia un nuovo ticket con flow, input, progetto e revisione di uno esistente, e lo segue.
afe resume TICKET [AZIONE] [--comment …]Risponde a un ticket in attesa (o lo fa ripartire) e lo segue.
afe inspect TICKETStato, revisione, consumi, la domanda in attesa, gli artefatti.
afe tickets [--state STATO]Elenca i ticket, con i primi 12 caratteri della loro revisione.
afe workersI worker vivi e le metriche della coda.
afe cancel TICKETAnnulla un ticket. I suoi artefatti restano.

Quando un flow lavora su un progetto (requiresWorkspace diverso da none), afe run accetta --project NOME. Il progetto deve esistere e combaciare con il tipo di workspace del flow. afe inspect lo stampa.

Codici di uscita: 0 quando il ticket è finito, 2 quando aspetta una persona, 1 negli altri casi. Senza un terminale afe run non chiede nulla. Esce con 2 e stampa il comando afe resume da usare.

Note​

  • afe worker --dry fa girare ogni agente sull'harness dry, che riempie ogni artefatto partendo dal suo Schema, a costo zero.
  • La sessione del browser per la web UI vive in un cookie HttpOnly:
    • POST /auth/login con {"token": "…"} la imposta. Il token è confrontato a tempo costante.
    • POST /auth/logout la cancella.
    • GET /auth/session risponde {"expires_at": …} oppure 401.
    • --session-hours decide quanto dura una sessione, 8 ore di default.
    • Il WebSocket /rpc accetta anche quel cookie, ma solo se l'Origin della richiesta è quello del server. La CLI continua a usare il token Bearer, mai il cookie.
  • afe worker si ferma in modo pulito su SIGINT o SIGTERM. Smette di prendere nuovi job, aspetta quelli che sta eseguendo, rilascia i suoi lock ed esce.

Risoluzione dei problemi​

Sintomo: afe serve termina con "set AFE_API_TOKEN: the server does not start without a token". Causa: il token non è stato esportato in questa shell prima di avviare afe serve. Rimedio: esporta di nuovo AFE_API_TOKEN, poi avvia afe serve.

Sintomo: afe run non finisce mai, oppure afe workers non mostra nessun worker vivo. Causa: nessun processo afe worker gira contro lo stesso store e broker. Rimedio: avvia almeno un afe worker -c config/ in un altro terminale.

Sintomo: due processi afe worker provano a eseguire lo stesso ticket. Causa: contro un Runtime condiviso non può succedere. Segnala che i worker puntano a store diversi, per esempio uno ancora su un Runtime in memoria. Rimedio: controlla che entrambi i worker carichino la stessa cartella config/ e lo stesso DSN dello store.

Vedi anche​