Anatomía de un agente

Un agente de aiuda son cuatro piezas, todas en core/aiuda_core/:

1. System prompt (agents/<agente>/prompt.py)

Define quién es, sus reglas inquebrantables (numeradas, no negociables) y el contexto del negocio. Las reglas que el dueño agrega desde la consola se inyectan al final como sección aparte: se suman a los safeguards, nunca los sustituyen.

build_system_prompt(
    business_name="Taquería La Bonita",
    business_context="Aceptamos transferencia y OXXO...",
    user_rules=["A Constructora GAMA siempre de usted."],
)

2. Tools (agents/<agente>/tools.py)

Funciones con JSON Schema que el modelo puede invocar. La regla de oro: las descripciones dicen CUÁNDO usar el tool, no solo qué hace. Y las validaciones críticas viven en el código, no en el prompt: registrar_pago marca payment_reported=True, nunca paid — aunque el modelo quisiera, no puede cerrar una factura por dicho del cliente.

3. El loop (engine/llm.py)

Loop de tool-use manual sobre la API de Anthropic: permite gates de aprobación, registro de uso por iteración y modelos por tarea (Haiku para triage, Sonnet para redacción). Todo el acceso al LLM pasa por este módulo — el runtime es pluggable por diseño.

4. La máquina de aprobación (engine/approval.py)

draft → pending_approval → approved → sent
            └─ rejected         └─ failed → (reintento)

Transiciones válidas en código, estado en Postgres. El LLM redacta; el código decide qué se puede enviar. enviar solo es ejecutable sobre trabajos approved.

El patrón completo

LLM para lo que el LLM es bueno (redactar, clasificar, conversar) y código determinístico para lo que no se negocia (tonos por atraso, estados, verificación). Cuando dudes dónde poner una regla: si romperla cuesta dinero o confianza, va en código.

¿Qué sigue?

• Los 8 agentes
• Arquitectura