smart-support/docs/phases/phase-2-dev-log.md

Phase 2: Multi-Agent Routing + Safety Layer -- Development Log

Status: COMPLETED Phase branch: phase-2/multi-agent-safety Date started: 2026-03-30 Date completed: 2026-03-30 Related plan section: Phase 2 in DEVELOPMENT-PLAN

What Was Built

• Intent Classification (app/intent.py): LLM structured output-based intent classifier with Pydantic models (IntentTarget, ClassificationResult). Supports single-intent, multi-intent, and ambiguity detection with configurable confidence threshold.
• Discount Agent (app/agents/discount.py): Mock agent with apply_discount (write + interrupt) and generate_coupon (read) tools. Validates discount range (1-100%).
• Interrupt Manager (app/interrupt_manager.py): TTL-based interrupt tracking with 30-minute auto-expiration. Provides register, check_status, resolve, cleanup_expired, and generate_retry_prompt methods. Complements SessionManager.
• Webhook Escalation (app/escalation.py): HTTP POST escalation with exponential backoff retry (max 3 attempts). Includes WebhookEscalator and NoOpEscalator implementations behind EscalationService protocol.
• Enhanced Supervisor Routing (app/graph.py): Supervisor prompt now includes dynamic agent descriptions. Intent classifier attached to graph for use by ws_handler routing layer. Multi-intent hint injection for sequential execution.
• Vertical Templates: Three industry YAML templates (e-commerce, SaaS, fintech) in backend/templates/.
• Template Loading (app/registry.py): load_template() and list_templates() class methods for template-based agent configuration.
• WebSocket Integration (app/ws_handler.py): Ambiguous intent sends clarification message. Interrupt TTL checked before resume -- expired interrupts return retry prompt. Interrupt manager registration on interrupt detection.

Code Structure

New files:

• backend/app/intent.py -- Intent classification models and LLM classifier
• backend/app/agents/discount.py -- Discount agent tools
• backend/app/interrupt_manager.py -- Interrupt TTL management
• backend/app/escalation.py -- Webhook escalation with retry
• backend/templates/e-commerce.yaml -- E-commerce agent template
• backend/templates/saas.yaml -- SaaS agent template
• backend/templates/fintech.yaml -- Fintech agent template

Modified files:

• backend/app/graph.py -- Intent classifier integration, dynamic supervisor prompt
• backend/app/agents/__init__.py -- Registered discount tools
• backend/app/agents/fallback.py -- Updated capability list
• backend/app/registry.py -- Template loading methods
• backend/app/config.py -- Webhook, template settings
• backend/app/ws_handler.py -- Interrupt manager + intent classification integration
• backend/app/main.py -- Wiring new modules, template loading, version bump to 0.2.0
• backend/agents.yaml -- Added discount agent
• backend/pyproject.toml -- Added httpx to main dependencies

Test files added:

• tests/unit/test_intent.py (11 tests)
• tests/unit/test_discount.py (13 tests)
• tests/unit/test_interrupt_manager.py (14 tests)
• tests/unit/test_escalation.py (11 tests)
• tests/unit/test_templates.py (9 tests)

Test files updated:

• tests/unit/test_graph.py -- Tests for classifier attachment and classify_intent
• tests/unit/test_ws_handler.py -- Tests for interrupt manager and clarification flow
• tests/unit/test_main.py -- Updated version check

Test Coverage

• Total tests: 153 (87 Phase 1 + 66 Phase 2)
• Overall coverage: 90.18%
• New module coverage:
  • intent.py: 100%
  • discount.py: 96%
  • interrupt_manager.py: 100%
  • escalation.py: 100%
  • graph.py: 100%
  • registry.py: 97%

Deviations from Plan

• Multi-intent handling uses supervisor prompt hint injection rather than a fully custom pre-routing graph node. This is simpler and leverages the existing langgraph-supervisor routing rather than fighting it.
• Webhook escalation is wired to main.py app.state but not yet connected to a specific agent tool (escalation trigger). The module is ready for use -- integration with fallback agent's escalation path is straightforward but deferred to avoid scope creep.
• The escalate_to_human tool mentioned in the plan was not created. The escalation module works standalone and can be triggered from ws_handler or agent tools in Phase 5.

Known Issues / Tech Debt

• SaaS and fintech templates reference tool names (get_account_status, change_plan, etc.) that don't have implementations. These are configuration blueprints for future use.
• Interrupt manager cleanup is not called on a schedule -- cleanup_expired() exists but no periodic task invokes it. Consider adding a background task in Phase 5.
• main.py coverage is 44% due to lifespan requiring real DB connection. Integration tests would cover this.