API de reportes de agentes: la guía completa

La superficie de reportes de agentes es la forma en que Dailybot convierte trabajo de código invisible en actualizaciones que tu equipo sí lee. Ya lo invoques con el CLI de Dailybot o con un script wrapper delgado, el contrato es el mismo: autentícate, envía un mensaje claro, agrega datos estructurados solo si aportan, y deja que la metadata lleve el contexto a la línea de tiempo.

Cómo se estructuran las solicitudes

La vía habitual es el comando CLI dailybot agent update. En la práctica equivale a una petición autenticada al backend de reportes de agentes de Dailybot: tu identidad define la organización, --name asocia el reporte a un proyecto o etiqueta de agente, y el cuerpo combina el mensaje con flags opcionales que el servicio vuelve entradas en el feed.

No necesitas armar HTTP a mano en la mayoría de los equipos. Toma el CLI como contrato estable: primero el mensaje, luego opcionalmente --milestone, --json-data, --metadata y --co-authors cuando un humano te pidió acreditar a alguien.

Autenticación

La autenticación pasa por la sesión del CLI de Dailybot o por una API key. Ejecuta dailybot login (o usa dailybot login con email y código en entornos automatizados) o configura DAILYBOT_API_KEY para que los agentes no pidan interacción. El wrapper agent_scripts/dailybot-report.sh revisa dailybot status y sale en silencio si falta el CLI o no hay login, así no rompes flujos de agente y aun así ves el aviso en logs.

Para ops, estandariza DAILYBOT_PROJECT_NAME (o .dailybot.env / .env / nombre del devcontainer) para que cada reporte caiga en el proyecto correcto sin argumentos por ejecución.

Payload: mensaje, metadata y json-data

Mensaje — Obligatorio. Una a tres frases estilo standup: qué se entregó o cambió y por qué importa. Es lo primero que leen los managers.

metadata — Objeto JSON con claves de contexto. El script reporter fusiona campos auto-detectados (repo, agent_tool, model, branch) con lo que pases en --metadata. Pasa al menos model si tu entorno no define DAILYBOT_AGENT_MODEL.

json-data — JSON opcional para avance estructurado. Forma habitual:

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

Úsalo en cierres de plan o trabajo con varios entregables; omítelo en arreglos pequeños aislados.

milestone — Flag opcional para un resultado importante (lanzamiento, refactor terminado, migración hecha).

Juntos, estos campos son lo que el producto usa para mostrar entradas ricas en el feed y en resúmenes posteriores.

Respuestas, errores y reintentos

Los envíos exitosos los confirma el CLI; los fallos suelen deberse a auth, validación o red transitoria. El script oficial envuelve la llamada con un timeout corto y siempre termina en cero para que el agente no se quede bloqueado reportando. Si usas dailybot agent update directo, trata salida distinta de cero o timeout como señal de registrar y reintentar con backoff exponencial: no hagas reintentos en bucle cerrado. Lee el stderr del CLI cuando depures.

Límites de uso y buenas prácticas

Dailybot espera reportes con sustancia, no ruido por cada commit. Alineate con el standup humano: un puñado de actualizaciones relevantes por agente al día, agrupando trabajo relacionado en un solo mensaje. Si la automatización recibe señales de limitación o fallos repetidos, reduce frecuencia. Prioriza calidad sobre volumen para que auto-standup y digest sigan siendo legibles.

Wrapper del CLI versus llamadas directas

agent_scripts/dailybot-report.sh añade resolución del nombre de proyecto, auto-detección de metadata, comportamiento no bloqueante y un timeout acotado alrededor de dailybot agent update. Úsalo dentro de Claude Code, Cursor, Codex o hooks de CI cuando el script esté en el repo.

Usa dailybot agent update directo cuando controles todos los argumentos (un --name custom, metadata mínima o pruebas de integración). Ambos caminos apuntan al mismo flujo de reporte subyacente.

Integración en el producto

Este camino de reporte alimenta auto-standup: la salida del agente puede completar o complementar el standup del desarrollador si está configurado. Los reportes también entran en la línea de tiempo unificada, así los check-ins humanos y los del agente cuentan una sola historia. Acertar en forma de payload y autenticación implica que tu org ve historial preciso y comparable en un solo lugar.