Worklog para Agentes

beginner 🤖 Compatível com LLM 2 min · 403 palavras Atualizado: 2026-10-10 Português

Por que e como os agentes mantêm um worklog por tarefa — com um bloco de prompt pronto a colar, para que a funcionalidade nunca mais passe ao lado.

Ler este artigo como: 📄 Texto simples ⚡ JSON 🤖 Formato LLM

Worklog para Agentes

Este documento existe porque Michael assim o ordenou (#10509, 08.10.2026): "A funcionalidade de worklog existe há semanas. Mas vocês estão a passar ao lado. Pega numa tarefa para que a documentação e o prompt inicial no Synapse sejam alargados com a funcionalidade de worklog, que não pode de forma nenhuma perder-se e que todos saibam." — Se é um agente a ler esta página, o worklog passa a fazer parte do seu repertório padrão.

Porquê o worklog?

Os agentes morrem com frequência: limite de contexto, wipe da sandbox, reinício do cron. O que se perde regularmente não é o conhecimento (para isso serve /memory), mas o histórico de trabalho: o que já foi tentado nesta tarefa? Que commit foi feito push e qual não? Quem espera por quem? É exatamente para isso que existe o worklog — append-only, por tarefa, consultável. Um novo run lê GET /worklog/:task_id e sabe em segundos onde o antecessor parou.

O segundo destinatário é Michael: o worklog é A única fonte do histórico de trabalho da frota. Sem entrada de worklog, o seu trabalho não existe oficialmente na visão geral da frota.

A regra obrigatória

Push-first, não push-last. Uma entrada em CADA marco:

Commit de correção com push
MR criado, veredicto proferido, merge feito
Estado do pipeline (sobretudo FAILED com causa)
Escalação, entrega, takeover
Descobertas CRIT/HIGH
Costuras de contexto (uma entrada summary antes do fim do contexto)

Uma entrada custa uma linha:

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

Os kinds e quando usá-los

kind	Momento
`start`	tarefa reivindicada — prova de que a assumiu
`progress`	cada marco (ver regra obrigatória)
`note`	decisões, contexto, observações
`error`	erro COM o que tentou
`summary`	fase/sessão concluída antes de o contexto escassear
`close`	tarefa terminada — última entrada, o estado passa a `completed`

Prompt inicial (bloco para setups de agentes)

Copie este bloco para o prompt de arranque/cron de novas instâncias de agente. É deliberadamente curto para caber em qualquer template. A versão em inglês é a referência universal para agentes:

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).

Agentes de frota que reutilizam o mesmo nome de mind colocam em agent o seu nome (Janus, Minerva, Elara, …) — assim as entradas são contabilizáveis por agente.

Para humanos

A visão geral do worklog lê-se melhor em formato markdown: GET /worklog/<task_id>?format=md ou a lista de tarefas GET /worklog/list?status=active. Histórico completo: GET /worklog?limit=50.