Skip to content

ADR-004: Personality-Driven Agent Architecture with Dual-Layer Design

Status: Accepted Date: 2025-10-25 Decision Makers: System Architect, Development Team Stakeholders: Product Team, UX Team, Compliance Team

Context

The loan processing system is implementing a revolutionary AI Dream Team user experience featuring personality-driven agents (Hawk-Income, Scarlet Witch-Credit, Doctor Strange-Risk, Cap-ital America) with celebration-focused messaging and voice-first mobile experience. The core architectural question is how to implement personality-driven responses while maintaining the technical integrity of the existing loan processing workflow.

Current Technical Foundation

  • 5 specialized agents: Intake → Credit → Income → Risk → Orchestrator
  • Microsoft Agent Framework with structured Pydantic responses
  • MCP servers for external verification (credit bureaus, document processing, financial calculations)
  • Performance-optimized processing (intake agent <10 seconds)
  • Comprehensive business logic in data models and utilities
  • Regulatory compliance and audit trail requirements

UX Vision Requirements

  • AI Dream Team with distinct personalities for each agent
  • Celebration-focused conversational responses
  • Animation triggers and UI enhancements
  • Voice-first mobile experience
  • Emotional intelligence and encouragement
  • Milestone recognition and progress celebration

Architectural Constraints

  • Cannot compromise loan processing accuracy: Technical decisions must remain unaffected
  • Regulatory compliance: Must maintain audit trails and compliance requirements
  • Performance requirements: Cannot degrade current processing speed
  • Team development: Technical and UX teams need parallel development capability
  • Fallback requirements: System must function if personality layer fails

Decision

Implement a Dual-Layer Architecture with complete separation between business logic and personality presentation layers.

Architecture Pattern: Presentation Wrapper with Enhanced Response Model

Layer 1: Technical Processing (Unchanged) - Preserve all existing technical agent personas exactly as-is - Maintain current MCP server integrations - Keep structured Pydantic response models - Continue regulatory compliance patterns

Layer 2: Personality Enhancement (New) - Add personality agents for conversational responses - Generate UI trigger data for animations - Provide celebration and encouragement messaging - Handle emotional intelligence and milestone recognition

Alternatives Considered

Alternative 1: Replace Technical Personas Entirely

Description: Merge personality instructions directly into existing technical personas. Rejected Because: - High risk of contaminating technical logic with presentation concerns - Difficult to maintain regulatory compliance - Cannot fallback to technical-only mode - Makes testing and validation complex

Alternative 2: Enhanced Single Agent

Description: Single agent with both technical and personality instructions. Rejected Because: - Violates separation of concerns principle - Personality changes could affect technical accuracy - Difficult to optimize each concern independently - Team development conflicts between technical and UX requirements

Alternative 3: Dual-Layer Architecture (SELECTED)

Description: Complete separation with presentation wrapper pattern. Selected Because: - Zero risk to core business logic - Perfect separation of concerns - Independent evolution of each layer - Fallback safety to technical-only mode - Parallel team development capability

Implementation Design

Enhanced Response Model

class EnhancedAssessment(BaseModel):
    """Enhanced assessment with personality presentation layer."""

    # Technical assessment (unchanged)
    technical_assessment: CreditAssessment | IncomeVerification | RiskAssessment

    # Personality presentation layer
    personality_response: PersonalityResponse

    # UI enhancement triggers
    ui_triggers: UITriggerResponse

class PersonalityResponse(BaseModel):
    """Personality-driven presentation data."""
    agent_name: str  # "Hawk-Income", "Scarlet Witch-Credit", "Doctor Strange-Risk", "Cap-ital America"
    celebration_message: str
    encouragement_note: str
    milestone_achieved: str | None
    emotional_tone: Literal["excited", "supportive", "professional", "celebratory"]

class UITriggerResponse(BaseModel):
    """UI enhancement and animation triggers."""
    animation_trigger: str | None  # "celebration", "progress", "milestone"
    progress_percentage: float
    status_badge: str  # "Great Progress!", "Excellent Credit!"
    next_step_preview: str

Agent Architecture Pattern

class PersonalityEnhancedCreditAgent:
    def __init__(self):
        # Layer 1: Technical processing (unchanged)
        self.technical_agent = CreditAgent()

        # Layer 2: Personality enhancement (new)
        self.personality_agent = ChatClientAgent(
            instructions=load_persona("marcus-personality-persona.md"),
            response_format=PersonalityResponse
        )
        self.ui_trigger_agent = ChatClientAgent(
            instructions=load_persona("ui-enhancement-persona.md"),
            response_format=UITriggerResponse
        )

    async def assess_with_personality(self, application: LoanApplication) -> EnhancedAssessment:
        # Technical assessment (unchanged)
        technical_result = await self.technical_agent.assess_credit(application)

        # Personality enhancement (new)
        personality_result = await self.personality_agent.run({
            "applicant_name": application.applicant_name,
            "credit_score": technical_result.credit_score,
            "risk_level": technical_result.risk_level.value
        })

        # UI triggers (new)
        ui_triggers = await self.ui_trigger_agent.run({
            "assessment_result": technical_result.model_dump(),
            "personality_tone": personality_result.emotional_tone
        })

        return EnhancedAssessment(
            technical_assessment=technical_result,
            personality_response=personality_result,
            ui_triggers=ui_triggers
        )

Data Flow Architecture

LoanApplication
     ↓
Technical Agent (unchanged)
     ↓
CreditAssessment (unchanged)
     ↓
Personality Agent (new)
     ↓
PersonalityResponse (presentation only)
     ↓
UI Trigger Agent (new)
     ↓
EnhancedAssessment (combined response)
     ↓
UI Layer (animations, celebrations)

Consequences

Positive Consequences

  1. Technical Integrity Preserved: Core loan processing logic remains completely unchanged
  2. Zero Business Risk: Technical decisions unaffected by personality layer
  3. Regulatory Compliance Maintained: Audit trails and compliance patterns unchanged
  4. Independent Evolution: Technical and personality layers can evolve separately
  5. Fallback Safety: Can disable personality layer without affecting core functionality
  6. Performance Optimization: Each layer can be optimized independently
  7. Parallel Development: Technical and UX teams can work simultaneously
  8. Testing Isolation: Technical and personality concerns tested separately

Negative Consequences

  1. Increased Complexity: Additional architectural layer to maintain
  2. Response Time Impact: Additional processing for personality and UI triggers
  3. Development Overhead: Need to maintain both technical and personality personas
  4. Resource Usage: Additional AI agent calls for personality enhancement

Risk Mitigation Strategies

  1. Performance Impact:
  2. Implement async processing for personality layer
  3. Cache personality responses for similar scenarios

  4. Optimize personality agent personas for speed

  5. Complexity Management:

  6. Clear interface contracts between layers
  7. Comprehensive testing at each layer

  8. Documentation for dual-persona maintenance

  9. Failure Handling:

  10. Graceful degradation to technical-only responses
  11. Circuit breaker patterns for personality layer
  12. Monitoring for personality agent performance

Implementation Phases

Phase 1: Foundation (Weeks 1-2)

  • Create enhanced response models (EnhancedAssessment, PersonalityResponse, UITriggerResponse)
  • Implement dual-layer agent wrapper pattern
  • Create personality persona templates for each agent character
  • Add fallback mechanisms for personality layer failures

Phase 2: Agent Personalities (Weeks 3-4)

  • Develop Scarlet Witch-Credit (Credit Analyst) personality persona and responses
  • Develop Hawk-Income (Income Specialist) personality persona and responses
  • Develop Doctor Strange-Risk (Risk Assessor) personality persona and responses
  • Develop Cap-ital America (Decision Coordinator) personality persona and responses
  • Implement UI trigger generation for animations and celebrations

Phase 3: Integration & Testing (Weeks 5-6)

  • Integrate personality layer with existing workflow
  • Comprehensive testing of dual-layer architecture
  • Performance optimization and caching strategies
  • Fallback mode testing and validation

Phase 4: UX Enhancement (Weeks 7-8)

  • UI integration for personality responses and animations
  • Voice-first mobile experience integration
  • Celebration and milestone recognition features
  • User acceptance testing and feedback incorporation

Success Metrics

Technical Metrics

  • Processing Time: No degradation in core technical processing time
  • Accuracy: 100% preservation of technical assessment accuracy
  • Reliability: 99.9% uptime for technical layer, graceful degradation for personality failures

User Experience Metrics

  • Engagement: Increased user satisfaction scores with personality-driven experience
  • Completion Rate: Improved loan application completion rates
  • Emotional Response: Positive user feedback on celebration and encouragement features

Operational Metrics

  • Development Velocity: Parallel technical and UX development capability
  • Maintenance: Separate maintenance cycles for technical and personality concerns
  • Testing: Independent testing strategies for each architectural layer

References

  • Microsoft Agent Framework Documentation
  • Current loan processing workflow specifications
  • UX Design specifications for AI Dream Team experience
  • Regulatory compliance requirements for loan processing
  • Performance benchmarks for current system

Notes

This architectural decision enables the revolutionary AI Dream Team user experience while maintaining complete technical integrity. The dual-layer design provides maximum flexibility for both technical accuracy and personality-driven user engagement, with clear separation of concerns and risk mitigation strategies.