Intelligent Cabin Agent

Quick Start

Create and activate the Python 3.11 virtual environment:

uv venv .venv --python 3.11
source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Start the service:

.venv/bin/uvicorn app.main:app --host 127.0.0.1 --port 8000

Open the API docs:

http://127.0.0.1:8000/docs

Demo UI:

http://127.0.0.1:8000/demo

Architecture and flow review:

solution_review.md

The demo console supports:

local browser session history restore
runtime matcher/classifier/session backend switching
matcher routing debug panel with Top-K candidates
local rewrite -> keyword/classifier/retrieval -> fusion decision trace
direct display of classifier backend / raw label / fallback reason / raw candidate payload
workflow JSON visualization

Core APIs

POST /api/v1/agent/chat
POST /api/v1/agent/fill-slots
GET /health

Current Scope

Configurable session backend: memory / Redis
Config-driven intent registry
Router layer with pluggable matcher / extractor
Rule-based fast-path intent routing
Basic slot extraction
Plugin registry with mock handlers
Workflow response payloads

Runtime Config

AGENT_SESSION_BACKEND=memory|redis
AGENT_REDIS_URL=redis://127.0.0.1:6379/0
AGENT_REDIS_KEY_PREFIX=agent:session
AGENT_SESSION_TTL_SECONDS=86400
AGENT_MATCHER_PIPELINE=keyword
AGENT_SLOT_EXTRACTOR_BACKEND=heuristic
AGENT_CLASSIFIER_BACKEND=mock
AGENT_CLASSIFIER_THRESHOLD=1.2
AGENT_CLASSIFIER_BERT_THRESHOLD=0.0
AGENT_CLASSIFIER_MODEL_PATH=/path/to/model
AGENT_CLASSIFIER_LABEL_MAP_PATH=/path/to/label_map.json
AGENT_CLASSIFIER_REMOTE_URL=http://127.0.0.1:9000/classify
AGENT_CLASSIFIER_REMOTE_TIMEOUT_SECONDS=3.0
AGENT_LOCAL_EXECUTE_THRESHOLD=1.65
AGENT_LOCAL_ROUTE_TO_CLOUD_THRESHOLD=0.75
AGENT_LOCAL_CLARIFY_MARGIN_THRESHOLD=0.12
AGENT_PLANNER_BACKEND=heuristic|dashscope
AGENT_PLANNER_BASE_URL=https://your-base-url/v1
AGENT_PLANNER_API_KEY=your-api-key
AGENT_PLANNER_MODEL_NAME=qwen3.5-plus
AGENT_PLANNER_TIMEOUT_SECONDS=6.0

Matcher pipeline examples:

AGENT_MATCHER_PIPELINE=keyword
AGENT_MATCHER_PIPELINE=keyword,classifier,retrieval
AGENT_MATCHER_PIPELINE=keyword,retrieval
AGENT_MATCHER_PIPELINE=classifier
AGENT_MATCHER_PIPELINE=retrieval

Classifier backend examples:

AGENT_CLASSIFIER_BACKEND=mock
AGENT_CLASSIFIER_BACKEND=bert
AGENT_CLASSIFIER_BACKEND=remote
AGENT_CLASSIFIER_TOP_K=3

For local BERT models:

install optional runtime deps such as transformers and a backend like torch
point AGENT_CLASSIFIER_MODEL_PATH to the local model directory
if the model outputs labels like LABEL_0, provide AGENT_CLASSIFIER_LABEL_MAP_PATH
use AGENT_CLASSIFIER_BERT_THRESHOLD instead of the mock threshold

Example label map:

{
  "LABEL_0": "cs_query_order",
  "LABEL_1": "cs_cancel_order",
  "LABEL_2": "cabin_play_music"
}

Remote classifier expected request payload:

{
  "text": "我的订单现在什么情况 A808001",
  "top_k": 3,
  "labels": ["cs_query_order", "cs_cancel_order", "cabin_play_music"]
}

Remote classifier response payload:

{
  "intent_id": "cs_query_order",
  "label": "LABEL_0",
  "score": 0.982,
  "model_name": "bert-remote-v1",
  "candidates": [
    {"label": "LABEL_0", "intent_id": "cs_query_order", "score": 0.982},
    {"label": "LABEL_1", "intent_id": "cs_cancel_order", "score": 0.011},
    {"label": "LABEL_7", "intent_id": "cs_query_logistics", "score": 0.007}
  ]
}

When bert or remote is unavailable or below threshold, the classifier falls back to mock, and the demo debug panel shows both the attempted backend and the fallback reason.

Planner notes:

keep the planner key in environment variables, not in source code or front-end code
the planner uses POST {base_url}/chat/completions
for DashScope OpenAI-compatible endpoints, use the compatible v1 base URL and set AGENT_PLANNER_BACKEND=dashscope
when cloud planning is unavailable, the service falls back to a local heuristic planner for multi-command splitting

Next Steps

Replace rule router with classifier + retrieval + LLM
Connect real business plugins
Add automated tests

4.3 KiB Raw Permalink Blame History