AI Lead Qualification Agent

Reusable AI lead qualification and routing automation built on n8n.

This repository contains a client-ready demo package for an automation that accepts inbound leads, normalizes the data, enriches company context, qualifies the lead with rules or AI-assisted analysis, routes the result, and records an audit-friendly outcome.

The demo is safe to run locally. It uses a local webhook receiver and mock/template persistence paths by default. No secrets or API keys are committed.

What It Does

The automation can connect to website forms, spreadsheets, CRMs, manual API calls, or webhook sources. A lead moves through this flow:

1. Lead Intake validates the incoming payload and preserves the raw source data.
2. Lead Normalizer maps source-specific fields into the Canonical Lead Object.
3. Company Intelligence Engine preserves and enriches company context such as industry, size, website, and domain.
4. Lead Qualification Engine scores the lead in rules_only, ai_only, or hybrid mode.
5. Routing Engine chooses destinations for qualified, nurture, or disqualified leads.
6. Dispatchers can send qualified leads to CRM, Slack/email-style notifications, webhook destinations, email tasks, or audit storage.
7. Master Orchestrator returns one final payload containing the core lead, intelligence, qualification, routing, dispatch, and audit results.

Demo Modes

• Rules-only demo mode: deterministic, no paid provider required, best for client walkthroughs and offline validation.
• Hybrid AI mode: combines deterministic rules with OpenRouter AI analysis. If configured with ai_failure_policy: "fallback_to_rules", the workflow can still produce a rules-based decision when the AI adapter is unavailable.
• Webhook receiver demo: routes qualified demo leads to target_key: "demo_sink", resolved by the Webhook HTTP Adapter to a local receiver.

Quick Start

Run the validation suite before importing workflows into n8n:

node scripts/demo-doctor.js
node scripts/n8n-runtime-check.js
node tests/e2e/run-e2e.js

Then follow:

• Demo Quickstart
• Local Setup
• Client Onboarding
• Troubleshooting
• Sales Demo Script

Required Environment Variables

Rules-only mode does not require provider credentials.

Hybrid AI mode with OpenRouter requires this variable in the n8n runtime environment:

OPENROUTER_API_KEY

Optional:

OPENROUTER_HTTP_REFERER

Do not paste secrets into workflow JSON, demo config files, or screenshots.

Important Demo Files

• demo/tenant-config.demo.json: safe demo tenant config used by the local demo.
• demo/sample-client-config.js: editable client-facing config example.
• demo/leads/qualified.json: expected to qualify and route to webhook.
• demo/leads/nurture.json: expected to route to nurture.
• demo/leads/disqualified.json: expected to disqualify.
• demo-webhook-receiver/receiver.js: local webhook receiver for demo delivery.

Workflow Import

Import workflow JSON files into n8n, publish them, then update the workflow IDs used by Master Orchestrator and provider adapters in the demo config:

• workflow_refs.*
• qualification.ai_provider_adapter.workflow_id
• webhook_dispatcher.provider_adapter.workflow_id
• dispatcher provider adapter workflow IDs

n8n may assign new workflow IDs during import. The demo config must use the IDs from your n8n instance.

Success Signal

A successful demo run returns master.orchestration.completed and includes:

• canonical_lead
• company_intelligence
• qualification_decision
• routing_decision
• dispatcher result objects for enabled dispatchers
• persistence/audit result when configured

For expected lead outcomes, see demo/EXPECTED_RESULTS.md.