Series 4 — Part 7 of 8

Agent modes are database-configured feature flags for AI capabilities. A client activates lead capture, objection handling, or appointment setting from an admin dashboard — no code change required. This article covers the mode system design, activation logic, and the admin interface.

Modes as Database Feature Flags

Each mode has a prompt_fragment that is injected into the system prompt when active, and an is_active flag that enables or disables it. Changing a mode's state takes effect on the next conversation — no deployment needed.

-- Default mode library (available to all clients)
CREATE TABLE mode_library (
  id              INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
  module_key      VARCHAR(60) NOT NULL UNIQUE,
  label           VARCHAR(100) NOT NULL,
  description     TEXT NOT NULL,
  default_fragment TEXT NOT NULL,  -- starting point; clients can customise
  category        ENUM('lead','sales','support','legal','custom') NOT NULL
);

INSERT INTO mode_library (module_key, label, description, default_fragment, category) VALUES
('lead_capture',      'Lead Capture',       'Collect contact details from prospects', '...', 'lead'),
('objection_handler', 'Objection Handling', 'Handle price and trust objections',      '...', 'sales'),
('product_guide',     'Product Guide',      'Explain features and use cases',          '...', 'sales'),
('appointment_setter','Appointment Setting','Book discovery calls',                    '...', 'sales');

Per-Client Mode Activation

def activate_mode(client_id: int, module_key: str, custom_fragment: str | None, db):
    lib_mode = db.query("SELECT * FROM mode_library WHERE module_key = ?", module_key)
    fragment = custom_fragment or lib_mode['default_fragment']

    db.execute("""
        INSERT INTO agent_modes (client_id, module_key, label, prompt_fragment, is_active)
        VALUES (?, ?, ?, ?, 1)
        ON DUPLICATE KEY UPDATE
          prompt_fragment = VALUES(prompt_fragment),
          is_active = 1
    """, client_id, module_key, lib_mode['label'], fragment)

    # Clear the system prompt cache for this client
    cache.delete(f"system_prompt:{client_id}")

def deactivate_mode(client_id: int, module_key: str, db):
    db.execute("UPDATE agent_modes SET is_active = 0 WHERE client_id = ? AND module_key = ?",
               client_id, module_key)
    cache.delete(f"system_prompt:{client_id}")

Admin Dashboard

The dashboard shows the mode library, with each mode as a toggle. Active modes show a customisation panel for the prompt fragment. Saving a custom fragment replaces the default and rebuilds the next request's system prompt automatically.

The dashboard also shows a live system prompt preview: the assembled prompt for the current mode configuration, with token count. This prevents admins from accidentally overflowing the context window.

What to Watch For

  • Mode conflicts — lead_capture and appointment_setter both try to collect user information. If both are active, the bot may ask for name and phone twice in one conversation. Validate conflict rules on activation.
  • Fragment quality — Bad fragment writing is the #1 source of bot misbehavior. Provide templates, show examples, and validate that fragments don't contain injection patterns before saving.
  • Priority ordering — When multiple modes are active, the priority field controls which mode's instructions appear first (and therefore carry more weight with the LLM). Expose priority in the admin UI.