How to Build an AI Troubleshooting Wizard

An ai troubleshooting wizard for customer self-service walks people through fixes step by step, adapting based on their answers. I build these for products with technical issues that follow logical decision trees. Instead of reading a long article and guessing which section applies, customers answer questions and the wizard narrows down the fix.

It is like having your best support agent available 24/7, working through the same diagnostic process they would.

What You Need Before Starting

• Documented troubleshooting flows from your support team
• Python 3.8+ with Flask and the Anthropic SDK
• Common issue categories and their resolution paths
• A frontend for the step-by-step interface

Step 1: Define Troubleshooting Trees

TROUBLESHOOTING_TREES = {
    "cant_login": {
        "first_question": "What happens when you try to log in?",
        "branches": {
            "error_message": {
                "question": "What error message do you see?",
                "branches": {
                    "invalid_password": {"solution": "Reset your password at /forgot-password. Check your spam folder for the reset email."},
                    "account_locked": {"solution": "Your account is locked after 5 failed attempts. Wait 30 minutes or contact support."},
                    "unknown_error": {"escalate": True}
                }
            },
            "blank_page": {
                "question": "Which browser are you using?",
                "branches": {
                    "chrome": {"solution": "Clear your Chrome cache: Settings > Privacy > Clear browsing data. Select 'Cached images and files.'"},
                    "safari": {"solution": "Clear Safari cache: Preferences > Privacy > Manage Website Data > Remove All."},
                    "other": {"solution": "Try using Chrome or Firefox. Our app works best on these browsers."}
                }
            },
            "page_not_loading": {"solution": "Check your internet connection. Try visiting google.com. If that works, try our status page at status.example.com."}
        }
    }
}

Step 2: Build the AI-Powered Flow

Let AI handle conversations that do not fit predefined trees:

import anthropic

client = anthropic.Anthropic()

SYSTEM_PROMPT = """You are a troubleshooting assistant for [Product Name].
Guide the customer through fixing their issue step by step.

Rules:
- Ask ONE question at a time
- Give clear, numbered steps
- After each step, ask if it worked
- If your steps do not fix it, offer to connect them with support
- Never guess. If you do not know, say so.

Known issues and fixes:
{known_issues}"""

def troubleshoot(session_id, user_message):
    history = get_session_history(session_id)
    history.append({"role": "user", "content": user_message})

    response = client.messages.create(
        model="claude-sonnet-4-20250514",
        max_tokens=300,
        system=SYSTEM_PROMPT.format(known_issues=load_known_issues()),
        messages=history
    )

    reply = response.content[0].text
    save_message(session_id, "assistant", reply)
    return reply

Step 3: Track Resolution Success

import sqlite3

def log_troubleshoot_outcome(session_id, issue_type, resolved, steps_taken):
    conn = sqlite3.connect("troubleshoot.db")
    conn.execute("""
        INSERT INTO outcomes (session_id, issue_type, resolved, steps_taken, completed_at)
        VALUES (?, ?, ?, ?, datetime('now'))
    """, (session_id, issue_type, resolved, steps_taken))
    conn.commit()

def get_resolution_rates():
    conn = sqlite3.connect("troubleshoot.db")
    return conn.execute("""
        SELECT issue_type,
               COUNT(*) as total,
               SUM(CASE WHEN resolved = 1 THEN 1 ELSE 0 END) as resolved,
               AVG(steps_taken) as avg_steps
        FROM outcomes
        GROUP BY issue_type
    """).fetchall()

Step 4: Learn from Failed Resolutions

def analyze_failures(days=30):
    conn = sqlite3.connect("troubleshoot.db")
    failures = conn.execute("""
        SELECT session_id, issue_type FROM outcomes
        WHERE resolved = 0 AND completed_at > datetime('now', ?)
    """, (f"-{days} days",)).fetchall()

    failure_patterns = {}
    for session_id, issue_type in failures:
        if issue_type not in failure_patterns:
            failure_patterns[issue_type] = 0
        failure_patterns[issue_type] += 1

    return sorted(failure_patterns.items(), key=lambda x: x[1], reverse=True)

Step 5: Add Visual Guides

Pair text steps with screenshots or diagrams:

STEP_VISUALS = {
    "clear_chrome_cache": {
        "image": "/images/help/chrome-clear-cache.png",
        "alt": "Chrome settings showing clear browsing data option"
    },
    "check_network": {
        "image": "/images/help/network-check.png",
        "alt": "Network diagnostics showing connection status"
    }
}

def enrich_step_with_visual(step_text, step_key):
    visual = STEP_VISUALS.get(step_key)
    if visual:
        return {"text": step_text, "image": visual["image"], "alt": visual["alt"]}
    return {"text": step_text}

What to Build Next

Add device and browser detection. When a customer starts the wizard, auto-detect their device and browser to skip irrelevant questions and show platform-specific instructions from the start.

Related Reading

• AI in Customer Service - troubleshooting wizards as first-line support
• Input, Process, Output: The Universal AI Framework - the troubleshooting wizard follows this exact pattern
• The Feedback Loop That Powers Everything - failed troubleshooting sessions improve the system