Agent Configuration Architect

Agent Configuration Architect - Platform AI Solutions (v7.1.2)

1. Concepto: La Arquitectura de Agentes Nexus

Filosofía Multi-Capa

Nexus no usa un único system prompt estático. Utiliza una arquitectura de 3 capas para construir la inteligencia del agente en runtime:

• Capa 1: Template Base (Polimorfismo): Definida en agent_service/app/core/agent_templates.py. Provee la estructura de identidad y reglas core según el rol (Sales, Support, Leads, Logistics).
• Capa 2: Wizard Overrides (Identidad de Negocio): Datos específicos del cliente (Tono, Reglas de Negocio, Diccionario de Sinónimos) que sobreescriben los valores del template.
• Capa 3: Instrucciones de Tools (Táctica de Ejecución): Instrucciones detalladas sobre CÓMO usar cada herramienta y CÓMO formatear la respuesta, inyectadas dinámicamente.

2. Configuración de Templates (Wizard Defaults)

Los valores predeterminados para el Wizard se definen en orchestrator_service/app/api/agents.py → AGENT_TEMPLATES.

Ejemplo: Sales Agent (Pointe Coach inspired)

AGENT_TEMPLATES = {
    "sales": {
        "agent_name": "Agente de Ventas (IA)",
        "model_provider": "openai",
        "model_version": "gpt-4o",
        "temperature": 0.7,
        "defaultValue": {
            "agent_tone": "Sos una asesora experta en danza clásica... usamos voseo argentino...",
            "synonym_dictionary": "mallas: Leotardos\ncancanes: Medias...",
            "business_rules": "1. Prioridad: Venta asistida...\n2. Fitting: Ofrecer siempre para puntas...",
            "catalog_knowledge": "Categorías: Zapatillas, Medias, Leotardos, Accesorios.",
            "store_website": "https://pointecoach.com"
        }
    }
}

3. Dynamic Global Templates (v7.2+)

Nexus ahora soporta Templates Dinámicos almacenados en la base de datos. Esto permite crear plantillas que aparecen automáticamente en el Wizard de todos los inquilinos.

Lógica de Visibilidad

El endpoint /admin/agent-templates mezcla los templates hardcoded con los de la base de datos siguiendo esta lógica:

• is_template = TRUE: El registro es tratado como una plantilla, no como un agente vivo.
• tenant_id IS NULL: Template Global. Visible para todas las cuentas del sistema.
• tenant_id = X: Template Privado. Visible solo para el inquilino X.

Mapeo de Campos

El JSON en la columna config del template debe mapear a los campos expected del Wizard:

• store_description -> Descripción en el Wizard.
• agent_tone -> Tono y Personalidad.
• business_rules -> Reglas de Negocio.
• synonym_dictionary -> Diccionario de Sinónimos.

4. Instrucciones de Herramientas (Tool Config)

Cada herramienta tiene dos componentes de inyección de prompt definidos en orchestrator_service/main.py:

• Táctica (tactical_injections): Instrucciones sobre el proceso de pensamiento y validación antes de llamar a la tool.
• Guía de Respuesta (response_guides): Instrucciones sobre el formato y contenido de la salida (ej: Formato WhatsApp limpio, CTAs obligatorios).

Distribución de Instrucciones

El sistema busca instrucciones en este orden de prioridad:

• Personalización por Tienda: Configurada en el modal "Configurar Herramientas" (tenant.tool_config).
• Configuración de la Tool en DB: Tabla tools, campos prompt_injection y response_guide.
• Global Defaults: Diccionarios tactical_injections y response_guides en main.py.

4. Inyección Dinámica y Variables Mágicas

El Orchestrator inyecta variables en el prompt antes de enviarlo al agent_service:

• {STORE_NAME}: Nombre del comercio.
• {STORE_CATALOG_KNOWLEDGE}: Descripción del catálogo (Wizard).
• {STORE_DESCRIPTION}: Descripción del negocio.
• {store_website}: URL del sitio (usado en guías de respuesta).

5. El Proceso de "Trasplante" de Templates

Cuando integres un agente de un proyecto legacy o una configuración compleja (como Pointe Coach), utilizá la técnica de Distribución Multi-Capa:

| Componente | Ubicación en Código | Propósito |

| :--- | :--- | :--- |

| Identidad/Tono | agents.py (Wizard) | Estilo de habla y personalidad. |

| Reglas de Negocio | agents.py (Wizard) | Políticas de venta, derivación y fitting. |

| Diccionario | agents.py (Wizard) | Mapeo de términos informales a categorías. |

| Táctica de Tool | main.py (Tactical) | Lógica de búsqueda y validación. |

| Formato Respuesta | main.py (Response) | Estructura visual de los mensajes (WhatsApp). |

| Reglas de Calidez | templates.py (Base) | Puntuación, prohibiciones críticas (anti-markdown). |

> [!TIP]

> Consultá la skill Template_Transplant_Specialist para ver el proceso paso a paso de extracción textual 1:1.

6. Checklist de Arquitecto

• Wizard Alignment: Asegurate de que los campos agent_tone, business_rules y synonym_dictionary del Wizard lleguen como wizard_overrides al agent_service.
• Tool Parity: Verificá que el modal "Configurar Herramientas" en el Frontend muestre los defaults del sistema si no hay customización.
• Prompt Merge: Verificá en agent_service/main.py que el prompt final sea la unión de: template.build_system_prompt() + request.context.system_prompt + injected_content (RAG y Tools).
• Token Flow: Confirmá que el tiendanube_access_token se obtenga del Vault y se pase limpio al agent_service sin fallbacks legacy.

Protocolo Omega: En el 2026, los agentes se definen por su capacidad de seguir instrucciones tácticas precisas por herramienta. Menos "instrucciones generales" y más "guías de respuesta específicas".