# chat_supervisor_agent

**Repository Path**: tyzhsj/chat_supervisor_agent

## Basic Information

- **Project Name**: chat_supervisor_agent
- **Description**: chat_supervisor_agent 基于 LangGraph + FastMCP + FastAPI 构建的多智能体调度工作流系统，内置分类调度主管(Supervisor)，分流旅游规划、笑话生成、对联检索、通用兜底四大子智能体，搭配前端网页实现流式对话可视化调试。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-04
- **Last Updated**: 2026-07-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# chat_supervisor_agent
基于 LangGraph + FastMCP + FastAPI 构建的多智能体调度工作流系统，内置分类调度主管(Supervisor)，分流旅游规划、笑话生成、对联检索、通用兜底四大子智能体，搭配前端网页实现流式对话可视化调试。

## 项目介绍
1. **核心架构**
    - Supervisor 调度节点：大模型自动识别用户意图，分发任务至对应子Agent
    - Travel旅游智能体：对接 FastMCP STDIO/HTTP MCP服务，调用工具生成行程方案
    - Joke笑话智能体：直接调用LLM生成趣味短笑话
    - Couplet对联智能体：本地检索模块匹配对联并生成回复
    - Other兜底智能体：无法识别意图时统一返回提示文案
2. **通信与流式能力**
    - FastAPI + SSE 长连接实时推送 LangGraph 全量运行日志
    - 支持 `values / updates / custom` 三类流数据，前端可视化节点执行过程
    - 自动序列化 LangChain Message 对象，解决 JSON 序列化报错
3. **前端页面**
    原生 HTML + TailwindCSS + JS，分双面板：对话结果展示、Graph节点实时执行日志

## 技术栈
### 后端
- Python 3.10+
- LangGraph 0.1+：多智能体状态图编排
- LangChain / langchain-mcp-adapters：MCP工具适配、Agent构建
- FastMCP：MCP标准客户端通信
- FastAPI + uvicorn：Web服务接口
- sse-starlette：SSE流式推送
- uuid-utils：会话ID生成
### 前端
- 原生 HTML / JavaScript
- Tailwind CSS（CDN引入，无需本地构建）
### 外部依赖
- DeepSeek LLM（可替换任意OpenAI兼容模型）
- MCP Travel服务（独立行程工具服务）

## 项目目录结构
chat_supervisor_agent/
├── main.py                 # FastAPI 入口、SSE流式接口、路由注册
├── pyproject.toml          # 项目依赖配置
├── .gitignore
├── static/                 # 前端静态资源
│   ├── index.html          # 对话主页面
│   └── js/
│       └── chat.js        # SSE 连接、渲染逻辑
├── src/
│   ├── __init__.py
│   ├── state_def.py        # 状态State、Context、类型定义
│   ├── llm_config.py       # LLM 模型统一封装 llm / model
│   ├── constants.py        # 常量 nodes、路由文字、提示词
│   ├── mcp_client/         # MCP 工具封装模块
│   │   ├── __init__.py
│   │   ├── fastmcp_stdio.py # FastMCP stdio 获取工具
│   │   └── mcp_agent_runner.py # MCP Agent 异步执行函数
│   ├── agents/             # 所有智能体节点逻辑
│   │   ├── __init__.py
│   │   ├── supervisor.py   # 调度主管节点
│   │   ├── travel_agent.py # 旅游规划节点
│   │   ├── joke_agent.py   # 笑话节点
│   │   ├── couplet_agent.py# 对联节点
│   │   └── other_agent.py  # 兜底节点
│   ├── graph_builder.py    # LangGraph 图构建、编译逻辑
│   └── utils/
│       ├── __init__.py
│       ├── logger.py       # 统一日志配置
│       └── uuid_helper.py  # thread_id 生成工具
├── mcp_servers/            # MCP 服务脚本存放目录
│   └── travel_mcp_server.py
└── tests/                  # 单元测试（可选）
    └── test_graph.py

## 核心功能特性
### 1.自动意图分流
Supervisor 节点通过 LLM 自动识别用户需求，无需人工标签，自动路由至对应 Agent
### 2.MCP 工具调用
旅游智能体支持 FastMCP STDIO/HTTP 双模式连接 MCP 服务，自动加载工具执行函数调用
### 3.全链路流式日志
SSE 实时推送图运行全量状态，可直观调试多智能体流转逻辑
### 4.消息自动序列化
内置 LangChain Message 专用序列化逻辑，支持 HumanMessage/AIMessage/ToolMessage 完整 JSON 输出，无序列化报错
### 5.可控递归限制
Graph 内置剩余步数判断，超过阈值自动终止工作流，防止无限循环
### 6.独立模块化设计
新增业务 Agent 仅需新增 agents 文件、注册图节点，低耦合易扩展

## 扩展开发指南
**1.新增业务智能体**  
- 在src/agents/新建节点文件，编写节点逻辑
- 在src/graph_builder.py中注册节点、补充路由判断
- 更新src/constants.py节点名称常量

**2.新增知识库检索能力**  
在src/retrieval/新建检索模块，对应 Agent 直接导入调用

**3.持久化会话记忆**  
将 InMemorySaver 替换为 RedisSaver，实现多服务会话持久化

**4.用户登录鉴权**  
FastAPI 增加 Token 校验接口，扩展 Context 上下文携带用户信息

**5.历史对话存储**  
新增 SQLite/MySQL 存储接口，持久化每轮对话输入输出

## 许可证
MIT