Skip to content

Redirect Handler

Overview

The Redirect Handler routes non-product conversations (support requests, off-topic questions) to appropriate resources without using the knowledge base. This provides faster responses and better visitor experience.

Handled Intents

Intent Description Typical Redirect
SUPPORT Existing customer support requests Support portal, help desk
OFFTOPIC Questions unrelated to the product Polite redirection
OTHER Miscellaneous non-product queries Contextual response

Architecture

flowchart TD A[Visitor message] --> B[intent_router] B --> C{Intent classification} C -->|PRODUCT| D[Normal RAG flow] C -->|SUPPORT| E[redirect_handler] C -->|OFFTOPIC| E C -->|OTHER| E E --> F[Cancel RAG retrieval] F --> G[Generate redirect response] G --> H[Return with redirect_type metadata]

Key Design Decisions

  1. Skips RAG - No knowledge base retrieval needed → faster response
  2. Cancels pending retrieval - If RAG was already started, it's cancelled
  3. 3-level prompt hierarchy - Meta → Agent → Client-specific instructions
  4. Analytics tracking - redirect_type in metadata for reporting

Key Files

Backend

File Purpose
ixchat/nodes/redirect_handler.py Main redirect logic
ixchat/nodes/intent_router.py Routes to redirect_handler
ixchat/retrieval_task_store.py Cancels pending RAG tasks
prompts/website-agent/response-agents/meta-template.md Shared meta-template
prompts/website-agent/response-agents/redirect/template.md Redirect-specific template
prompts/website-agent/response-agents/redirect/instructions/ Client-specific instructions

Prompt Hierarchy

The handler uses a 3-level prompt system:

website-agent/response-agents/meta-template                    (shared by all agents)
         ↓
website-agent/response-agents/redirect/template                (redirect-specific)
         ↓
website-agent/response-agents/redirect/instructions/{domain}   (optional, client-specific)

This allows: - Consistent base behavior across all sites - Redirect-specific instructions (tone, suggested resources) - Client-specific customization (support URLs, contact info)

Response Metadata

The handler adds metadata for analytics:

{
    "agent_type": "redirect",
    "redirect_type": "support",  # or "offtopic", "other"
    "model_used": "gpt-4.1-nano",
    "processing_pattern": "redirect_handler",
}

Example Responses

Support Intent

Visitor: "I'm having trouble logging into my account"

Bot: "I understand you're having login issues. For account support,
please visit our help center at support.example.com or contact
our support team at support@example.com. They'll be able to
assist you right away!"

Off-Topic Intent

Visitor: "What's the weather like today?"

Bot: "I'm here to help with questions about [Product]. Is there
anything specific about our features or pricing I can help you with?"

Debugging

Backend logs use the 🔀 [REDIRECT HANDLER] prefix:

🔀 [REDIRECT HANDLER] Handling SUPPORT intent for visitor
🔀 [REDIRECT HANDLER] Cancelled pending retrieval task
🔀 [REDIRECT HANDLER] Generated response (length: 180 chars)

Configuration

Client-specific redirect behavior can be configured via:

  1. Langfuse prompts - Custom redirect instructions per domain
  2. Agent config - Support URLs, contact information in agent_config table

Testing

poetry run pytest packages/ixchat/ixchat/tests/test_query_stream_redirect_handler.py -v