SmartBizTrip

SmartBizTrip 企业差旅智能体

本项目用于学习意图识别、任务规划、A2A 子助手协作、MCP 工具调用和对话记忆。预订功能为模拟演示，不会实际下单或出票。

1. 准备 Python 环境

安装 uv 后，在项目根目录（能看到本文件和 pyproject.toml）打开终端：

uv sync --locked
uv run python --version

看到 Python 3.12.x，并且依赖安装无报错后继续。保留 pyproject.toml、uv.lock 和 .python-version；不需要复制他人的 .venv。

2. 填写自己的配置

macOS / Linux：

cp .env.example .env
cp .env.mysql.example .env.mysql

Windows PowerShell：

Copy-Item .env.example .env
Copy-Item .env.mysql.example .env.mysql

编辑这两个文件，把 your_... 替换成自己的配置：

• DEEPSEEK_API_KEY：聊天模型密钥；DEEPSEEK_MODEL 填自己的账号可用的模型名。
• MYSQL_PASSWORD：两个文件中保持一致；数据库账号、库名也应一致。
• QWEATHER_API_KEY、QWEATHER_API_HOST：使用天气 API 时填写。
• DASHSCOPE_API_KEY：使用会务套餐向量检索时填写，不能用聊天模型密钥代替。
• WEATHER_SOURCE=database：使用 SQL 中的天气样例；api 使用天气接口。

示例配置不含真实密钥。填写后的 .env、.env.mysql 只保留在自己的电脑，不提交或发送给别人。

3. 先运行离线测试

uv run python -B -m tests.run_offline

看到 OK 后继续。此命令使用模拟对象并阻止网络连接，不消耗真实模型额度。需要数据库或 A2A 服务的集成测试会显示 skipped，这不代表它们已通过联网验证。

4. 启动数据服务

使用本项目的 Docker 配置时，先打开 Docker，再运行：

docker compose up -d mysql milvus
docker compose ps

看到所需服务为 healthy 后继续。此 Compose 只启动 MySQL 和 Milvus，不启动 Python 服务。

SQL 样例主要是 2026-05-01，北京到成都、成都当地资源。首次使用空数据卷会执行建表和样例导入；已有数据卷不会因为重启自动重新导入。sql/create_all_tables.sql 含删库重建语句，只用于准备教学样例库，不要对已有重要数据执行。

仅学习会务套餐检索时，填写向量模型配置并启动 Milvus 后，再手动运行：

uv run python sql/init_meeting_package_rag.py

看到插入成功和样例检索结果后再查询会务套餐。此脚本会删除并重建同名集合，不是增量导入。

5. 分别启动 Python 服务

每条命令使用一个终端，均在项目根目录执行。目录名称可以修改，不必叫 SmartBizTrip。

先启动 MCP 工具服务，看到各自监听端口后继续：

uv run python -m mcp_server.mcp_ticket_server
uv run python -m mcp_server.mcp_weather_server
uv run python -m mcp_server.mcp_trip_server

再启动 A2A 子助手：

uv run python -m a2a_server.ticket_server
uv run python -m a2a_server.weather_server
uv run python -m a2a_server.trip_server

最后启动网页 API：

uv run api_server.py

看到 API 监听 127.0.0.1:8080 后，浏览器打开 http://127.0.0.1:8080。

服务	端口
网页 API	8080
天气 / 票务 / 差旅 A2A	5005 / 5006 / 5007
票务 / 天气 / 差旅 MCP	8001 / 8002 / 8003
MySQL / Milvus	3306 / 19530

导入样例数据后，可询问：“查询 2026 年 5 月 1 日北京到成都的二等座高铁票”。若使用天气数据库模式，可询问同一天的成都天气。其他日期不保证有样例数据。

6. 阅读代码

从 api_server.py 的启动与路由开始，再看 ChatService.chat_stream()，然后追踪票务助手和 MCP 的 query_train。

网页 → API → ChatService → A2A 子助手 → MCP 工具 → 数据源
网页 ← SSE ← 主助手汇总 ← 子助手回复 ← 工具结果 ← 数据源

agent_learn/ 是独立概念示例；课件示例/项目实现/ 中的编号文件是随课程逐步组合的片段，部分依赖前面章节的导入、类或变量，不应逐个当完整程序运行。完整项目以根目录及 a2a_server/、mcp_server/ 为准；课件中的 Docker 全服务部署片段需要按章节整合，根目录 Compose 仅负责数据服务。

若要运行需要真实服务的测试，先准备对应服务和自己的配置，再设置 RUN_ONLINE_TESTS=1。这些测试可能调用模型；平时练习使用离线测试命令即可。