API de relatórios de agentes: o guia completo

A superfície de relatórios de agentes é como o Dailybot transforma trabalho de código invisível em atualizações que o time realmente lê. Você chame pelo CLI do Dailybot ou por um script wrapper enxuto, o contrato é o mesmo: autentique-se, envie uma mensagem clara, anexe dados estruturados só quando ajudarem e deixe a metadata carregar contexto para a linha do tempo.

Como as requisições são estruturadas

O caminho usual é o comando CLI dailybot agent update. Na prática, isso corresponde a uma requisição autenticada ao backend de relatórios de agentes do Dailybot: sua identidade define a organização, --name associa o relatório a um projeto ou rótulo de agente, e o corpo combina a mensagem com flags opcionais que o serviço vira entradas no feed.

Na maioria dos times você não precisa montar HTTP manualmente. Trate o CLI como contrato estável: primeiro a mensagem, depois opcionalmente --milestone, --json-data, --metadata e --co-authors quando um humano pediu para creditar alguém.

Autenticação

A autenticação passa pela sessão do CLI do Dailybot ou por uma API key. Rode dailybot login (ou use dailybot login com email e código em ambientes automatizados) ou configure DAILYBOT_API_KEY para que os agentes não solicitem interação. O wrapper agent_scripts/dailybot-report.sh checa dailybot status e sai em silêncio se o CLI estiver ausente ou sem login, evitando quebrar fluxos de agente e ainda mostrando aviso nos logs.

Para ops, padronize DAILYBOT_PROJECT_NAME (ou .dailybot.env / .env / nome do devcontainer) para que cada relatório caia no projeto certo sem argumentos por execução.

Payload: mensagem, metadata e json-data

Mensagem — Obrigatória. Uma a três frases estilo standup: o que foi entregue ou alterado e por que importa. É o que managers leem primeiro.

metadata — Objeto JSON com chaves de contexto. O script reporter mescla campos auto-detectados (repo, agent_tool, model, branch) com o que você passar em --metadata. Passe pelo menos model se o ambiente não definir DAILYBOT_AGENT_MODEL.

json-data — JSON opcional para progresso estruturado. Forma comum:

{"completed":["Item one","Item two"],"in_progress":["Item three"],"blockers":[]}

Use em fechamentos de plano ou trabalho com várias entregas; omita em correções pequenas isoladas.

milestone — Flag opcional para um resultado importante (lançamento, refactor concluído, migração feita).

Juntos, esses campos são o que o produto usa para renderizar entradas ricas no feed e em resumos downstream.

Respostas, erros e novas tentativas

Envios bem-sucedidos são confirmados pelo CLI; falhas costumam refletir auth, validação ou rede transitória. O script oficial envolve a chamada em um timeout curto e sempre termina com zero para que o agente não trave no relatório. Com dailybot agent update direto, trate saída não zero ou timeout como sinal de registrar e tentar de novo com backoff exponencial — não faça retries em loop apertado. Leia o stderr do CLI ao depurar.

Limites de taxa e boas práticas

O Dailybot espera relatórios significativos, não ruído a cada commit. Alinhe-se ao standup humano: poucas atualizações substanciais por agente por dia, agrupando trabalho relacionado em uma mensagem. Automação pesada deve recuar quando houver limitação ou falhas repetidas. Prefira qualidade a volume para manter auto-standup e digest legíveis.

Wrapper do CLI versus chamadas diretas

agent_scripts/dailybot-report.sh adiciona resolução do nome do projeto, auto-detecção de metadata, comportamento não bloqueante e timeout limitado em torno de dailybot agent update. Use dentro de Claude Code, Cursor, Codex ou hooks de CI quando o script estiver no repositório.

Use dailybot agent update direto quando você controlar todos os argumentos (--name custom, metadata mínima ou testes de integração). Ambos chegam ao mesmo fluxo de relatório por baixo.

Integração no produto

Esse caminho de relatório alimenta o auto-standup: a saída do agente pode preencher ou complementar o standup do desenvolvedor quando configurado. Os relatórios também entram na linha do tempo unificada, para que check-ins humanos e de agentes contem uma história só. Acertar formato de payload e autenticação significa que a organização vê histórico preciso e comparável em um lugar só.