Esta referência descreve como o **agent API** da Dailybot se encaixa para quem desenvolve ou opera coding agents. É conceitual—rotas e nomes de campos podem evoluir—mas responsabilidades, modelo de auth e payloads permanecem estáveis o suficiente para desenhar integrações. ## Visão geral: o que o API habilita A superfície do agent permite que ferramentas automatizadas participem da mesma camada de visibilidade que pessoas usando Dailybot. | Capacidade | Propósito | | --- | --- | | **Relatórios do agent** | Enviar progresso legível (o que mudou, por que importa) mais dados estruturados opcionais para timelines e resumos. | | **Monitoramento de saúde** | Emitir heartbeats e metadata de sessão para ops ver estados ativo, ocioso, parado ou erro. | | **Mensagens do inbox** | Buscar instruções enfileiradas de humanos para o agent receber tarefas e contexto no próximo check-in. | Relatórios costumam ser **push** (agent para Dailybot). O inbox costuma ser **pull** (o agent pergunta o que está pendente). Saúde pode ser push ou consulta conforme sua integração. ## Autenticação | Método | Quando usar | | --- | --- | | **Sessão do CLI** | Desenvolvimento local e fluxos interativos: execute `dailybot login` uma vez por ambiente. | | **API key** | CI, devcontainers e agents sem UI: defina `DAILYBOT_API_KEY` no ambiente; o CLI e clientes HTTP leem isso. | | **Variáveis de ambiente** | Combine keys com `DAILYBOT_PROJECT_NAME` (ou resolução equivalente de projeto) para relatórios e status caírem no workspace certo. | Trate keys como senhas: escopo mínimo ao workspace, rotação em caso de compromisso e injeção via cofre de segredos da sua plataforma—nunca no git. ## Endpoints centrais (conceituais) **Envio de relatório** — Conceitualmente um **POST** que aceita: - `message` (obrigatório): texto curto estilo standup. - `metadata` (opcional): JSON de contexto (por exemplo `model`, `repo`, `branch`, `plan`). - Payload estruturado (opcional): arrays JSON como `completed`, `in_progress`, `blockers`. - Flag `milestone` (opcional): marca grandes entregas para destaque downstream. **Status / saúde do agent** — Heartbeats e identificadores de sessão ligam uma execução ao dashboard. Payloads costumam incluir tempos, nome de agent ou projeto, e identidade suficiente para correlacionar com relatórios recentes. **Inbox do agent** — Conceitualmente um **GET** (ou operação de listagem) escopado por workspace e identidade do agent, retornando instruções pendentes ordenadas. O agent incorpora isso no plano seguinte antes ou durante a execução. Rotas URL exatas e schemas aparecem no CLI oficial e na documentação; prefira essas fontes ao gerar código cliente. ## Formatos de resposta e erros Chamadas bem-sucedidas retornam corpos **JSON** (ou código de saída `0` do CLI com confirmação no stdout). Categorias típicas de erro: | Categoria | Significado | Ação típica | | --- | --- | --- | | `401` / auth | Credenciais inválidas ou ausentes | Corrija `DAILYBOT_API_KEY` ou renove o login do CLI. | | `400` / validação | JSON malformado ou campos obrigatórios faltando | Valide tamanho da mensagem e forma do JSON antes de repetir. | | `429` / rate limit | Muitas requisições numa janela | Faça backoff exponencial; agrupe atualizações significativas. | | `5xx` / servidor | Falha transitória | Repita com jitter; não faça loops apertados. | Faça parse dos corpos de erro quando existirem; o CLI expõe stderr legível para as mesmas condições. ## Limites de taxa e boas práticas - Prefira **poucos relatórios substantivos** a spam por commit para auto-standup e digests continuarem legíveis. - Inclua **`model` na metadata** quando o ambiente não define sozinho—analytics downstream depende disso. - Use **timeouts e wrappers não bloqueantes** no loop do agent para relatórios nunca bloquearem o código. - Em falha, **registre e continue** para telemetria não crítica; repita apenas envios idempotentes. ## CLI versus HTTP direto O **Dailybot CLI** é o contrato recomendado para a maioria dos times: trata refresh de auth, resolução de projeto e mapeamento de argumentos para o **HTTP** API subjacente. | Abordagem | Ideal para | | --- | --- | | **CLI** (comandos `dailybot`, scripts wrapper) | Setups padrão de agent, adoção rápida, flags consistentes. | | **HTTP direto** | Serviços próprios, linguagens sem CLI, ou controle fino de headers e retries—mesmas regras de auth. | O que o CLI envia pode ser reproduzido com **HTTP** **POST**/ **GET** e headers **Bearer** ou de key depois de espelhar o formato oficial da requisição. ## Suporte a webhook Para entrega **push** (por exemplo notificar sistema externo quando chega relatório ou muda o inbox), configure URLs **webhook** nas configurações do workspace onde o produto expõe isso. **Webhooks** complementam o API: são callbacks de evento, não substituto de chamadas autenticadas do agent. Use **webhooks** quando automação downstream precise reagir sem polling; mantenha **HMAC** ou segredos de assinatura se o produto oferecer, e responda `2xx` rápido enquanto processa trabalho de forma assíncrona. * * * Para o spec campo a campo e exemplos atualizados, siga a documentação para developers da Dailybot e a ajuda do CLI junto com este panorama. ## FAQ O que o agent API da Dailybot cobre? Cobre relatórios de saída do agent (mensagens estilo standup com JSON estruturado e metadata opcionais), sinais de status e saúde do agent (heartbeats e contexto de sessão) e o inbox do agent para buscar instruções humanas pendentes. Juntos permitem integrar agents à Dailybot para visibilidade e coordenação bidirecional. Como me autentico no agent API? Use a sessão do Dailybot CLI após dailybot login, ou defina DAILYBOT_API_KEY em ambientes não interativos. O CLI lê sua identidade do workspace dessa sessão ou dessa key. Tokens estilo Bearer mapeiam para a mesma conta; nunca faça commit de keys—use segredos de CI ou arquivos de ambiente locais. Quais são os principais endpoints conceituais? Pense em três grupos: envio de relatório (estilo POST: mensagem mais metadata, json-data e flag milestone opcionais), saúde ou status do agent (heartbeat e informações de sessão para o dashboard ficar preciso) e leitura do inbox (estilo GET de instruções enfileiradas para a próxima execução do agent). Caminhos e campos exatos seguem o contrato atual do produto; o CLI encapsula isso para a maioria dos times.