# 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](../DEVELOPMENT-PLAN.md#phase-2-多-agent-路由--安全层-第-3-4-周)

## 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.