Building a Production WhatsApp AI Agent: Architecture That Actually Works

构建生产级 WhatsApp AI 智能体：真正有效的架构方案

Everyone demos a WhatsApp chatbot. Few run one in production with real customers sending real messages 24/7. After 18 months of running SARA — an open-source WhatsApp AI agent serving businesses across 20 industries — here’s what we learned about architecture that survives contact with reality. 每个人都能演示一个 WhatsApp 聊天机器人，但很少有人能在生产环境中 24/7 处理真实客户发送的真实消息。在运行 SARA（一个为 20 个行业的企业提供服务的开源 WhatsApp AI 智能体）18 个月后，我们总结了这套能够经受现实考验的架构经验。

Why WhatsApp? The numbers are simple: 2B+ monthly active users, 60% of SMB customers prefer messaging over calling, 98% open rate (vs 20% for email). But WhatsApp is NOT just another chat channel. It has unique constraints that break naive implementations. 为什么选择 WhatsApp？数据很简单：拥有超过 20 亿月活跃用户，60% 的中小企业客户更倾向于通过消息而非电话沟通，消息打开率高达 98%（相比之下电子邮件仅为 20%）。但 WhatsApp 不仅仅是另一个聊天渠道，它有着独特的限制，足以让简单的实现方案失效。

Architecture Overview

架构概览

WhatsApp (WAHA) → Bridge (:3008) → SARA API (:3006) → AI Provider Chain → Tool Dispatcher ↓ Groq → Cerebras → SambaNova → Mistral WhatsApp (WAHA) → 桥接服务 (:3008) → SARA API (:3006) → AI 提供商链 → 工具调度器 ↓ Groq → Cerebras → SambaNova → Mistral

The Provider Fallback Chain

提供商故障转移链

Single-provider AI is a production risk. We use a 4-provider chain: Primary: Groq (fastest, free tier) ↓ fail Fallback 1: Cerebras ↓ fail Fallback 2: SambaNova ↓ fail Fallback 3: Mistral (paid, always works). Each provider gets 2 retries with exponential backoff before failover. Result: 99.7% uptime over 6 months with $0 inference cost (free tiers). 单一 AI 提供商在生产环境中存在风险。我们使用了一个 4 级提供商链：主用：Groq（最快，有免费额度）↓ 失败 → 备用 1：Cerebras ↓ 失败 → 备用 2：SambaNova ↓ 失败 → 备用 3：Mistral（付费，稳定性高）。每个提供商在故障转移前都有 2 次指数退避重试机会。结果：6 个月内实现了 99.7% 的在线率，且推理成本为 0 美元（利用了免费额度）。

Tool Calling: Not Just Chat

工具调用：不仅仅是聊天

SARA doesn’t just answer questions. She executes actions: create_reservation (books a table with date normalization), check_inventory (queries stock levels), generate_invoice (creates a PDF from database records), schedule_appointment (manages calendar slots). The dispatcher maps 30+ tools to handlers with an autonomy gate: User message → Intent classification → Risk assessment → Tool execution. Low risk: execute immediately; Medium: execute + notify owner; High: ask for confirmation first. You do NOT want your AI agent booking a catering order for 500 people without human approval. SARA 不仅仅是回答问题，她还能执行操作：create_reservation（预订餐位并进行日期标准化）、check_inventory（查询库存）、generate_invoice（从数据库记录生成 PDF）、schedule_appointment（管理日程）。调度器将 30 多种工具映射到处理程序，并设有自主权门控：用户消息 → 意图分类 → 风险评估 → 工具执行。低风险：立即执行；中风险：执行并通知所有者；高风险：先请求确认。你肯定不希望 AI 智能体在没有人工批准的情况下预订 500 人的餐饮订单。

PII Handling

个人身份信息 (PII) 处理

Messages contain names, phone numbers, addresses. Our pipeline: Anonymize before sending to LLM (replace “Mario Rossi” → “[PERSON_1]”), process with anonymized data, de-anonymize tool calls only (the reservation needs the real name), never log PII in plain text. 消息中包含姓名、电话号码和地址。我们的处理流程是：在发送给大模型前进行匿名化处理（将“Mario Rossi”替换为“[PERSON_1]”），使用匿名数据进行处理，仅在工具调用时进行去匿名化（预订需要真实姓名），且绝不以明文形式记录 PII。

Session Management

会话管理

WhatsApp doesn’t have “sessions” — it’s just a stream of messages. We manage context with: Sliding window (last 20 messages as context), Business context injection (CRM data, menu, pricing injected per-tenant), Cross-conversation memory (the agent remembers “last time you ordered the risotto”). WhatsApp 没有“会话”概念，它只是一连串的消息流。我们通过以下方式管理上下文：滑动窗口（将最后 20 条消息作为上下文）、业务上下文注入（按租户注入 CRM 数据、菜单、定价）、跨对话记忆（智能体能记住“你上次点了意大利烩饭”）。

Self-Hosting vs Cloud

自托管与云服务

SARA runs on a single VPS (4 vCPU, 8GB RAM): WAHA (~500MB RAM), Bridge service (~50MB), SARA API (~200MB), PostgreSQL + pgvector (~2GB). Total ~3GB. No GPU needed — inference is offloaded to cloud providers. SARA 运行在单台 VPS 上（4 vCPU, 8GB 内存）：WAHA (~500MB 内存)、桥接服务 (~50MB)、SARA API (~200MB)、PostgreSQL + pgvector (~2GB)。总计约 3GB。无需 GPU，推理任务被卸载到云端提供商。

The Hardest Bugs

最棘手的 Bug

WhatsApp session contention (running two instances with the same number = instant logout). Date parsing across languages (“dopodomani” + timezone handling + business hours). Message ordering (WhatsApp doesn’t guarantee delivery order; our bridge queues and re-orders by timestamp). WhatsApp 会话冲突（用同一个号码运行两个实例会导致立即登出）。跨语言日期解析（“dopodomani”意为后天 + 时区处理 + 营业时间感知）。消息顺序（WhatsApp 不保证投递顺序；我们的桥接服务会进行排队并按时间戳重新排序）。

Open Source

开源

SARA is AGPL-3.0 on GitHub: github.com/Alessandro114/sara. Self-host it, extend it, build your own vertical agent on top. Cloud-only features (multi-tenant, white-label, analytics) stay in the commercial version. The 20 industry-specific agent definitions are also open source: scala-agent-definitions (Apache-2.0). SARA 已在 GitHub 上以 AGPL-3.0 协议开源：github.com/Alessandro114/sara。你可以自托管、扩展它，或在其基础上构建自己的垂直领域智能体。仅云端功能（多租户、白标、分析）保留在商业版本中。20 个行业特定的智能体定义也已开源：scala-agent-definitions (Apache-2.0)。

What’s Next

未来展望

Proactive agents (don’t wait for messages, reach out when something needs attention). Cross-agent events (when DineOS agent sees a large booking, TravelOS agent checks nearby hotel availability). Voice (WhatsApp voice messages → STT → agent → TTS → voice reply). 主动式智能体（不再被动等待消息，在需要关注时主动联系）。跨智能体事件（当 DineOS 智能体看到大额预订时，TravelOS 智能体自动检查附近酒店空房）。语音交互（WhatsApp 语音消息 → 语音转文字 → 智能体 → 文字转语音 → 语音回复）。

Running AI in production is 10% model quality and 90% engineering. Follow for more war stories. 在生产环境中运行 AI，10% 取决于模型质量，90% 取决于工程实现。关注我以获取更多实战经验。