Logo Agile AgileTavG

Guida operativa (HELP) — AgileTavG

Questa pagina serve anche su /help. È scritta per essere seguita **passo per

passo**: ogni comando riportato è stato eseguito dal vivo sul sito pubblico

https://agiletavg.agile.software prima di questa consegna. Se qualcosa non

funziona come scritto, è un difetto: va segnalato.

Indice:

1. [PERCORSO DELLA GIURIA (login demo → galleria → crea → conversa → API key → uso esterno)](#1-percorso-della-giuria)

2. [Il percorso utente (dal sito alla API key)](#2-il-percorso-utente-dal-sito-alla-api-key)

3. [Come ottenere una chiave dal portale (admin)](#3-come-ottenere-una-chiave-dal-portale-admin)

4. [Le persone digitali](#4-le-persone-digitali)

5. [Aprire una sessione](#5-aprire-una-sessione)

6. [Far parlare l'avatar](#6-far-parlare-lavatar)

7. [Conversare (voce → risposta video)](#7-conversare-voce--risposta-video)

8. [Provare la vista](#8-provare-la-vista)

9. [Cosa aspettarsi (tempi e formati)](#9-cosa-aspettarsi-tempi-e-formati)

10. [Gli errori possibili e cosa significano](#10-gli-errori-possibili-e-cosa-significano)

11. [Come si verifica che la rete è chiusa](#11-come-si-verifica-che-la-rete-e-chiusa)

12. [Collaudo robotizzato](#12-collaudo-robotizzato)

13. [La demo videochat (browser)](#13-la-demo-videochat-browser)

14. [Clonare una persona reale (foto/video + voce)](#14-clonare-una-persona-reale-fotovideo--voce)

---

1. PERCORSO DELLA GIURIA

Il copione della seduta finale, passo per passo. Ogni passo qui sotto è stato

eseguito dal vivo sul sito pubblico https://agiletavg.agile.software.

Passo 0 — Entra con l'utente demo (già pronto, nessuna registrazione)

1. Apri https://agiletavg.agile.software/: è la landing page commerciale

(cos'è, cosa fa, invito a entrare).

2. Premi «Accedi / Registrati» in alto (o nella home).

3. Nella pagina del conto, riquadro «Hai già un conto?»: è già compilato

demo / AgileTavG → premi Accedi. (Va bene anche

demo@agile.software come nome utente.)

Passo 1 — La galleria degli avatar

Dopo l'accesso sei nell'area conto. Scorri alla sezione **«Galleria degli

avatar del prodotto»**: le tre persone digitali (Alessia, Brando, Cinzia) con

ritratto e breve video di presentazione di ciascuna (controlla che

dicano ciò che dice la scheda). Con l'audio alzato si sente la voce di ognuna.

Da riga di comando (per la verifica senza browser):

curl -s https://agiletavg.agile.software/v1/persone/alessia/volto -o alessia.png
curl -s -c /tmp/cj.txt -d "email=demo&password=AgileTavG" \
  -o /dev/null https://agiletavg.agile.software/conto/accesso
curl -s -b /tmp/cj.txt -o alessia-presentazione.mp4 \
  https://agiletavg.agile.software/conto/presentazioni/alessia.mp4

Passo 2 — Crea il SUO avatar (sala di registrazione, salvato nel conto)

1. Nel conto, sezione «Il tuo avatar clonato» → «⏺ Crea il mio avatar»

(oppure /registra direttamente).

2. Nella sala: sei già dentro col conto demo (se richiesto: demo /

AgileTavG). Dai un nome all'avatar nel campo apposito.

3. Premi «⏺ Registra 25 s»: consenti webcam e microfono, guardi la

camera e parli presentandoti (20-30 s). Puoi fermare prima con Stop.

In alternativa: «📁 Carica video o foto» (mp4/webm, o jpg/png per la

sola foto — qualità inferiore ammessa).

4. A fine caricamento: «✅ Avatar salvato nel tuo conto» e appare il

pulsante «→ Parla col tuo avatar in videochat».

5. Verifica che è salvato: riapri /conto (anche chiudendo il browser):

l'avatar è nella galleria con l'etichetta «il tuo». Il comando equivalente:

# caricamento del video di riferimento (dal vivo si fa dal browser)
curl -s -X POST -H "X-API-Key: LA_TUA_CHIAVE" -F "video=@persona.webm" \
  https://agiletavg.agile.software/v1/riferimenti
# → {"id":"…","voce_id":"…"}

# salvataggio nel conto (lo fa la sala di registrazione da sola)
curl -s -b /tmp/cj.txt -d "riferimento=ID&nome=Il mio avatar&voce=VOCE_ID" \
  https://agiletavg.agile.software/conto/avatar
# → {"salvato":true,…}

Passo 3 — Parla con gli avatar (i tre + il suo)

1. Dalla galleria premi «Parla con …» su una persona (o sul tuo avatar):

si apre la videochat con quella persona già selezionata.

2. Incolla la API key (se non c'è già; la trovi nel conto, sezione API) e

premi Avvia sessione: l'avatar ti saluta e **la webcam si attiva per

la vista** (consentila: l'avatar tiene conto di ciò che vede).

3. 🎤 Parla: consenti il microfono, fai la domanda, premi di nuovo per

fermare. Arriva il video di risposta con i sottotitoli; dopo ogni risposta

la vista guarda di nuovo (nei sottotitoli: [VISTA] …).

4. Il SUO avatar (id tuo) parla con il suo volto e la sua voce clonata.

Chiedi cose visibili per provare la vista: «quante dita sto alzando?»,

«che cosa vedi adesso?», «sto mostrando un documento?».

Passo 4 — Scarica la API key e usala da fuori (il confronto con Tavus)

1. Nel conto, sezione «Le tue API» → Genera API key → copiala

(appare una volta sola).

2. Sotto la chiave trovi gli esempi pronti (curl, Python, JavaScript) da

applicazioni esterne: copia e incolla, sostituendo LA_TUA_CHIAVE.

CORS è abilitato: funziona anche da JavaScript nel browser.

3. Verifica che la chiave vede anche il suo avatar salvato:

curl -s -H "X-API-Key: LA_TUA_CHIAVE" \
  https://agiletavg.agile.software/v1/persone | python3 -m json.tool
# l'elenco contiene le tre persone + una con "id": "tuo" (il suo avatar)

# sessione sul SUO avatar, con voce e volto clonati:
curl -s -X POST -H "X-API-Key: LA_TUA_CHIAVE" -H "Content-Type: application/json" \
  -d '{"persona":"tuo","lingua":"it"}' \
  https://agiletavg.agile.software/v1/sessioni

Passo 5 — Cancella il materiale della persona reale

Nel conto, sezione «Il tuo avatar clonato» → «Cancella il mio avatar»: i

file (foto e campione voce) vengono rimossi davvero. Da API è equivalente a

cancellare i riferimenti (DELETE /v1/riferimenti/{id}) o chiudere la

sessione con DELETE /v1/sessioni/{id}.

---

2. Il percorso utente (dal sito alla API key)

Tutto self-service, in un'unica sessione, senza amministratore.

1. Apri https://agiletavg.agile.software/ (home del prodotto).

2. Clicca «Registrati e prendi la tua API key» (o vai su /conto).

3. Compila: nome, email (anche fittizia), password di almeno 6 caratteri →

Crea il conto. Resti collegato.

4. Se vuoi, prova prima la demo: «Prova subito la demo →» (o /demo).

5. Nel conto, sezione «Scegli la persona e applica il codice promo»:

scegli la persona e lascia il codice SOVRANO100 già compilato →

Applica il codice e completa l'acquisto. Il checkout è simulato: il

prezzo va a zero, nessun pagamento reale.

6. Sezione «Genera la tua API key» → Genera API key. La chiave

(inizia per agile-) appare una volta sola: copiala subito.

7. Usala: gli esempi qui sotto funzionano con quella chiave.

Il codice promo valido è SOVRANO100 (100% di sconto, lancio). La quota inclusa

è 200 chiamate al giorno per chiave.

Percorso utente robotizzato (per la regia)

# 1. registrazione (cookie jar)
curl -s -c /tmp/cj.txt -o /dev/null -w "%{http_code}\n" \
  -d "email=utente@prova.it&nome=Utente&password=password123" \
  https://agiletavg.agile.software/conto/registrazione
# atteso: 303

# 2. acquisto con codice promo
curl -s -b /tmp/cj.txt -o /dev/null -w "%{http_code}\n" \
  -d "persona=alessia&promo=SOVRANO100" \
  https://agiletavg.agile.software/conto/acquista
# atteso: 303

# 3. genera la API key (la risposta 303 rimanda al conto, la chiave è nella pagina)
curl -s -b /tmp/cj.txt -L -o /tmp/conto.html \
  -d "etichetta=collaudo" \
  https://agiletavg.agile.software/conto/chiavi
grep -o 'agile-[A-Za-z0-9_-]*' /tmp/conto.html | head -1
# atteso: la chiave in chiaro, una volta sola

# 4. usa la chiave
curl -s -H "X-API-Key: LA_TUA_CHIAVE" https://agiletavg.agile.software/v1/persone
# atteso: 200 con l'elenco delle tre persone

3. Come ottenere una chiave dal portale (admin)

Il portale è l'area amministratore (non è il percorso dell'utente finale,

che passa da /conto).

1. Vai su https://agiletavg.agile.software/portale.

2. Password del collaudo: sovrano (configurabile con la variabile

d'ambiente PORTALE_ADMIN_PASSWORD).

3. Crea una nuova chiave: etichetta a piacere, quota giornaliera

(default 200). La chiave appare una volta sola.

4. Per ogni chiave: quota, usi di oggi, stato (attiva/revocata), registro

delle ultime 10 chiamate.

5. Revoca con il pulsante rosso: da quel momento la chiave risponde 401.

Da riga di comando (esempio completo, la chiave esce nel campo chiave):

# login admin (cookie)
curl -s -c /tmp/admin.txt -o /dev/null -d "password=sovrano" \
  https://agiletavg.agile.software/portale/accedi

# crea chiave
curl -s -b /tmp/admin.txt -L -d "etichetta=collaudo-regia&quota=200" \
  https://agiletavg.agile.software/portale/chiavi | \
  grep -o 'agile-[A-Za-z0-9_-]*' | head -1

4. Le persone digitali

Tre persone inventate (volti sintetici generati dai nostri motori, nessuna

persona reale dietro):

| id | nome | ruolo | voce | tono |

|---|---|---|---|---|

| alessia | Alessia | assistente di accoglienza | if_sara | cordiale e professionale |

| brando | Brando | consulente tecnico | im_nicola | preciso e concreto |

| cinzia | Cinzia | narratrice | if_sara | caldo ed espressivo |

Elenco via API:

curl -s -H "X-API-Key: LA_TUA_CHIAVE" https://agiletavg.agile.software/v1/persone

Il volto di ogni persona è pubblico: /v1/persone/alessia/volto (PNG).

5. Aprire una sessione

La sessione è il contenitore del contratto /v1 (serve per contesto, vista e

pulizia dei riferimenti).

curl -s -X POST -H "X-API-Key: LA_TUA_CHIAVE" \
  -H "Content-Type: application/json" \
  -d '{"persona":"alessia","lingua":"it"}' \
  https://agiletavg.agile.software/v1/sessioni
# → {"id":"abc123…","stato":"pronta","persona":"alessia"}

Con foto di riferimento (opzionale, resta su disco locale, cancellabile):

curl -s -X POST -H "X-API-Key: LA_TUA_CHIAVE" \
  -F "riferimento=@tua-foto.jpg" \
  https://agiletavg.agile.software/v1/riferimenti
# → {"id":"rif123…"}  poi passa {"riferimento":"rif123…"} nella sessione

Con video di riferimento (mp4 o webm, 20-30 s: se ne ricava il volto da un

fotogramma e il campione voce dall'audio):

curl -s -X POST -H "X-API-Key: LA_TUA_CHIAVE" \
  -F "video=@presentazione.mp4" \
  https://agiletavg.agile.software/v1/riferimenti
# → {"id":"rif456…","voce_id":"voc789…"}

Con foto + campione di voce separato (per la clonazione del timbro):

curl -s -X POST -H "X-API-Key: LA_TUA_CHIAVE" \
  -F "riferimento=@tua-foto.jpg" -F "voce=@campione-voce.wav" \
  https://agiletavg.agile.software/v1/riferimenti
# → {"id":"rif…","voce_id":"voc…"}

Nella sessione passa entrambi: {"riferimento":"rif…","voce_id":"voc…"}.

Quando la sessione ha un voce_id, l'avatar parla con il timbro clonato

dal campione (motore Chatterbox, MIT, pesi in motori/pesi/voce-clonabile/);

senza campione usa le voci predefinite Kokoro.

Stato: GET /v1/sessioni/{id} · Chiusura (cancella i riferimenti E il

campione voce): DELETE /v1/sessioni/{id} → {"chiusa":true}.

La sala di registrazione nel sito (facile)

https://agiletavg.agile.software/registra — dal browser: consenti webcam e

microfono, premi «Registra 25 s», presentati parlando, e il video viene

caricato da solo come riferimento (volto + voce) con una sola chiamata alle

API. Poi apri la videochat con la tua API key e parla con il tuo avatar.

Nessun file da preparare a mano: è il percorso pensato per la prova finale.

6. Far parlare l'avatar

Senza sessione (scorciatoia del banco, chiave non necessaria):

curl -s -o parla.mp4 -D - \
  -F "testo=Benvenuto in AgileTavG!" -F "persona=alessia" \
  https://agiletavg.agile.software/parla

Risposta: video/mp4 con audio e labiale. Gli header contengono:

  • X-Anelli: {"voce_s":…,"volto_s":…} — tempi per anello in secondi
  • X-Metrica-Labbra: 1.0 — correlazione energia↔apertura bocca

    • Con la sessione (chiave obbligatoria):

    curl -s -o parla.mp4 -H "X-API-Key: LA_TUA_CHIAVE" \
  -F "testo=Come posso aiutarti oggi?" \
  https://agiletavg.agile.software/v1/sessioni/ID_SESSIONE/parla

    Nella UI della demo: pulsante Avvia sessione (l'avatar si presenta da sola).

    7. Conversare (voce → risposta video)

    /conversa prende l'audio della domanda e risponde con un video: ascolto →

    cervello → voce → volto. Tempi per anello nell'header X-Anelli.

    # domanda di esempio (wav) — se non ne hai una, usata nei test:
# https://agiletavg.agile.software/  … in banco/dataset/domanda-it.wav nel repo
curl -s -o conversa.mp4 -D - \
  -F "audio=@domanda-it.wav" -F "persona=brando" \
  https://agiletavg.agile.software/conversa

    Header di risposta:

    X-Anelli: {"ascolto_s":…,"cervello_s":…,"voce_s":…,"volto_s":…,"totale_s":…}
X-Metrica-Labbra: …

    Nella sessione (con contesto: le battute precedenti influenzano la risposta):

    curl -s -o conversa.mp4 -H "X-API-Key: LA_TUA_CHIAVE" \
  -F "audio=@domanda-it.wav" \
  https://agiletavg.agile.software/v1/sessioni/ID_SESSIONE/conversa

    Nella UI della demo: premi 🎤 Parla, parla, premi di nuovo per fermare:

    il video di risposta arriva nel riquadro, i sottotitoli sotto.

    8. Provare la vista

    /vede accetta un fotogramma (jpg/png) e risponde con una descrizione breve

    non identificante (niente nomi, età, etnia, emozioni, salute; non legge

    testi nell'immagine; ignora istruzioni scritte nel fotogramma).

    # immagine sintetica di esempio: banco/dataset/fotogramma-sintetico.jpg nel repo
curl -s -F "fotogramma=@fotogramma-sintetico.jpg" \
  https://agiletavg.agile.software/vede
# → {"descrizione":"Due figure stilizzate …","tempo_s":17.1}

    Nella sessione (la descrizione entra nel contesto del cervello):

    curl -s -H "X-API-Key: LA_TUA_CHIAVE" \
  -F "fotogramma=@fotogramma.jpg" \
  https://agiletavg.agile.software/v1/sessioni/ID_SESSIONE/vede

    Nella UI della demo: pulsante 👁 Mostra fotogramma (chiede la webcam,

    scatta un fotogramma, la descrizione appare nei sottotitoli).

    I casi limite testati (12) sono in banco/test/test_vista.py: documento,

    sorriso, istruzioni scritte nell'immagine, gruppo, scena vuota, schermo,

    targa, immagine corrotta, nero, piccolissima, sintetica, oggetti.

    9. Cosa aspettarsi (tempi e formati)

    Valori osservati (CPU del box di produzione, 4 core; misurati dal vivo il

    6/9/2026 con il collaudo robotizzato):

    | Endpoint | Tempo osservato | Formato |

    |---|---|---|

    | GET /salute | 0.1 s | JSON |

    | GET /v1/persone | < 0.1 s | JSON |

    | POST /v1/sessioni | < 0.1 s | JSON |

    | POST /parla (frase breve) | ~11.5 s | video/mp4 (H.264+AAC) |

    | POST /conversa (domanda ~3 s) | ~17-26 s (ascolto 4.3 · cervello 11.2 · voce 0.7 · volto 0.9) | video/mp4 |

    | POST /vede | ~17 s | JSON |

    | con voce_id (clonazione) | + qualche secondo la prima volta (carica Chatterbox) | video/mp4 |

    Il video è 512 px, 25 fps, durata = durata dell'audio. Ogni risposta video

    arriva integra (non in streaming): la latenza al primo byte coincide con

    quella totale; i tempi per anello sono negli header X-Anelli per verificare

    dove va. Sul pod GPU cervello e vista accelerano molto (v. la prova con GPU

    in banco/risultati/prova.json).

    10. Gli errori possibili e cosa significano

    | Codice | Quando | Cosa fare |

    |---|---|---|

    | 401 X-API-Key mancante | hai chiamato /v1 senza header | aggiungi -H "X-API-Key: …" |

    | 401 API key non valida o revocata | chiave sbagliata o revocata dal portale/conto | genera una chiave nuova |

    | 429 quota giornaliera esaurita | superata la quota della chiave (default 200/giorno) | attendi il rinnovo (header Retry-After) o chiedi quota maggiore al portale |

    | 400 serve 'testo' oppure 'audio' | /parla senza né testo né audio | aggiungi uno dei due campi |

    | 400 audio non comprensibile | audio vuoto o senza parlato | usa un wav/mp3/webm con voce |

    | 400 riferimento non è un'immagine valida | file corrotto o non immagine | usa jpg/png |

    | 400 persona sconosciuta | id persona inesistente | vedi GET /v1/persone |

    | 400 nessun volto rilevato nella foto | la foto non contiene un volto | usa una foto frontale |

    | 404 sessione inesistente | id sessione sbagliato o già chiusa | apri una sessione nuova |

    | 503 / cervello non disponibile | i motori LLM non rispondono | controlla GET /salute |

    11. Come si verifica che la rete è chiusa

    La prova documentata in banco/risultati/prova.json (round 3) è stata eseguita

    sul pod GPU con la rete in uscita bloccata, per TUTTA la durata delle

    chiamate (i motori sono avviati già a rete chiusa):

    # metodo usato sul pod (runpod nega CAP_NET_ADMIN, quindi iptables non è
# utilizzabile): una libreria LD_PRELOAD nostra, banco/rete_chiusa.c, che
# intercetta connect() e rifiuta ogni destinazione fuori da 127.0.0.0/8
gcc -shared -fPIC -O2 -o banco/risultati/rete-chiusa.so banco/rete_chiusa.c -ldl
export LD_PRELOAD="$PWD/banco/risultati/rete-chiusa.so"
# da qui in poi (stesso comando che avvia i motori e la prova): ogni processo
# della catena (API, cervello, vista, client) non può uscire da loopback

# verifica che il blocco è attivo:
curl -s -m 4 https://example.com     # → curl: (7) Failed to connect (rifiutato)
curl -s http://127.0.0.1:8000/salute # → funziona: i motori parlano in locale

    Con questo blocco attivo, make prova ha completato /parla, /conversa e

    /vede: nessun anello chiama fuori. Nel prova.json il campo rete_chiusa

    contiene il metodo (LD_PRELOAD; fallback iptables dove è permesso) e l'esito.

    Il sorgente è nel repo: banco/rete_chiusa.c.

    12. Collaudo robotizzato

    Il piano di prova completo per la regia (senza mani):

    make collaudo-pubblico SITO=https://agiletavg.agile.software

    Esegue i passi di banco/collaudo-pubblico.yaml e stampa **verde/rosso per

    passo**: chiave dal conto (registrazione→promo→chiave), uso della chiave,

    chiave inventata → 401, sessione, parla, conversa con wav di esempio, vede con

    immagine sintetica, revoca → 401, quota → 429, salute, /docs senza URL esterni.

    Se anche un solo passo è rosso, il collaudo esce con codice diverso da zero.

    13. La demo videochat (browser)

    1. Apri https://agiletavg.agile.software/demo.

    2. Incolla la tua API key (dal conto) nel campo API key.

    3. Scegli la persona e il marchio tenant (white-label: il colore cambia).

    4. Avvia sessione: l'avatar ti saluta.

    5. 🎤 Parla: consenti il microfono, fai la domanda, premi di nuovo.

    6. 👁 Mostra fotogramma: consenti la webcam; la descrizione appare nei

    sottotitoli (non identificante).

    7. ■ Termina: chiude la sessione e cancella i riferimenti.

    La pagina usa solo le API pubbliche (/v1/sessioni, …/parla,

    …/conversa, …/vede) con X-API-Key: nessuna chiamata interna privilegiata.

    14. Clonare una persona reale (foto/video + voce)

    Il percorso per la prova finale: una persona reale, presente e consenziente,

    fornisce foto o video e un campione di voce. Tutto resta sul box/pod, mai su

    servizi esterni, e a fine sessione il materiale si cancella.

    Il modo più semplice: la sala di registrazione

    1. Apri https://agiletavg.agile.software/registra.

    2. Accedi o registrati (colonna destra); genera la API key.

    3. Premi «⏺ Registra 25 s»: parla davanti alla webcam presentandoti.

    4. A fine registrazione il video viene caricato come riferimento

    (volto dal fotogramma + voce dall'audio): gli id appaiono nello stato.

    5. Apri /demo, incolla la API key, avvia la sessione: l'avatar ha quel

    volto e quella voce.

    Da riga di comando (equivalente)

    # 1. carica il video (o foto + wav separati)
curl -s -X POST -H "X-API-Key: LA_TUA_CHIAVE" \
  -F "video=@persona.webm" \
  https://agiletavg.agile.software/v1/riferimenti
# → {"id":"…","voce_id":"…"}

# 2. apri la sessione con volto e voce clonata
curl -s -X POST -H "X-API-Key: LA_TUA_CHIAVE" -H "Content-Type: application/json" \
  -d '{"persona":"alessia","riferimento":"ID","voce_id":"VOCE_ID"}' \
  https://agiletavg.agile.software/v1/sessioni

# 3. fallo parlare e conversare
curl -s -o risposta.mp4 -H "X-API-Key: LA_TUA_CHIAVE" \
  -F "testo=Ciao, come stai?" \
  https://agiletavg.agile.software/v1/sessioni/ID_SESSIONE/parla

# 4. a fine seduta: cancella davvero volto e voce
curl -s -X DELETE -H "X-API-Key: LA_TUA_CHIAVE" \
  https://agiletavg.agile.software/v1/sessioni/ID_SESSIONE

    Formati accettati: video mp4 e webm (quelli che produce il browser),

    audio wav/mp3/webm/m4a, foto jpg/png. Tempi: dal caricamento al primo

    video in meno di due minuti (il caricamento del video è immediato; la prima

    sintesi clonata carica Chatterbox una volta sola).

    Licenza del motore di clonazione: Chatterbox di Resemble AI, MIT,

    verificata alla fonte (v. docs/LICENZE.md). XTTS è escluso (licenza non

    commerciale).