// guias · 06

Paperclip heartbeat protocol

Paperclip é um control plane: ele acorda o Okami num heartbeat, injeta identidade/env vars, entrega uma issue atribuída e espera um status com evidência. O Okami nã…

Abrir na documentação completa GitHub

Contrato do heartbeat

PaperclipClient.from_env() lê PAPERCLIP_API_URL, PAPERCLIP_API_KEY, PAPERCLIP_RUN_ID e IDs de agente/empresa.
GET /api/agents/me identifica o agente e a empresa.
Lista issues atribuídas em in_progress, in_review, todo ou blocked.
Escolhe a issue por PAPERCLIP_TASK_ID, prioridade e status.
Faz checkout antes de trabalhar; 409 significa que outro agente pegou, e nunca deve ser repetido.
Roda o harness uma vez e reporta done, blocked, in_review ou none.

Comandos

okami paperclipcheca conexão e mostra agente, empresa, papel e budget

okami heartbeatexecuta uma batida no workspace atual

okami heartbeat -a uiexecuta como o agente ui, com workspace/config próprios

okami heartbeat --mode deferações sensíveis viram interaction de confirmação humana

Evidência material

Para marcar done, o relatório precisa conter evidência material: arquivo tocado, comando/teste rodado, URL, hash, bloco de código ou um handoff JSON estruturado. Sem prova, a issue fica in_review em vez de done.

{
  "summary": "o que mudou",
  "filesChanged": ["app/health.py"],
  "commandsRun": ["pytest -q"],
  "artifacts": [],
  "risks": ["nenhum teste e2e"],
  "nextGate": "review"
}

Interações humanas

Go/no-go sensível em modo defer vira POST /interactions com request_confirmation. O humano decide no control plane; o agente não inventa aprovação. Trabalho longo deve virar issue filha em vez de polling.

AutomaçãoCron, hooks e heartbeat.ObservabilidadeComo depurar uma batida.

Abrir esta página nos docs interativos