AI支持副驾驶——LLM+MCP+多模态+观察性+多智能体编排
一个完整的人工智能支持票务处理系统，展示了：
- 模型上下文协议（MCP） 用于工具集成
- 多代理编排 （分类→ 研究→ 行动→ 主管）
- 多模态LLM 支持（文本+视觉）
- 可观测性 使用结构化跟踪
- 无框架 -手绘建筑，教育清晰
该项目专为研讨会和学习而设计，具有综合数据和清晰的实施模式。
建筑
┌─────────────────────────────────────────────────────────────────┐
│ Support Copilot Host │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Triage │──▶│ Research │──▶│ Action │──▶│Supervisor│ │
│ │ Agent │ │ Agent │ │ Agent │ │ Agent │ │
│ └──────────┘ └────┬─────┘ └──────────┘ └──────────┘ │
│ │ │
│ │ MCP Client │
│ ▼ │
│ ┌────────────────┐ │
│ │ MCP Tools API │ │
│ └────────┬───────┘ │
└───────────────────────┼─────────────────────────────────────────┘
│
┌───────────────────────┼─────────────────────────────────────────┐
│ │ Support MCP Server │
│ ▼ │
│ ┌────────────────────────────────────┐ │
│ │ support_docs.search │ │
│ │ incidents.search │ │
│ │ status.check │ │
│ └────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────┐ │
│ │ Synthetic Data │ │
│ │ - Runbooks │ │
│ │ - Incidents │ │
│ │ - Service Status │ │
│ └──────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘项目结构
.
├── README.md # This file
├── prd.md # Product Requirements Document
├── requirements.txt # Python dependencies
├── data/ # Synthetic data
│ ├── docs/runbooks/ # Support documentation
│ ├── incidents/ # Incident database
│ ├── status/ # Service status
│ └── tickets/ # Sample tickets
├── support_mcp_server/ # MCP Server implementation
│ ├── config.py
│ ├── tools_support_docs.py
│ ├── tools_incidents.py
│ ├── tools_status.py
│ └── server.py
└── support_copilot_host/ # Host application
├── config.py
├── models.py # Data models
├── llm_client.py # LLM wrapper
├── mcp_client.py # MCP client
├── agents.py # Four agents
├── orchestrator.py # Main flow
├── observability.py # Tracing
├── cli.py # CLI interface
└── examples.py # Workshop demos设置
1.先决条件
- Python 3.11+
- OpenAI API密钥（或兼容的LLM提供程序）
2.安装依赖项
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -r requirements.txt3.设置环境变量
export OPENAI_API_KEY="your-api-key-here"或者创建一个 .env 文件（您可以使用现有的 openai_key.env 作为参考）：
OPENAI_API_KEY=your-api-key-here
LLM_MODEL_NAME=gpt-4o-mini # Optional, defaults to gpt-4o-mini交互式Jupyter笔记本
非常适合研讨会和互动学习！
我们提供 3个Jupyter笔记本 进行实践探索：
1.快速入门演示(demo_quickstart.ipynb)
⏱️ 5分钟 -非常适合车间介绍
- 端到端处理2张样票
- 查看完整输出（客户回复+内部注释）
- 比较不同的票类型
- 最适合： 首次演示、测试设置
2.MCP工具深度学习(demo_mcp_tools.ipynb)
⏱️ 15分钟 -了解工具层
- 连接到MCP服务器
- 单独测试每个工具(
support_docs.search,incidents.search,status.check) - 探索搜索算法和评分
- 性能分析
- 现实世界中的机票分流场景
- 最适合： 教授MCP概念、工具定制
3.完整的流量勘探(demo_complete_flow.ipynb)
⏱️ 20-30分钟 -全系统深潜
- 完成票务处理流程
- 单独测试每种试剂（分类、研究、行动、主管）
- 详细的痕迹探索
- 处理所有4张样票
- 比较结果和行为
- 最适合： 了解多代理编排、调试
运行笔记本
先决条件：
# Install Jupyter
pip install jupyter
# Start MCP server (in separate terminal)
python -m support_mcp_server.server
# Start Jupyter
jupyter notebook然后打开任何演示笔记本，按顺序运行单元格！
工作坊提示： 从开始 demo_quickstart.ipynb 让观众惊叹，然后深入 demo_mcp_tools.ipynb 或 demo_complete_flow.ipynb 基于兴趣。
______________________________________________________________________
用法
快速入门：运行示例工单
这需要 两个端子:
终端1-启动MCP服务器：
python -m support_mcp_server.server2号航站楼-运行样本票：
python -m support_copilot_host.cli run-sample --id TICKET-001可用命令
列出可用的样品票
python -m support_copilot_host.cli list-samples运行特定的样本票
python -m support_copilot_host.cli run-sample --id TICKET-001
python -m support_copilot_host.cli run-sample --id TICKET-002
python -m support_copilot_host.cli run-sample --id TICKET-003
python -m support_copilot_host.cli run-sample --id TICKET-004运行自定义票
python -m support_copilot_host.cli run-ticket \
--description "User cannot export dashboard to CSV" \
--log "2025-11-01T10:00:00Z ERR_EXPORT_TIMEOUT service=export_service"运行研讨会演示
python -m support_copilot_host.examples样品票
该项目包括四张合成票：
- 票务-001：导出到CSV超时（已知问题+服务降级）
- 票务-002：SSO身份验证失败（调查事件）
- 票务-003：工作区权限问题（配置错误）
- 票务-004：API速率限制（已解决事件）
多代理流
每张票都要经过四个代理人：
- 分类试剂：分析工单，分类问题类型，决定使用哪些工具
- 研究代理：调用MCP工具（文档、事件、状态）以收集上下文
- ActionAgent：起草面向客户的回复和内部说明
- 主管代理人：审查输出的质量、安全性和幻觉
MCP工具
MCP服务器公开了三个工具：
support_docs.search：搜索内部运行手册incidents.search：查找相关事件status.check：检查服务运行状况
可观测性
每次执行票证都会生成一个跟踪：
- 唯一跟踪ID
- 每个事件的时间戳
- 代理步骤（LLM调用、工具调用、输出）
- 完整有效载荷数据（如果较大，则截断）
痕迹包括：
- 在终端中显示为漂亮的桌子
- 已保存到
traces/trace.jsonl作为JSONL - 用于调试和车间演示
定制
添加新的Runbook
在中创建markdown文件 data/docs/runbooks/:
# My New Runbook
Description of the issue...
Resolution steps:
1. Step one
2. Step two添加新事件
编辑 data/incidents/incidents.json:
{
"incident_id": "INC-1005",
"title": "New incident",
"status": "Investigating",
"summary": "...",
"tags": ["tag1", "tag2"]
}更改LLM模型
设置环境变量：
export LLM_MODEL_NAME="gpt-4o"车间使用
本项目设计为3小时的研讨会：
- 第一阶段：解释架构和MCP概念
- 第2阶段：演示MCP服务器和工具
- 第三期：显示单个代理基线（无工具）
- 阶段4：添加MCP工具集成
- 阶段5：重构为多代理模式
- 第6阶段：探索可观察性和痕迹
- 第7阶段：讨论扩展（RAG、更多代理等）
看 prd.md 了解详细的车间计划。
发展
运行测试
# Start MCP server first
python -m support_mcp_server.server
# In another terminal, run a test ticket
python -m support_copilot_host.cli run-sample --id TICKET-001查看痕迹
# Traces are saved to traces/trace.jsonl
cat traces/trace.jsonl | jq .局限性
这是一个 工作坊/教育项目，未准备好生产：
- 简单的关键字搜索（无嵌入/矢量搜索）
- 无数据库持久性
- 无身份验证
- 同步代理执行（无并行化）
- 有限的错误处理
将来的扩展
看 prd.md 第13节的想法：
- 文档/事件的矢量搜索
- 平行研究代理
- 反馈收集
- Web用户界面
- 高级评估指标
许可证
教育用途。看 prd.md 了解全部细节。
问题？
参见 prd.md 了解完整的实现细节和架构决策。