TravelMind Agent Lab

一个可以直接运行、适合逐文件学习的多 Agent 旅行规划项目。默认 demo 模式不需要 API Key；主 Agent 会并行调用航班、酒店、活动三个专家，读取本地旅行知识，最后生成 结构化方案并保存到 SQLite。

你会在这里学到什么

• LangGraph 状态图与主 Agent 编排
• asyncio.gather 并行专家调用
• Pydantic 请求/响应模型
• FastAPI、后台任务与 SSE 事件流
• 本地 RAG、SQLite 会话持久化
• DeepSeek V4 Pro 的 OpenAI-compatible API
• 可选 Redis 任务状态、PostgreSQL 报告存储、FastMCP 工具

3 分钟启动

uv sync --extra dev
Copy-Item .env.example .env
uv run travelmind-api

浏览器打开 http://127.0.0.1:8000/docs，调用 POST /api/v1/plan：

{
  "query": "帮我规划一次四天的巴黎旅行",
  "origin": "Shanghai",
  "destination": "Paris",
  "days": 4,
  "budget": 12000,
  "currency": "CNY",
  "thread_id": "lesson-001"
}

默认结果是可重复的模拟数据，目的是先学清 Agent 数据流。测试命令：

uv run pytest
uv run ruff check .

切换 DeepSeek

在 .env 中填写：

APP_MODE=deepseek
DEEPSEEK_API_KEY=你的密钥
DEEPSEEK_MODEL=deepseek-v4-pro

DeepSeek 只负责润色基于工具结果的摘要，航班、酒店和活动仍使用演示 Provider，避免 模型虚构价格。以后可在 providers.py 中替换为真实 Amadeus/地图 API。

可选基础设施

docker compose -f docker/compose.yml up -d
uv sync --extra redis --extra postgres --extra mcp

• REDIS_URL=redis://localhost:6379/0：任务状态放入 Redis。
• DATABASE_URL=postgresql://travelmind:travelmind@localhost:5432/travelmind： 报告放入 PostgreSQL。
• uv run travelmind-mcp：把 plan_trip 暴露为 MCP 工具。

没有 Redis/PostgreSQL 时会自动使用内存任务表和 SQLite，因此核心项目始终能启动。

学习顺序

1. models.py：理解输入、专家结果和最终报告。
2. agents.py：看三个专家如何并行工作。
3. graph.py：看主 Agent 如何连接检索、专家和汇总节点。
4. service.py：看图执行和持久化。
5. api.py：看 HTTP、后台任务和 SSE。
6. storage.py、jobs.py：再学习数据库与 Redis 适配器。

项目边界

这是可运行的学习版，不是出票系统。演示价格不应被用于真实预订。真实供应商 API、 认证、限流、退款和支付属于后续工程阶段。

来源与许可证说明见 UPSTREAM.md。