int-layer/docs/rag-migration-guide.md

RAG Migration Guide

Overview

This guide explains how to migrate from Dialogflow CX to the RAG (Retrieval-Augmented Generation) server for intent detection and response generation.

Architecture

The integration layer now supports both Dialogflow and RAG implementations through a common interface (IntentDetectionService). You can switch between them using a configuration property.

┌─────────────────────────────────────────┐
│  ConversationManagerService /           │
│  NotificationManagerService             │
└────────────────┬────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│    IntentDetectionService (interface)   │
└────────────┬────────────────────────────┘
             │
      ┌──────┴──────┐
      │             │
      ▼             ▼
┌──────────┐  ┌──────────┐
│Dialogflow│  │   RAG    │
│ Client   │  │  Client  │
└──────────┘  └──────────┘

Quick Start

1. Configure the RAG Server

Set the following environment variables:

# Select RAG as the intent detection client
export INTENT_DETECTION_CLIENT=rag

# RAG server URL
export RAG_SERVER_URL=https://your-rag-server.com

# Optional: API key for authentication
export RAG_SERVER_API_KEY=your-api-key-here

# Optional: Customize timeouts and retries (defaults shown)
export RAG_SERVER_TIMEOUT=30s
export RAG_SERVER_RETRY_MAX_ATTEMPTS=3
export RAG_SERVER_RETRY_BACKOFF=1s

2. Deploy and Test

Deploy the application with the new configuration:

# Using Docker
docker build -t capa-integracion:rag .
docker run -e INTENT_DETECTION_CLIENT=rag \
           -e RAG_SERVER_URL=https://your-rag-server.com \
           capa-integracion:rag

# Or using Maven
mvn spring-boot:run -Dspring-boot.run.profiles=dev

3. Monitor Logs

On startup, you should see:

✓ Intent detection configured to use RAG client
RAG Client initialized successfully with endpoint: https://your-rag-server.com

Configuration Reference

Intent Detection Selection

Property	Values	Default	Description
intent.detection.client	dialogflow, rag	dialogflow	Selects which implementation to use

RAG Server Configuration

Property	Type	Default	Description
rag.server.url	URL	http://localhost:8080	RAG server base URL
rag.server.timeout	Duration	30s	HTTP request timeout
rag.server.retry.max-attempts	Integer	3	Maximum retry attempts on errors
rag.server.retry.backoff	Duration	1s	Initial backoff duration for retries
rag.server.api-key	String	(empty)	Optional API key for authentication

Dialogflow Configuration (Kept for Rollback)

These properties remain unchanged and are used when intent.detection.client=dialogflow:

dialogflow.cx.project-id=${DIALOGFLOW_CX_PROJECT_ID}
dialogflow.cx.location=${DIALOGFLOW_CX_LOCATION}
dialogflow.cx.agent-id=${DIALOGFLOW_CX_AGENT_ID}
dialogflow.default-language-code=${DIALOGFLOW_DEFAULT_LANGUAGE_CODE:es}

Switching Between Implementations

Switch to RAG

export INTENT_DETECTION_CLIENT=rag

Switch Back to Dialogflow

export INTENT_DETECTION_CLIENT=dialogflow

No code changes required! Just restart the application.

What Stays the Same

✅ External API contracts - Controllers remain unchanged ✅ DTOs - DetectIntentRequestDTO and DetectIntentResponseDTO unchanged ✅ Conversation storage - Memorystore + Firestore persistence unchanged ✅ DLP obfuscation - Data Loss Prevention flow unchanged ✅ Session management - 30-minute timeout logic unchanged ✅ Notification handling - Notification storage and retrieval unchanged

What Changes

RAG Receives:

• Phone number (for internal conversation history tracking)
• Obfuscated user input (already processed by DLP)
• Notification context (when applicable)

RAG Returns:

• Response text (generated by RAG)
• Response ID (for tracking)
• Optional parameters (extracted/computed by RAG)

Data Flow

Conversation Flow

User Message
    ↓
DLP Obfuscation
    ↓
ConversationManagerService
    ↓
IntentDetectionService (RAG or Dialogflow)
    ↓
RagRequestMapper → RAG Server → RagResponseMapper
    ↓
DetectIntentResponseDTO
    ↓
Persist to Memorystore + Firestore
    ↓
Response to User

Notification Flow

Notification Event
    ↓
DLP Obfuscation
    ↓
NotificationManagerService
    ↓
Store Notification (Memorystore + Firestore)
    ↓
IntentDetectionService (RAG or Dialogflow)
    ↓
RagRequestMapper → RAG Server → RagResponseMapper
    ↓
DetectIntentResponseDTO
    ↓
Response to User

Redundancy by Design

The integration layer intentionally maintains redundant functionality to ensure safe migration:

1. Conversation History

   • Integration layer: Continues to store history in Memorystore + Firestore
   • RAG server: Maintains its own history by phone number
   • Why: Allows gradual migration without data loss

2. Session Management

   • Integration layer: Continues to enforce 30-minute timeout
   • RAG server: Handles session internally by phone number
   • Why: Preserves existing business logic

3. Parameter Passing

   • Integration layer: Continues to extract and pass all parameters
   • RAG server: Uses only what it needs (phone number, text, notifications)
   • Why: Maintains flexibility for future requirements

Troubleshooting

RAG Server Not Responding

Symptom: Errors like "RAG connection failed" or "RAG request timeout"

Solution:

1. Verify RAG_SERVER_URL is correct
2. Check RAG server is running and accessible
3. Verify network connectivity
4. Check RAG server logs for errors
5. Temporarily switch back to Dialogflow:

   export INTENT_DETECTION_CLIENT=dialogflow
   

Invalid RAG Response Format

Symptom: Errors like "Failed to parse RAG response"

Solution:

1. Verify RAG server implements the API specification (see docs/rag-api-specification.md)
2. Check RAG server response format matches expected structure
3. Review RagResponseMapper logs for specific parsing errors

Missing Phone Number

Symptom: Error "Phone number is required in request parameters"

Solution:

1. Verify external requests include phone number in user data
2. Check ExternalConvRequestMapper correctly maps phone number to telefono parameter

Dialogflow Fallback Issues

Symptom: After switching back to Dialogflow, errors occur

Solution:

1. Verify all Dialogflow environment variables are still set:
   • DIALOGFLOW_CX_PROJECT_ID
   • DIALOGFLOW_CX_LOCATION
   • DIALOGFLOW_CX_AGENT_ID
2. Check Dialogflow credentials are valid

Rollback Plan

If issues arise with RAG, immediately rollback:

Step 1: Switch Configuration

export INTENT_DETECTION_CLIENT=dialogflow

Step 2: Restart Application

# Docker
docker restart <container-id>

# Kubernetes
kubectl rollout restart deployment/capa-integracion

Step 3: Verify

Check logs for:

✓ Intent detection configured to use Dialogflow CX client
Dialogflow CX SessionsClient initialized successfully

Monitoring

Key Metrics to Monitor

1. Response Time

   • RAG should respond within 2 seconds (p95)
   • Monitor: Log entries with "RAG query successful"

2. Error Rate

   • Target: < 0.5% error rate
   • Monitor: Log entries with "RAG query failed"

3. Retry Rate

   • Monitor: Log entries with "Retrying RAG call"
   • High retry rate may indicate RAG server issues

4. Response Quality

   • Monitor user satisfaction or conversation completion rates
   • Compare before/after RAG migration

Log Patterns

Successful RAG Call:

INFO  Initiating RAG query for session: <session-id>
DEBUG Successfully mapped request to RAG format
INFO  RAG query successful for session: <session-id>, response ID: <response-id>

Failed RAG Call:

ERROR RAG server error for session <session-id>: status=500
WARN  Retrying RAG call for session <session-id> due to status code: 500
ERROR RAG retries exhausted for session <session-id>

Testing

Manual Testing

1. Test Regular Conversation

   curl -X POST http://localhost:8080/api/v1/dialogflow/detect-intent \
     -H "Content-Type: application/json" \
     -d '{
       "message": "¿Cuál es el estado de mi solicitud?",
       "user": {
         "telefono": "573001234567",
         "nickname": "TestUser"
       },
       "channel": "web",
       "tipo": "text"
     }'
   

2. Test Notification Flow

   curl -X POST http://localhost:8080/api/v1/dialogflow/notification \
     -H "Content-Type: application/json" \
     -d '{
       "text": "Tu documento ha sido aprobado",
       "phoneNumber": "573001234567",
       "hiddenParameters": {
         "document_id": "DOC-2025-001"
       }
     }'
   

Expected Behavior

• RAG should return relevant responses based on conversation context
• Response time should be similar to or better than Dialogflow
• All parameters should be preserved in conversation history
• Notification context should be used in RAG responses

Migration Phases (Recommended)

Phase 1: Development Testing (1 week)

• Deploy RAG to dev environment
• Set INTENT_DETECTION_CLIENT=rag
• Test all conversation flows manually
• Verify notification handling

Phase 2: QA Environment (1 week)

• Deploy to QA with RAG enabled
• Run automated test suite
• Perform load testing
• Compare responses with Dialogflow baseline

Phase 3: Production Pilot (1-2 weeks)

• Deploy to production with INTENT_DETECTION_CLIENT=dialogflow (Dialogflow still active)
• Gradually switch to RAG:
  • Week 1: 10% of traffic
  • Week 2: 50% of traffic
  • Week 3: 100% of traffic
• Monitor metrics closely

Phase 4: Full Migration

• Set INTENT_DETECTION_CLIENT=rag for all environments
• Keep Dialogflow config for potential rollback
• Monitor for 2 weeks before considering removal of Dialogflow dependencies

Future Cleanup (Optional)

After RAG is stable in production for 1+ month:

Phase 1: Deprecate Dialogflow

1. Add @Deprecated annotation to DialogflowClientService
2. Update documentation to mark Dialogflow as legacy

Phase 2: Remove Dependencies (Optional)

Edit pom.xml and remove:

<!-- Can be removed after RAG is stable -->
<!--
<dependency>
    <groupId>com.google.cloud</groupId>
    <artifactId>google-cloud-dialogflow-cx</artifactId>
</dependency>
<dependency>
    <groupId>com.google.protobuf</groupId>
    <artifactId>protobuf-java-util</artifactId>
</dependency>
<dependency>
    <groupId>com.google.api</groupId>
    <artifactId>gax</artifactId>
</dependency>
-->

Phase 3: Code Cleanup

1. Remove DialogflowClientService.java
2. Remove DialogflowRequestMapper.java
3. Remove DialogflowResponseMapper.java
4. Remove Dialogflow-specific tests
5. Update documentation

Note: Only proceed with cleanup after confirming no rollback will be needed.

Support

For issues or questions:

1. Check this guide and docs/rag-api-specification.md
2. Review application logs
3. Contact the RAG server team for API issues
4. Contact the integration layer team for mapping/configuration issues

Summary

• Minimal Code Changes: Only configuration needed to switch
• Safe Rollback: Can switch back to Dialogflow instantly
• Redundancy: Both systems store data for safety
• Gradual Migration: Supports phased rollout
• No External Impact: API contracts unchanged