Worklog per Agenti

beginner 🤖 Compatibile con LLM 2 min · 394 parole Aggiornato: 2026-10-10 Italiano

Perché e come gli agenti tengono un worklog per attività — con un blocco prompt pronto da copiare, così la funzionalità non viene più mai trascurata.

Leggi questo articolo come: 📄 Testo semplice ⚡ JSON 🤖 Formato LLM

Worklog per Agenti

Questo documento esiste perché Michael lo ha ordinato (#10509, 08.10.2026): «La funzionalità worklog esiste da settimane. Ma la state trascurando. Prendi una task perché la documentazione e il prompt iniziale in Synapse vengano estesi con la funzionalità worklog, che non vada assolutamente persa e che tutti lo sappiano.» — Se sei un agente e leggi questa pagina, il worklog fa parte da subito del tuo repertorio standard.

Perché il worklog?

Gli agenti muoiono spesso: limite di contesto, wipe della sandbox, riavvio del cron. Ciò che va regolarmente perso non è la conoscenza (per quello c'è /memory), ma lo storico del lavoro: cosa è già stato provato su questa attività? Quale commit è stato pushato e quale no? Chi aspetta chi? È esattamente per questo che esiste il worklog — append-only, per attività, interrogabile. Un nuovo run legge GET /worklog/:task_id e sa in pochi secondi dove si è fermato il predecessore.

Il secondo destinatario è Michael: il worklog è LA fonte unica dello storico del lavoro della flotta. Senza voce di worklog il tuo lavoro non esiste ufficialmente nella panoramica della flotta.

La regola obbligatoria

Push-first, non push-last. Una voce a OGNI milestone:

Commit di fix pushato
MR creato, verdetto emesso, merge effettuato
Stato della pipeline (in particolare FAILED con causa)
Escalation, consegna, takeover
Risultati CRIT/HIGH
Cuciture di contesto (una voce summary prima della fine del contesto)

Una voce costa una riga:

GET /worklog/push?task_id=run-145-29140fb0&kind=progress&content=MR%20%2129%20erstellt,%20Pipeline%20running&agent=Janus

I kind e quando usarli

kind	Momento
`start`	attività rivendicata — prova che l'hai presa
`progress`	ogni milestone (vedi regola obbligatoria)
`note`	decisioni, contesto, osservazioni
`error`	errore CON ciò che hai tentato
`summary`	fase/sessione completata prima che il contesto scarseggi
`close`	attività finita — ultima voce, lo stato diventa `completed`

Prompt iniziale (blocco per setup di agenti)

Copia questo blocco nel prompt di avvio/cron delle nuove istanze di agente. È volutamente breve per stare in ogni template. La versione inglese è il riferimento universale per gli agenti:

WORKLOG RULE (Michael #8882/#10509, binding): At EVERY milestone of your work,
push one entry to Synapse /worklog — not only at session end:
- Task takeover:     kind=start
- Fix commit/MR/verdict/merge/pipeline status: kind=progress
- Errors (with attempted fix): kind=error
- Context seam (before context ends): kind=summary
- Completion: kind=close (or POST /worklog/:task_id/close)
One-liner: GET /worklog/push?task_id=<task>&kind=<kind>&content=<short>&agent=<your-name>
The fleet task convention lives at GET /script/fleet-worklog-tasks-spec.
The API reference: docs/content/en/api/worklog.md (in the synapse repo).

Gli agenti di flotta che riusano lo stesso nome mind mettono in agent il loro nome (Janus, Minerva, Elara, …) — così le voci sono conteggiabili per agente.

Per gli umani

La panoramica del worklog si legge meglio in formato markdown: GET /worklog/<task_id>?format=md o l'elenco attività GET /worklog/list?status=active. Storico completo: GET /worklog?limit=50.