1050df780d
- Intent classification with LLM structured output (single/multi/ambiguous) - Discount agent with apply_discount and generate_coupon tools - Interrupt manager with 30-min TTL auto-expiration and retry prompts - Webhook escalation module with exponential backoff retry (max 3) - Three vertical industry templates (e-commerce, SaaS, fintech) - Template loading in AgentRegistry - Enhanced supervisor prompt with dynamic agent descriptions - 153 tests passing, 90.18% coverage
77 lines
4.8 KiB
Markdown
77 lines
4.8 KiB
Markdown
# 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.
|