egutierrez
f225d76eff
Pipeline de 12 pasos obligatorios: scaffold → build → register → verify E2EE → [convert robot] → auto-avatar → display name → personalize → rebuild → start → health check → self-introduce (el bot habla a devs) Nuevos pasos: display name automatico, health check post-arranque, y mejora del mensaje de bienvenida. Garantiza consistencia entre creacion manual (dev-scripts) y via father-bot. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
176 lines
8.4 KiB
Markdown
176 lines
8.4 KiB
Markdown
# 0044 — Formalizar pipeline de creacion de agentes
|
|
|
|
**Estado:** pendiente
|
|
|
|
## Objetivo
|
|
|
|
Definir, documentar y garantizar que el pipeline de creacion de agentes/robots sea completo, robusto y consistente — tanto cuando se ejecuta manualmente via `dev-scripts/` como cuando father-bot lo ejecuta via Matrix. El pipeline debe culminar siempre con el **propio bot recien creado enviando un mensaje de bienvenida a los desarrolladores**.
|
|
|
|
## Contexto
|
|
|
|
- `dev-scripts/agent/create-full.sh` ya ejecuta un pipeline de 6-7 pasos: scaffold → build → register → verify E2EE → [convert robot] → auto-avatar → notify-developer.
|
|
- `notify-developer.sh` ya usa el token del bot recien creado para enviar DMs a los devs listados en `DEVELOPER_MATRIX_USERS`.
|
|
- Father-bot (issue 0037) puede crear agentes via Matrix, ejecutando `create-full.sh` internamente.
|
|
- **Problema actual**: no hay garantia de que todos los pasos se ejecuten siempre ni de que el bot quede operativo antes de hablar a los devs. Falta un "health check" final.
|
|
|
|
## Pipeline formalizado
|
|
|
|
Estos son los pasos obligatorios, en orden estricto. Todo agente o robot creado debe pasar por TODOS:
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ PIPELINE DE CREACION DE AGENTES/ROBOTS │
|
|
│ │
|
|
│ 1. SCAFFOLD → crear archivos base desde template │
|
|
│ 2. BUILD → go build -tags goolm ./... │
|
|
│ 3. REGISTER → crear usuario Matrix + token │
|
|
│ 4. VERIFY E2EE → cross-signing + recovery key │
|
|
│ 5. CONVERT (robot) → eliminar LLM/prompts si type=robot │
|
|
│ 6. AUTO-AVATAR → generar y aplicar foto de perfil │
|
|
│ 7. DISPLAY NAME → configurar nombre visible en Matrix │
|
|
│ 8. PERSONALIZE → config.yaml, agent.go, system prompt │
|
|
│ 9. REBUILD → recompilar tras personalizacion │
|
|
│ 10. START/RESTART → arrancar el launcher con el bot │
|
|
│ 11. HEALTH CHECK → verificar que el bot esta activo │
|
|
│ 12. SELF-INTRODUCE → el bot envia bienvenida a los devs │
|
|
│ │
|
|
│ Env var requerida: DEVELOPER_MATRIX_USERS │
|
|
│ Si no esta definida, paso 12 se salta con warning. │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Detalle de cada paso
|
|
|
|
#### 1. SCAFFOLD
|
|
- Ejecutar `new-agent.sh <id> "Display Name"` o copiar desde template
|
|
- Crea: `agents/<id>/agent.go`, `config.yaml`, `prompts/system.md`, `data/`
|
|
- Registra blank import en `cmd/launcher/main.go`
|
|
|
|
#### 2. BUILD
|
|
- `go build -tags goolm ./...`
|
|
- Si falla: **STOP**, reportar error
|
|
|
|
#### 3. REGISTER
|
|
- `register.sh <id> "Display Name"`
|
|
- Crea usuario Matrix, genera token, password, pickle key
|
|
- Anade env vars a `.env`
|
|
|
|
#### 4. VERIFY E2EE
|
|
- `verify.sh <id>`
|
|
- Genera cross-signing keys, firma device
|
|
- Anade recovery key a `.env`
|
|
|
|
#### 5. CONVERT (solo robots)
|
|
- `convert-to-robot.sh <id>`
|
|
- Elimina config LLM, prompts, ajusta type a robot
|
|
|
|
#### 6. AUTO-AVATAR
|
|
- `agentctl auto-avatar <id>`
|
|
- Genera avatar automatico (DiceBear/RoboHash/Multiavatar)
|
|
- Lo sube como foto de perfil del usuario Matrix
|
|
|
|
#### 7. DISPLAY NAME (NUEVO)
|
|
- Configurar el display name en Matrix via API:
|
|
```
|
|
PUT /_matrix/client/v3/profile/@<id>:<server>/displayname
|
|
{"displayname": "<Display Name>"}
|
|
```
|
|
- Actualmente no se hace de forma consistente — el display name queda como el MXID
|
|
|
|
#### 8. PERSONALIZE
|
|
- Editar `config.yaml`: descripcion, LLM, tools, personalidad
|
|
- Editar `agent.go`: reglas especificas (si aplica)
|
|
- Escribir `prompts/system.md`: identidad, capacidades, seguridad
|
|
- **Incluir siempre seccion de seguridad anti-injection**
|
|
|
|
#### 9. REBUILD
|
|
- `go build -tags goolm ./...` tras personalizacion
|
|
- Si falla: corregir y reintentar antes de continuar
|
|
|
|
#### 10. START/RESTART
|
|
- `./dev-scripts/server/restart.sh` o arrancar el launcher
|
|
- Esperar ~5 segundos para que el bot sincronice
|
|
|
|
#### 11. HEALTH CHECK (NUEVO)
|
|
- Verificar en logs que el bot arranco correctamente:
|
|
- `"e2ee ready"` o `"starting matrix sync"`
|
|
- `"runner started"` o `"agent running"`
|
|
- Si no aparecen en 30s: **reportar error**, no continuar al paso 12
|
|
|
|
#### 12. SELF-INTRODUCE (MEJORAR)
|
|
- El **propio bot recien creado** envia DM a cada developer en `DEVELOPER_MATRIX_USERS`
|
|
- Mensaje de bienvenida con:
|
|
- Nombre y tipo (agent/robot)
|
|
- Descripcion breve de capacidades
|
|
- Comandos disponibles (si es robot)
|
|
- Instrucciones de uso ("Invitame a un room" o "Escribeme por DM")
|
|
- Usa `notify-developer.sh` (que ya usa el token del bot)
|
|
- Si `DEVELOPER_MATRIX_USERS` no esta definido: warning, no error
|
|
|
|
## Tareas
|
|
|
|
### Fase 1 — Display name automatico
|
|
|
|
- [ ] **1.1** Agregar paso de display name en `create-full.sh` (POST al API de Matrix con el token del bot)
|
|
- [ ] **1.2** Verificar que father-bot tambien ejecute este paso al crear agentes
|
|
- [ ] **1.3** Retroactivamente configurar display name para agentes existentes que no lo tengan
|
|
|
|
### Fase 2 — Health check post-arranque
|
|
|
|
- [ ] **2.1** Crear `dev-scripts/agent/health-check.sh <id>` que revise logs del agente buscando mensajes de arranque exitoso
|
|
- [ ] **2.2** Integrarlo en `create-full.sh` tras el restart (o tras notify, si el restart lo hace el usuario)
|
|
- [ ] **2.3** Father-bot debe ejecutar health check antes de confirmar al usuario
|
|
|
|
### Fase 3 — Mejorar mensaje de bienvenida
|
|
|
|
- [ ] **3.1** Enriquecer el mensaje de `notify-developer.sh`:
|
|
- Incluir descripcion del agente (leer de config.yaml)
|
|
- Incluir lista de tools habilitadas (si es agent con tools)
|
|
- Formato Markdown con estructura clara
|
|
- [ ] **3.2** Garantizar que el mensaje se envia DESPUES de que el bot este activo (health check ok)
|
|
- [ ] **3.3** Si el DM falla (el bot no esta synceando), reintentar 3 veces con backoff
|
|
|
|
### Fase 4 — Consistencia entre manual y father-bot
|
|
|
|
- [ ] **4.1** Documentar el pipeline completo (12 pasos) en `.claude/rules/create_agent.md`
|
|
- [ ] **4.2** Actualizar system prompt de father-bot para que ejecute TODOS los pasos, incluyendo:
|
|
- Display name (paso 7)
|
|
- Rebuild tras personalizacion (paso 9)
|
|
- Health check (paso 11)
|
|
- Self-introduce (paso 12)
|
|
- [ ] **4.3** Actualizar skill `/create-agent` y `/create-bot` para que sigan el mismo pipeline
|
|
- [ ] **4.4** Test E2E que verifique que el bot creado envia bienvenida a los devs
|
|
|
|
### Fase 5 — Cleanup y docs
|
|
|
|
- [ ] **5.1** Actualizar `CLAUDE.md` con el pipeline formalizado
|
|
- [ ] **5.2** Actualizar `dev-scripts/agent/README.md` con diagrama del pipeline
|
|
- [ ] **5.3** Agregar `DEVELOPER_MATRIX_USERS` a `.env.example` con documentacion
|
|
|
|
## Decisiones de diseno
|
|
|
|
1. **El bot mismo habla a los devs**: no un script externo ni otro bot. El `notify-developer.sh` ya usa el token del bot recien creado, asi que el DM viene del propio bot. Esto es intencional — los devs ven el mensaje directamente del bot nuevo.
|
|
|
|
2. **Health check antes de self-introduce**: si el bot no arranco, no puede enviar DMs. El health check evita intentos fallidos y da un diagnostico util.
|
|
|
|
3. **Display name obligatorio**: sin display name, el bot aparece como `@id:server` en Element, confundiendo a los usuarios. Debe configurarse siempre.
|
|
|
|
4. **Pipeline identico para manual y father-bot**: no debe haber diferencia en el resultado final. Un agente creado por `create-full.sh` y uno creado por father-bot deben pasar por los mismos 12 pasos.
|
|
|
|
5. **DEVELOPER_MATRIX_USERS como gate**: si no esta configurada, el paso 12 se salta con warning. Nunca bloquea la creacion.
|
|
|
|
## Prerequisitos
|
|
|
|
- Father-bot funcional (issue 0037) — completado
|
|
- Auto-avatar (issue 0042) — completado
|
|
- Scripts de creacion existentes — ya implementados
|
|
|
|
## Riesgos
|
|
|
|
| Riesgo | Mitigacion |
|
|
|--------|------------|
|
|
| Bot no arranca y no puede enviar bienvenida | Health check detecta el fallo antes de intentar |
|
|
| Display name no se actualiza (API falla) | Warning, no bloqueante; se puede corregir despues |
|
|
| Father-bot no ejecuta todos los pasos | System prompt actualizado con los 12 pasos; E2E test lo verifica |
|
|
| DEVELOPER_MATRIX_USERS no configurado | Warning explicito; documentado en .env.example |
|