超越聊天框：基于Google ADK的WhatsApp人工智能代理架构
WhatsApp生产助手如何整合Google ADK专业代理、RAG技术、确定性工具、会话状态管理、人工交接流程以及基于路径的评估机制。
大多数人工智能演示都只是将文本框与模型相连：输入问题，就能得到流畅的答案，观众也就满意了。但真正被客户依赖的产品则有更繁多的要求——它需要记住对话内容、处理实时公司数据、执行相应操作、在出错时仍能正常运行，而在自动化无法解决问题时还要将客户转交给人工处理。
本文将详细介绍为斯里兰卡一家电动汽车充电平台在WhatsApp中运行的实用助手的架构。该助手服务于电动汽车驾驶员、可能负责安装充电设备的物业所有者，以及那些只想了解电动汽车充电知识的人。读完本文后，你将获得围绕该模型所需各组件的具体设计蓝图，以及一套可在自己开发的智能助手中重复使用的设计规则，无论其运行在何种渠道上。
为何渠道会决定产品形态
该团队选择WhatsApp，这样人们就无需再安装其他应用来提问。目标用户已经使用WhatsApp：他们知道如何发送消息、分享位置、保存联系人以及回复对话中的特定消息。在现有平台上与用户见面完全避免了入门培训的问题。助手无需教导人们如何使用人工智能产品，而是以他们已熟悉的工具形式出现。
这一选择也带来了网页聊天机器人从未面临过的限制：
- 回复必须简短，因为过长的答案在手机上会显得过于繁重。
- 消息应以自然的速度发送，而非一次性呈现一大段文字。
- 位置请求应使用WhatsApp内置的位置共享界面。
- 联系人信息应以真实的联系卡形式呈现，而非粘贴的文本。
目标是要实现一种类似 WhatsApp 原生对话的体验，而非将桌面端聊天机器人硬塞进消息应用中。无论在哪个渠道使用，都应牢记这一点：平台的界面规范属于功能要求的一部分，而非装饰性元素。
从 webhook 到回复的请求路径
后端采用 Python 编写，基于 Google 的 Agent Development Kit（ADK）和 FastAPI 构建。ADK 能为智能体生成现成的 API 服务器，内置支持运行智能体、管理会话以及以事件形式返回处理结果的功能。该API 服务器运行在 FastAPI 和 Uvicorn 上，因此可以轻松添加自定义的 WhatsApp webhook 以及针对特定业务的需求端点。
一个 ADK 智能体由四部分组成：
- 模型，例如 Gemini。
- 定义智能体角色与功能范围的指令。
通过完整展示单条消息的处理流程，该设计更加清晰：
- 用户发送WhatsApp消息，Meta将其传递至FastAPI webhook。
- 后端解析该消息并将其同步到Chatwoot，以便客服团队跟进对话。
- 后端查找该用户的会话记录，并将消息传递给ADK。
- ADK启动协调器，负责路由请求：技术问题转交给EV代理，收益相关问题转交给定价代理，站点搜索请求则转交给站点代理。
- 对应的代理要么查询Vertex AI知识库，要么调用相关工具，例如查询站点数据、估算收益、发送联系卡或获取用户位置信息。
请注意，这一流程中模型本身所承担的部分其实很少。解析、会话查询、路由分配、格式化处理、消息发送以及内容同步都属于常规的后端工作。
一名协调员，三名专家
该助手由一名协调员负责统筹，再分配给三名专业代理：
- 一名电动汽车基础设施代理，负责处理充电器类型、安装及相关法规事宜。
- 一名定价与业务代理，负责分析运营成本问题。
- 一名站点搜索代理，负责查找充电地点。
协调员的唯一职责就是理解用户意图，并将对话转交给相应的专家。关于充电器类型的问题会转交至基础设施部门，物业主询问潜在收益的问题则会被转交给定价部门，而要求查找加勒附近充电站的需求则会转交至站点搜索功能。这些转接过程对用户来说是不可见的，用户感受到的始终是与同一位助手的连续对话。
另一种方案是使用一个带有长系统提示语且集成了所有工具的大型智能体。这种做法适用于原型开发，但随着工具和对话流程的不断增加，分离职责带来了三重好处：每个提示语都保持简洁，便于判断哪个智能体可以调用哪个工具，而且每个流程都可以单独进行测试。另一种已记录的智能体协调模式是将协调者与各专业智能体分开，这也能降低修改成本，因为无需改动站点搜索功能即可调整定价流程。
有一个值得提及的成本。每一个路由决策都意味着另一次可能出错的模型调用，因此被错误路由的问题会以单个智能体绝不会出现的方式失败。这就是后文所述的评估策略会检查选择了哪个智能体和工具，而不仅仅是最终表述的原因之一。如需更深入地了解路由机制与专业智能体之间的关联，请参阅LangGraph中的专业智能体、关键词路由器与中断机制。
将答案基于受控的知识库
公司助理绝不能编造事实，而电动汽车充电涉及诸多容易出错的细节：充电器容量、充电时间、安装要求、相关法规、车型以及企业特定信息。这些内容很多会随时间变化，普通模型对当地市场的了解十分有限。
解决方案是检索增强生成技术。相关知识以语料库的形式存储在Vertex AI的RAG引擎中，智能体在回答技术问题之前可以查询该语料库以获取最相关的内容。系统设有两条独立的检索路径：一条用于处理通用电动汽车基础设施相关问题，另一条则用于处理车型及充电时间相关问题。通过这种方式划分语料库，能让搜索结果更加精准，因为关于某款汽车具体充电时间的问题不会与法规文件争夺最优先的展示位置。
分工协作是核心理念。该模型依然负责生成答案，但所需数据来自公司可控的来源，且无需重新训练即可更新。
将对话转化为行动
最大的突破在于超越了单纯回答问题的范畴。该助手拥有能够执行实际任务的工具，它可以：
- 查询市场平台后台，获取某城市附近的充电站数量。
- 发送WhatsApp原生定位请求。
- 发送公司的联系卡片。
- 以地图标记的形式分享办公地点。
- 为考虑安装充电设备的人估算潜在收益。
- 在用户需要时将对话标记并转交给人工处理。
为何收益计算使用的是纯Python
收益计算流程体现了该系统最重要的设计原则。助手首先通过对话收集用户关于房产及充电需求的详细信息，随后计算每月的能源消耗量、预期收入、电费支出、月利润及年利润。
这一计算过程是由确定性Python代码完成的，而非由语言模型自行运算。模型在处理算术问题时并不可靠，而向潜在客户展示的财务数据必须具备可重复性和可审计性。模型负责管理对话并提取所需信息，而代码则用于生成具体数值。最终结果会通过结构化的WhatsApp模板呈现，并将客户信息记录在Google Sheets中。
语言处理和决策制定可借助模型，而所有需要精确结果的环节则应使用普通软件。
这一规则的应用范围远不止定价：日期处理、单位转换、资格验证以及任何具有法律或财务意义的内容都应放在模型调用的代码中，而非模型的输出结果中。
会话状态即产品逻辑
良好的对话依赖于之前的上下文。助手会为每个WhatsApp号码维护独立的会话，该会话中存储有用户的姓名、电话号码、所选的菜单选项、最新消息、位置状态以及最后一条消息的ID。
存储最后一条消息的ID能让系统理解用户对特定菜单消息的回复，而WhatsApp用户经常会这样做。会话状态还能让多步骤流程顺畅进行。例如位置共享的操作流程如下：
- 询问用户是否愿意分享其位置。
如果没有这种状态，每条消息都会被视为新对话的开始。智能体中的内存并非可选附加功能；它决定了产品的运行方式，因此应与其他任何功能一样得到同等的设计重视。
小屏幕的格式处理
一个令人意外的发现是：即使技术上正确，仅仅因为格式问题，答案仍可能让人感觉不对。模型往往会产生长段落、Markdown 列表以及将多个想法挤在同一个块中。这在桌面端看起来尚可，但在聊天窗口中则效果很差。
专门的格式处理层负责解决这一问题。它：
- 将 Markdown 转换为 WhatsApp 自有的格式语法。
- 检测隐藏在连续正文中的列表。
各部分之间的短暂间隔能让读者有时间理解每个观点。这样做的目的并非模拟人类打字，而是控制节奏。通过 Meta API 发送的打字指示器可以表明回复正在准备中。
该助手还会对某些消息用表情符号作出回应，且是选择性进行的。像 Flash Lite 这样的轻量级模型会判断某条消息是否值得回应，如果值得，则通过 Meta API 发送相应表情。充满情感、令人兴奋、有趣或有意义的消息可能会收到回应，而“好的”、“谢谢”这类常规消息或单纯的指令通常不会。使用小型且廉价的模型来做出此类判断，既能降低延迟和成本，又能让主要处理模块专注于核心内容。这些细节单独来看可能微不足道，但综合起来决定了产品的自然度。
保留与人工客服的通道
自动化系统绝不应成为客户与公司之间的隔阂。每条 incoming 对话都会同步到 Chatwoot，助手的回复也会被记录下来，这样客服团队始终能够清楚了解对话内容。
当用户要求与真人沟通或表现出沮丧情绪时，助手会启动人工协助流程，将请求及用户的问题记录下来以便团队处理。由于整个对话过程已被同步，接手处理的人无需让用户重复说明。
自动化应消除重复性工作，而非切断与人工客服的沟通渠道。
对话之外的可靠性保障工作
该系统还会发送WhatsApp模板营销信息，这带来了一个潜在问题：促销消息绝不应打断用户正在进行的客服对话。在发送之前，系统会查看每位接收者上次与助手互动的时间。那些刚刚结束对话的用户消息会被暂存，写入SQLite数据库，等待后续通过重试接口发送。
除此之外，每个服务都需要一些不太引人注目的功能：
- 对收到的消息进行去重处理，因为webhook可能会多次传递同一事件。
- 系统健康状况监控。
- 处理访问令牌的刷新问题。
- 对HTTP接口实施CORS控制。
- 基于Docker的部署方式。
- 使用Sentry进行错误追踪。
在演示中，这些功能都无法给任何人留下深刻印象。但一旦演示转变为客户依赖的实际服务，它们就变得至关重要。
测试行为而非仅文本
与普通函数相比，智能体更难测试，因为相同的输入可能会产生略有不同的输出。更糟糕的是，从最终文本无法看出故障模式——回复可能写得很好，但实际上调用了错误的工具；或者虽然调用了正确的工具，但结果的表达方式却很糟糕。
因此，评估套件会使用模拟对话来测试基础设施相关问题、定价流程以及不同专家之间的交流。这些检查不仅关注最终回复的措辞，还会查看工具调用顺序，即按何种顺序调用了哪些智能体和工具。
提示词的修改也采用相同方式处理。团队没有手动编辑系统提示词，而是尝试使用优化循环，在固定的对话集中对候选指令进行评分，其中包括基于GEPA的提示词优化。这些候选指令会与训练数据中的问题进行对比，同时还有一个由Gemini驱动的评分系统来评估每个响应的准确性和个性特征。这样一来，提示词优化工作就更接近工程化流程：不必因为某个修改感觉更好就直接采用，而是可以通过可重复的对话集来比较不同方案的表现。对于任何以模型作为评分器的设置都有一个需要注意的问题：评分器本身存在偏见，因此在依赖其结果做出重要决策之前，最好先用人类判断来校验其评分。
关键要点
- 模型只是其中一个组成部分；大部分工程工作集中在路由、检索、状态管理、工具设计、格式处理、故障处理以及问题升级等方面。
- 当提示词和工具列表变得难以管理时，将不断扩展的智能体拆分为协调器与各功能专责模块，并对路由机制本身进行测试。
- 将事实性答案基于你可控制的知识库生成，而将计算等精确操作放在确定性代码中处理。
- 将会话状态及特定渠道的格式要求视为核心产品逻辑。
- 始终保留一条清晰、便捷的人机交互路径。
- 在固定的对话场景下评估工具的使用效果，从而通过实际数据衡量而非猜测提示词调整的效果。
在 API 调用中加入提示词即可生成演示版本。一个可靠的智能体是一个完整的系统，其中语言模型、数据、工具、产品设计以及传统的后端工程各司其职，发挥各自的最大优势。