agents_and_robots/dev/issues/completed/0049-automate-agent-personalization.md

0049 — Automatizar personalización al crear agentes

Objetivo

Reducir el trabajo manual del Paso 8 del pipeline de creación (editar agent.go, config.yaml y system.md a mano). Crear un script personalize.sh que genere los 3 archivos desde argumentos CLI, auto-detecte el proveedor LLM disponible en .env, y se integre en create-full.sh con flags opcionales para que Father Bot pueda completar el pipeline de creación con una sola llamada sin pasos manuales intermedios.

Contexto

El pipeline actual de 12 pasos ejecuta los pasos 1-7 con create-full.sh, pero el Paso 8 (Personalizar) siempre requiere editar manualmente 3 archivos:

1. agents/<id>/agent.go — package name, Register ID, reglas
2. agents/<id>/config.yaml — description, tone, prefix, llm.provider, llm.model, tools
3. agents/<id>/prompts/system.md — system prompt completo con sección de seguridad

Actualmente estos 3 archivos se generan con placeholders desde el template y se editan a mano. Esto es el principal cuello de botella: Father Bot (el agente creador) tarda varios pasos de tool calls para leer, editar y verificar cada archivo.

Adicionalmente, el provider/model LLM siempre defaultea a openai/gpt-4o aunque ANTHROPIC_API_KEY esté disponible y OPENAI_API_KEY no.

Arquitectura

Archivos afectados:

• dev-scripts/agent/personalize.sh — NEW — genera los 3 archivos desde argumentos JSON/flags
• dev-scripts/agent/create-full.sh — MODIFICAR — aceptar --description, --provider, --model, --system-prompt-file para invocar personalize.sh en el mismo pipeline
• dev-scripts/agent/detect-provider.sh — NEW — detecta el provider LLM disponible desde .env
• .claude/skills/create-agent/SKILL.md — MODIFICAR — actualizar instrucciones para usar los nuevos flags
• .claude/skills/create-bot/SKILL.md — MODIFICAR — ídem para robots
• .claude/rules/create_agent.md — MODIFICAR — actualizar pipeline con el nuevo paso 8 automático

Todo es shell scripting y documentación — no toca pkg/ ni shell/ (no hay componentes puros/impuros en Go).

Tareas

Fase 1: Detección automática de provider

• 1.1 Crear dev-scripts/agent/detect-provider.sh — lee .env y devuelve el primer provider disponible:
  • Si OPENAI_API_KEY está seteado y no vacío → openai gpt-4o
  • Si ANTHROPIC_API_KEY está seteado y no vacío → anthropic claude-sonnet-4-20250514
  • Fallback: openai gpt-4o (con warning)
• 1.2 Verificar que el script funciona en todos los casos (ambas keys, ninguna, solo una)

Fase 2: Script personalize.sh

• 2.1 Crear dev-scripts/agent/personalize.sh <agent-id> con flags:
  • --description "<texto>" — descripción del agente
  • --provider <openai|anthropic|claude-code> — proveedor LLM (default: auto-detect)
  • --model <modelo> — modelo LLM (default: según provider)
  • --tone <friendly|professional|casual|technical> — tono (default: friendly)
  • --prefix "<emoji>" — emoji prefix (default: 🤖)
  • --system-prompt "<texto>" — system prompt inline
  • --system-prompt-file <path> — system prompt desde archivo
  • --tool-use — habilitar tool_use en config
• 2.2 El script genera config.yaml aplicando los valores sobre el template generado por scaffold
  • Usar yq o sed para actualizar campos específicos del YAML
  • Preservar la estructura completa del config generado por scaffold
• 2.3 El script regenera agent.go con el package name correcto (sin guiones) y el Register ID exacto
  • El package name se deriva del agent-id: quitar guiones, quitar sufijo _bot/-bot
• 2.4 El script genera prompts/system.md combinando:
  • Header con identidad (nombre, rol)
  • Descripción del agente
  • Sección de capacidades (tools si --tool-use)
  • Estilo y tono
  • Sección de seguridad anti-injection (desde .claude/templates/security-prompt.md o hardcodeada)
  • Si se pasa --system-prompt o --system-prompt-file, usar ese contenido + append sección seguridad
• 2.5 Validar que los 3 archivos generados son correctos: go build -tags goolm ./... debe pasar

Fase 3: Integrar en create-full.sh

• 3.1 Añadir soporte de flags a create-full.sh — pasar flags opcionales al final:

  ./dev-scripts/agent/create-full.sh <id> "Display Name" [--description "..."] [--provider openai] [--system-prompt "..."]
  

• 3.2 Si se pasan los flags de personalización, ejecutar personalize.sh como Paso 8 automático dentro de create-full.sh — no se necesita edición manual posterior
• 3.3 Si no se pasan flags de personalización, comportamiento actual: scaffold + pasos 1-7 y dejar Paso 8 para edición manual
• 3.4 Añadir output claro indicando si el Paso 8 fue automático o manual pendiente

Fase 4: Actualizar skills y reglas

• 4.1 Actualizar .claude/skills/create-agent/SKILL.md — indicar que Father Bot debe usar --description, --provider, --system-prompt siempre que tenga la información del usuario, para evitar el Paso 8 manual
• 4.2 Actualizar .claude/skills/create-bot/SKILL.md — ídem para robots (solo --description y --prefix son relevantes)
• 4.3 Actualizar .claude/rules/create_agent.md — documentar el nuevo flujo: si se conocen todos los inputs, usar create-full.sh con flags; si no, editar manualmente como antes

Fase 5: Tests y cleanup

• 5.1 Test manual: crear un agente con todos los flags y verificar que los 3 archivos son correctos y go build pasa
• 5.2 Test: detect-provider.sh con todas las combinaciones de keys
• 5.3 Verificar que el flujo sin flags sigue funcionando igual (retrocompatibilidad)

Ejemplo de uso

Antes (flujo actual)

# Paso 1-7 (automático)
./dev-scripts/agent/create-full.sh weather-bot "Weather Bot"

# Paso 8 (manual — Father Bot edita 3 archivos)
# Edit agents/weather-bot/config.yaml → description, provider, model
# Edit agents/weather-bot/agent.go → package name
# Edit agents/weather-bot/prompts/system.md → system prompt completo

# Pasos 9-12
go build -tags goolm ./...
./dev-scripts/server/restart.sh
./dev-scripts/agent/health-check.sh weather-bot
./dev-scripts/agent/notify-developer.sh weather-bot agent "Weather Bot"

Después (flujo mejorado)

# Pasos 1-8 (automático, un solo comando)
./dev-scripts/agent/create-full.sh weather-bot "Weather Bot" \
  --description "Consulta el tiempo actual y predicciones meteorológicas" \
  --provider anthropic \
  --system-prompt "Eres Weather Bot, especialista en meteorología. Consultas el tiempo actual y das predicciones."

# Pasos 9-12 (igual que antes)
go build -tags goolm ./...
./dev-scripts/server/restart.sh
./dev-scripts/agent/health-check.sh weather-bot
./dev-scripts/agent/notify-developer.sh weather-bot agent "Weather Bot"

Auto-detección de provider

# Sin especificar provider → detect-provider.sh elige automáticamente
./dev-scripts/agent/create-full.sh news-bot "News Bot" \
  --description "Agente de noticias" \
  --system-prompt "Eres un agente de noticias..."
# → Detecta ANTHROPIC_API_KEY disponible → usa anthropic/claude-sonnet-4-20250514

Decisiones de diseño

1. personalize.sh como script atómico independiente: puede usarse fuera de create-full.sh para re-personalizar un agente existente. Misma filosofía que los otros scripts atómicos.
2. Flags opcionales en create-full.sh: retrocompatibilidad total — sin flags, funciona igual que hoy. Con flags, automatiza el Paso 8.
3. detect-provider.sh separado: reutilizable por otros scripts (health-check, etc.) que necesiten saber qué LLM usar.
4. system-prompt inline vs file: soporte para ambos — inline para prompts cortos desde CLI/Matrix, file para prompts largos pre-escritos.
5. Sección de seguridad siempre al final: personalize.sh siempre appenda la sección anti-injection al system prompt generado, sin excepción.
6. yq preferido sobre sed para YAML: editar YAML con sed es frágil. Si yq no está disponible, usar sed con patrones conservadores o reescribir el archivo desde template.

Prerequisitos

• Issue 0044 (pipeline formalizado) — completado ✓
• Issue 0048 (delete pipeline) — completado ✓

Riesgos

Riesgo	Mitigación
yq no disponible en el entorno	Verificar disponibilidad; fallback a sed con patrones cuidadosos o escribir el YAML completo desde bash
System prompt generado automáticamente es genérico	El flag --system-prompt permite override completo; la generación automática es solo el caso base
Package name derivado incorrectamente	Casos edge: IDs con números, IDs muy cortos. Validar con go vet post-generación
Retrocompatibilidad rota en create-full.sh	Mantener los primeros 2 argumentos posicionales sin cambio; los nuevos flags son opcionales