通用决策代理：多代理客户支持协调器
通用决策代理是一个功能齐全的多代理支持自动化系统，由LangGraph、LangChain、FastMCP和SQLite构建而成。 它通过智能代理端到端地处理客户支持票，智能代理接收、分类、解决和上报问题，同时集成来自以下方面的数据：
知识库（KB）
账户与预订系统（CultPass）
长时程记忆
该系统使用Supervisor代理和工具动态选择操作，遵循支持实时决策和人工升级的分层多代理模式。
该项目达到并超过了Udacity的多代理编辑和决策轨道标准。
目录
- 概述
- 建筑与设计
- 多代理模式 - 架构图 - 状态模式
- 代理人和责任
- 知识、工具和MCP服务
- 票务处理流程
- 短期和长期记忆
- 存储库结构
- 安装说明
- 运行应用程序
- 运行测试
概述
Universal Decision Agent模拟生产级客户支持代理系统，能够：
- 了解入场券
- 对问题类型和紧急程度进行分类
- 在知识库中搜索解决方案
- 查找用户资料和预订
- 咨询长期记忆以了解以前的问题
- 尝试通过信心评分解决问题
- 需要时升级到人工智能
- 为支持团队提供结构化的解释
它运行在基于规则的路由和代理推理的混合体上，并通过表现得像外部微服务的FastMCP服务器集成多个数据源。
建筑与设计
多代理模式
系统采用Supervisor/Herarchical代理设计： \*Supervisor Agent充当中心路由器 \*招生代理对门票进行标准化 \*分类器代理确定问题特征 \*解析器代理使用工具和内存尝试解决方案 \*升级代理处理人工切换摘要 每个代理写入一个共享的LangGraph状态，主管根据不断演变的状态决定下一步。
架构图
状态管理
LangGraph状态架构：
class TicketState(TypedDict, total=False):
ticket: Dict[str, Any]
intake: Dict[str, Any]
classification: Dict[str, Any]
resolution: Dict[str, Any]
escalation: Dict[str, Any]
supervisor: Dict[str, Any]使用MemorySaver按线程_id存储。
测井和观测
UDA Hub实现了端到端的结构化JSON日志记录，因此可以通过Intake完全跟踪每张票→ 分类→ 主管→ 解析器→ 升级→ 完成。
所有日志都使用共享的JSON记录器（logger.get_log（））发出，由以下人员使用：
- agentic/workflow.py——节点生命周期、工具调用、主管决策、解析器评分
- 03_agentic_app.py--CLI+演示工作流事件
日志目的地
- 标准输出 –便于本地开发/调试
- 文件 –每行一个事件的JSONL文件：
logs/uda_hub.jsonl
每一行都是一个JSON对象，例如：
{
"timestamp": "2025-12-02T09:42:10.123456Z",
"level": "INFO",
"message": "supervisor_decision",
"extra": {
"ticket_id": "DEMO-TICKET-001",
"thread_id": "DEMO-TICKET-001",
"issue_type": "login",
"urgency": "high",
"complexity": "medium",
"next_step": "escalation",
"resolver_status": "needs_escalation",
"resolver_confidence": 0.2
}
}
系统记录：
- 节点生命周期事件
每个工作流节点都记录开始和结束事件：
* node_start_intake, node_end_intake
* node_start_classifier, node_end_classifier
* node_start_supervisor, node_end_supervisor
* node_start_resolver, node_end_resolver
* node_start_escalation, node_end_escalation字段包括：
* ticket_id
* thread_id- 主管决策
事件：主管_决策
捕获的字段：
* ticket_id, thread_id
* issue_type, urgency, complexity
* resolver_status (nullable)
* resolver_confidence
* next_step → resolver | escalation | done
* reason- 工具调用（MCP工具）
所有MCP工具都会发出开始和结束日志：
* tool_call_kb_search_start / tool_call_kb_search_end
* tool_call_account_get_user_start / tool_call_account_get_user_end
* tool_call_account_get_reservations_start / tool_call_account_get_reservations_end
* tool_call_memory_search_start / tool_call_memory_search_end捕获的字段：
* ticket_id, thread_id
* tool_name
* Sanitized inputs (e.g., query, external_user_id)
* Result metrics, e.g.:
* result_count
* memories_count
* reservations_count
* KB scoring:
* top_score
* lexical_overlap
* salient_overlap
* salient_tokens
* salient_hits- 解析器结果
解析器记录详细的决策信息：
* resolver_kb_confidence
* resolver_decision_resolved
* resolver_decision_needs_escalation字段包括：
* kb_result_count
* top_score
* lexical_overlap
* salient_overlap
* confidence
* Decision status- 最终工作流摘要
事件：工作流已完成
领域：
* ticket_id, thread_id
* final_status → resolved | needs_escalation
* final_confidence- CLI/演示事件
对于交互式或脚本化运行：
* cli_ticket_received
* cli_workflow_result
* demo_ticket_received
* demo_workflow_result字段包括：
* issue_type, urgency, complexity
* supervisor_next_step
* resolution_status
* resolution_confidence这些结构化日志提供：
* Full traceability of every ticket
* Complete visibility into agent decisions
* Debugging of KB search quality
* Auditing of tool interactions
* End-to-end observability for platform monitoring and analytics这使得能够对系统行为进行可靠的分析，并确保可以从第一次用户输入开始跟踪票证→ 没有黑匣子的最终解决方案。
代理人和责任
- 摄入剂
规范入场券内容。
输出：
- 总结
- 正常化问题
- 情绪
- 分类器代理
预测：
- issue_type（登录/计费/预订/帐户/其他）
- 紧急程度（低/中/高）
- 复杂性（低/中/高）
- 升级
- 原理
- 解析器代理
使用MCP工具：
- kb_search
- account_get_user
- account_get_user_reservations
- 记忆搜索
- 记忆_书写
生产：
- 状态：已解决/需求_升级
- 回答
- 信心
- 已使用_kb_文章
- notes_for_human
- 升级代理
生成人工准备摘要，包括：
- 问题摘要
- 推荐部门
- 下一步
- 可选包含解析器注释
- 主管代理
路线：
- 解析器
- 升级
- 完成
规则包括升级检查、解析器置信阈值和分类提示。
知识、工具和MCP服务
通用决策代理连接到三个FastMCP微服务：
KB服务器（KB/）
- 搜索知识库表
- 工具：kb_search（查询、限制）
帐户服务器（Account/）
- 获取用户资料+用户预订
- 工具：
account_get_user（external_user_id） account_get_user_reservations（external_user_id）
内存服务器（内存/）
- 长期内存写入和搜索
- 工具：
memory_write（…） memory_search（…） memory_get_all（外部用户id） 这些工具被包装并在解析器代理中使用。
票务处理流程
Incoming ticket
↓
Intake Agent (normalize)
↓
Classifier Agent (problem type, urgency)
↓
Supervisor Agent
↳ Resolver Agent → try to solve via tools
↳ If confident: DONE
↳ If not: back to Supervisor
↳ Escalation Agent → human summary
↳ DONE
所有内容都存储在LangGraph状态中，并作为最终输出返回。
存储器设计
短期（每张票）
- 由LangGraph MemorySaver支持
- 存储中间代理输出
长期（交叉票）
- SQLite支持
- 通过MCP访问
- 存储历史问题内容、元数据、时间戳
- 解析器用于个性化答案
存储库结构
uda-hub/
├── README.md
├── requirements.txt
├── .gitignore
├── .env # Local environment variables
│
├── 01_external_db_setup.ipynb # Notebook: loads JSONL → external DB
├── 02_core_db_setup.ipynb # Notebook: builds core DB schema
├── 03_agentic_app.py # Entry script to run full UDA-Hub workflow
│
├── agentic/ # LangGraph + Agent layer
│ ├── __init__.py
│ ├── workflow.py # Full StateGraph workflow (intake → classifier → supervisor → resolver/escalation)
│ │
│ ├── agents/ # All agent definitions
│ │ ├── __init__.py
│ │ ├── intake_agent.py
│ │ ├── classifier_agent.py
│ │ ├── resolver_agent.py
│ │ ├── escalation_agent.py
│ │ ├── supervisor_agent.py
│ │
│ ├── tools/ # MCP client wrappers (async)
│ ├── __init__.py
│ ├── mcp_client.py # MCP connection + dynamic tool loader
│ ├── knowledge_client.py # KB search/get
│ ├── account_client.py # Account get_user + get_user_reservations
│ ├── memory_client.py # Memory write + search
│
├── mcp_services/ # All MCP Servers (FastMCP)
│ ├── kb/
│ │ ├── server.py # Knowledge Base MCP tool server
│ │
│ ├── account/
│ │ ├── server.py # Account MCP server
│ │
│ ├── memory/
│ ├── server.py # Memory MCP server
│
├── data/
│ ├── models/ # SQLAlchemy DB models
│ │ ├── udahub.py # Core DB models (Memory + Mapping)
│ │ ├── cultpass.py # External CultPass models
│ │
│ ├── external/ # External “source-of-truth”
│ │ ├── cultpass_users.jsonl
│ │ ├── cultpass_articles.jsonl
│ │ ├── cultpass_experiences.jsonl
│ │ ├── cultpass.db
│ │
│ ├── core/
│ ├── udahub.db # Main core DB
│ ├── memory.db # Memory DB
│
├── tests/ # Full pytest suite
│ ├── conftest.py
│ ├── test_kb_tool.py # Tests for KB MCP server
│ ├── test_account_tool.py # Tests for Account MCP server
│ ├── test_memory_tool.py # Tests for Memory MCP server
│ ├── test_routing.py # Tests for workflow routing logic
│ ├── test_end_to_end.py # Full end-to-end test of UDA-Hub orchestration
│
├── utils.py # Shared utility functions
│
├── dump_mermaid.py # utility to draw mermaid diagram of the graph
├── debug_kb_direct.py # utility to debug the kb response
├── logger.py # utility for logging
├── logs/ # Full pytest suite
│ ├── uda_hub.jsonl # Log file
安装说明
- 创建并激活环境
conda create -n uda-hub python=3.11 -y
conda activate uda-hub
- 安装依赖项
pip install -r requirements.txt
- 配置环境变量
touch .env
编辑.env以添加openai的密钥
OPENAI_API_KEY=your_openai_key_here
- 构建数据库
运行：
- 01_外部_db_setup.ipynb
- 02_core_db_setup.ipynb
这些创建：
- 数据/外部/文化.db
- data/core/udahub.db
运行应用程序
运行演示票：
python 03_agentic_app.py --mode demo
运行交互模式：
python 03_agentic_app.py --mode chat
运行测试
pytest -q
您应该看到测试输出为：
8 passed in XXs
要检查结构化日志，请执行以下操作：
# Run the demo and show only final workflow completion events
python 03_agentic_app.py --mode demo 2>&1 | grep '"workflow_completed"'
# Show all supervisor decisions
python 03_agentic_app.py --mode demo 2>&1 | grep '"supervisor_decision"'