Cymbal Air：Google Cloud 原生的客服 Agent 实战范本

场景切入：你的航班被取消了，Agent 帮你找解决方案

设想这样一个场景：你搭乘 Cymbal Air 航班从旧金山飞往纽约，却收到了航班取消通知。凌晨 2 点，你打开航空公司客服页面，不是等待排队，而是在对话框输入："我的航班被取消了，能帮我查一下明天上午去 JFK 的备选航班吗？" 一个智能 Agent 立即理解了你的诉求，自动查询了你的订票信息、核验了航班状态，并在几秒内给出了 3 个备选方案。

这正是 Google Cloud 官方出品的 Cymbal Air 客服 Agent 演示项目所呈现的能力——不是科幻电影，而是用 LangGraph + RAG + MCP Toolbox 构建的生产级参考实现。

背景：从 LangChain 到 LangGraph，Google 的 Agent 架构演进

这个项目由 Google Cloud Platform 团队维护，最初发布于 2023 年 8 月，经历了从 LangChain 原生使用到全面迁移 LangGraph 的演进过程。LangGraph 是 LangChain 官方推出的有状态、有向图编排框架，专门为复杂 Agent 场景设计——它将 Agent 的工作流建模为节点（Node）和边（Edge）的组合，每个节点可以是 LLM 调用、工具执行或条件判断，每个边则定义状态如何流转。

项目以一家虚构航空公司 Cymbal Air 作为主角，模拟其旧金山国际机场（SFO）枢纽的完整客服场景。用户可以通过自然语言查询机场设施、搜索航班信息、了解退改签政策，甚至直接让 Agent 代为预订机票。这种"垂直领域 + 真实场景"的设定，使它成为学习如何将 LLM Agent 接入企业数据库的最佳实践。

技术架构：RAG + Agent + MCP 的三层设计

第一层：RAG 检索增强

CymBAL Air 的数据层由 Google Cloud 数据库（AlloyDB for PostgreSQL）支撑，Agent 通过 MCP Toolbox（Model Context Protocol 工具箱）访问数据库中的结构化数据。项目在 data/ 目录下提供了完整的演示数据集：airport_dataset.csv（机场信息）、flights_dataset.csv（航班数据）、amenity_dataset.csv（机场设施/商店/餐饮）和 cymbalair_policy.csv（退改签政策）。数据通过 run_database_init.py 初始化脚本导入数据库，Agent 在回答用户问题前，会先用这些真实数据做检索增强，显著降低幻觉率。

与传统的微调方案相比，RAG 的优势在于：数据不出上下文，信息可实时更新，且不影响基础模型本身。对于航空、银行、医疗这类信息敏感且频繁变动的行业，RAG 是比微调更灵活的选择。

第二层：LangGraph 状态机编排

核心逻辑在 agent/react_graph.py 中实现。LangGraph 的状态图包含以下关键节点：

• LLM 决策节点：接收用户 Query，由 Vertex AI 的 gemini-2.5-flash 模型判断是否需要调用工具、调用哪些工具，以及如何组织回复。
• 工具调用节点：通过 MCP Toolbox 动态加载的工具（如 search_airports、list_flights、search_flights_by_number）执行 SQL 查询。工具定义在 tools.yaml 配置文件中，支持 PostgreSQL、AlloyDB、Spanner 等多种 GCP 数据库。
• 条件路由边：根据工具返回结果决定下一步——是继续追问用户补充信息（如出发日期、目的地代码），还是直接返回查询结果。
• 确认节点：对于需要用户确认的操作（如机票预订），Agent 会先展示方案，等待用户确认后再执行写入操作。

值得注意的是，项目使用了 MemorySaver checkpointer 实现对话状态的持久化。agent/agent.py 中的 Agent 类为每个用户 Session 维护独立的对话历史，支持跨请求的上下文连续性。

第三层：MCP Toolbox 统一工具层

MCP（Model Context Protocol）是 Anthropic 提出的标准化协议，用于 LLM 与外部工具/数据源的交互。Google 的 MCP Toolbox 实现为 LangChain 提供了统一适配器：toolbox-langchain 包（v0.5.3）负责将 YAML 配置文件中定义的数据库连接和 SQL 模板，转换为 LangChain 可调用的 ToolboxTool 实例。

这种设计带来了极佳的可扩展性：要添加新工具，只需在 tools.yaml 中新增一个条目，定义 SQL 模板和参数，不需要改代码。tools.yaml 中已预设了 10+ 个工具，覆盖机场搜索、航班查询、设施查询、票务操作等全链路客服场景。

Web UI：FastAPI + Session 的对话界面

项目的 Web 层由 FastAPI 驱动（app.py + run_app.py），使用 Jinja2 模板引擎渲染对话页面，静态资源通过 FastAPI StaticFiles 托管。页面支持 Google OAuth 登录认证，通过 google-auth 库验证用户身份，确保只有已登录用户能发起服务请求。

对话界面核心流程：index 路由处理 GET/POST 请求，从 Session 中提取 uuid（用户唯一标识），调用 Agent.user_session_invoke() 方法，LangGraph 执行完整推理后返回 AI 回复。Agent 返回的响应结构包含 output（回复文本）、trace（推理链路追踪）和可选的 confirmation（等待用户确认的操作描述）。

部署挑战：为什么它不适合"一键部署"

尽管项目提供了 Dockerfile（python:3.11-slim 基础镜像），但真正阻碍快速部署的是云端依赖链：

1. Vertex AI API：必须启用 Google Cloud Vertex AI 服务，且模型调用按 token 计费。
2. 数据库：需要实际创建 AlloyDB / Cloud SQL / Spanner 实例并导入演示数据，run_database_init.py 脚本需要连接真实数据库才能运行。
3. 认证：需要生成 GCP 服务账号 JSON 密钥文件，配置环境变量 GOOGLE_APPLICATION_CREDENTIALS。

因此项目的定位是**参考实现（Reference Implementation）**而非开箱即用的产品——Google 在 README 开头也明确声明："This project is for demonstration only and is not an officially supported Google product."

行业意义：从 LangChain 到 Agent 架构的最佳实践教科书

Cymbal Air 项目的价值不仅在于它本身是一个可用的客服 Agent，更在于它展示了构建生产级 Agent 应用所需的完整技术栈和设计模式：

• 有状态 vs 无状态：用 LangGraph 的 StateGraph + checkpointer 替代 LangChain 的简单 Chain，解决了 Agent 多轮对话中的状态管理难题。
• 工具定义外部化：tools.yaml 配置驱动的工具注册机制，使得工具扩展不需要修改业务代码，降低了维护成本。
• RAG 的正确姿势：不是简单地向 LLM 塞文档，而是通过 MCP Toolbox 将数据库查询封装为标准化工具，让 Agent 按需精确检索。
• 认证与安全的平衡：通过 Google OAuth 实现用户认证，通过 MCP 协议隔离数据库访问，既保证了用户体验，又控制了数据泄露风险。

对于想构建类似应用的开发者，Cymbal Air 是一份不可多得的"抄作业"范本——从目录结构到代码组织，从 Dockerfile 到工具配置，每个细节都遵循 Google 工程师的工程实践标准。