使用说明

搭载Claude SDK的WhatsApp AI代理机器人

一个由Claude AI驱动的智能WhatsApp机器人，能够为WhatsApp用户提供自动化且上下文感知的回复。该机器人使用Python、Claude Agent SDK和FastAPI构建，并部署在Render平台上。

📋 目录

这个项目的作用
架构概述
技术栈
项目结构
它是如何运作的
安装说明
部署到渲染（服务/环境）
环境变量
测试
资源

🎯 该项目的功能

这个项目创建了一个 基于人工智能的WhatsApp机器人 使用Claude AI自动回复用户消息：

用例：智能WhatsApp助手

用户向您的WhatsApp商业号码发送消息 → 您的服务器使用Claude进行处理 → AI自动发送带有上下文感知的回复

示例对话：

User: "What's the weather like?"
Bot (Claude): "I'd be happy to help! However, I'll need to know your location to provide weather information..."

User: "Can you help me with Python?"
Bot (Claude): "Absolutely! I can help with Python programming. What specific aspect would you like assistance with?"

主要特点：

✅ 翻译为中文是：✓（对号，表示正确或确认） 多用户支持 - 每个电话号码对应一个代理实例
✅ 情境感知的 - 30分钟的对话会话，包含20条消息历史记录
✅ 工具集成 - 克劳德可以使用WhatsApp MCP工具发送消息
✅ 异步处理 - 非阻塞的webhook响应
✅ 已准备好投入生产 - 使用Docker在Render上部署

🏗️ 架构概述

┌─────────────────────────────────────────────────────────────────┐
│                         WhatsApp User                           │
│                              │                                  │
│                              │ Sends message                    │
│                              ▼                                  │
│                    WhatsApp Business API                        │
│                              │                                  │
│                              │ POST webhook                     │
│                              ▼                                  │
│         ┌────────────────────────────────────────────┐         │
│         │         Render (Docker Container)          │         │
│         │  ─────────────────────────────────────────  │         │
│         │                                             │         │
│         │  ┌──────────────────────────────────────┐  │         │
│         │  │   FastAPI Service (main.py)          │  │         │
│         │  │   • Webhook verification (GET)       │  │         │
│         │  │   • Message processing (POST)        │  │         │
│         │  │   • Health check endpoint            │  │         │
│         │  └──────────────────────────────────────┘  │         │
│         │                    │                        │         │
│         │                    ▼                        │         │
│         │  ┌──────────────────────────────────────┐  │         │
│         │  │   Agent Manager                      │  │         │
│         │  │   • One agent per phone number       │  │         │
│         │  │   • Agent spawning & routing         │  │         │
│         │  │   • Session management               │  │         │
│         │  └──────────────────────────────────────┘  │         │
│         │           │              │                  │         │
│         │           ▼              ▼                  │         │
│         │  ┌──────────────┐  ┌──────────────┐       │         │
│         │  │   Agent 1    │  │   Agent 2    │  ...  │         │
│         │  │              │  │              │       │         │
│         │  │ Claude SDK   │  │ Claude SDK   │       │         │
│         │  │ with MCP     │  │ with MCP     │       │         │
│         │  │ tools        │  │ tools        │       │         │
│         │  └──────────────┘  └──────────────┘       │         │
│         │           │              │                  │         │
│         │           └──────┬───────┘                  │         │
│         │                  ▼                          │         │
│         │  ┌──────────────────────────────────────┐  │         │
│         │  │   WhatsApp MCP Tool                  │  │         │
│         │  │   • send_whatsapp(to, text)          │  │         │
│         │  │   • Uses WhatsApp Business API       │  │         │
│         │  └──────────────────────────────────────┘  │         │
│         │                                             │         │
│         └─────────────────────────────────────────────┘         │
│                              │                                  │
│                              │ Send response                    │
│                              ▼                                  │
│                    WhatsApp Business API                        │
│                              │                                  │
│                              ▼                                  │
│                         WhatsApp User                           │
│                      (Receives AI response)                     │
└─────────────────────────────────────────────────────────────────┘

建筑亮点：

单帧渲染服务 - 一个Docker容器运行所有内容
代理管理器模式 - 每个电话号码生成一个代理
克劳德代理SDK - 使用官方Python SDK并附带工具支持
MCP 工具 - 集成WhatsApp发送功能作为工具
会话管理 - 30分钟TTL（生存时间），每用户20条消息历史记录

🛠️ 技术栈

后端（Python）

框架： FastAPI（支持异步的REST API）
AI SDK（人工智能软件开发工具包） claude-agent-sdk - 适用于Claude代理的官方Python SDK
MCP:（此处为缩写，具体含义需根据上下文确定，但直接翻译即为“MCP”） mcp>=1.18.0 - 工具集成的模型上下文协议
WhatsApp WhatsApp商业云API（图API v18.0）
服务器： Uvicorn（ASGI服务器）
python 3.11+

基础设施

部署： 渲染（Docker 容器）
集装箱化： 带有 Node.js 20 和 Python 3.11 的 Docker
运行时： Claude CLI 命令行工具（通过容器中的 npm 安装）

外部API

Anthropic Claude API - 人工智能代理能力
WhatsApp商业云API - 发送/接收消息

📁 项目结构

whatsapp_mcp/
├── src/
│   └── python/                        # 🐍 Python backend
│       ├── main.py                    # 🚀 FastAPI entry point
│       │
│       ├── agents/                    # Agent system
│       │   ├── __init__.py
│       │   ├── manager.py             # Agent manager (one per phone)
│       │   ├── agent.py               # Individual agent instance
│       │   └── session.py             # Session management (30min TTL)
│       │
│       ├── sdk/                       # Claude SDK wrapper
│       │   ├── __init__.py
│       │   └── claude_sdk.py          # SDK client with MCP tools
│       │
│       ├── whatsapp/                  # WhatsApp integration
│       │   ├── __init__.py
│       │   ├── client.py              # WhatsApp API client
│       │   └── parser.py              # Webhook payload parser
│       │
│       └── utils/                     # Utilities
│           ├── __init__.py
│           ├── config.py              # Environment config
│           └── logger.py              # Logging
│
├── test_claude_sdk.py                 # Local SDK testing script
├── test_agent.py                      # Agent integration tests
│
├── requirements.txt                   # Python dependencies
├── Dockerfile.render                  # 🐳 Docker for Render deployment
├── render.yaml                        # Render deployment config
├── .dockerignore                      # Docker build exclusions
│
├── .env                               # Environment variables (gitignored)
├── .gitignore
│
├── README.md                          # This file
│
└── docs/                              # Documentation
    ├── ARCHITECTURE.md                # Architecture deep dive
    ├── IMPLEMENTATION_COMPLETE.md     # Implementation summary
    ├── CLAUDE_SDK_TEST.md             # SDK test results
    └── PRE_DEPLOYMENT_CHECKLIST.md    # Deployment verification

🔄 工作原理

消息流：

用户发送消息 发送到WhatsApp商业号码
WhatsApp API → 向 Render 发送 webhook POST 请求： /webhook
FastAPI Webhook 处理程序 (main.py)：
- 验证Webhook（使用GET方法进行验证）
- 解析消息有效载荷（POST）
- 提取电话号码和文本
- 立即返回200 OK（WhatsApp要求快速响应）
异步处理 （后台任务）：
- 代理管理器为电话号码获取/创建代理
- 代理使用Claude SDK处理消息
- 克劳德生成回复（可能使用工具）
- 通过WhatsApp API发送的响应
用户收到AI回复 在WhatsApp上

代理系统：

一个电话号码对应一个代理 - 独立对话
会话管理 - 30分钟临时令牌（TTL），自动清理
对话历史 - 每个用户的最后20条消息
MCP工具集成 - send_whatsapp 克劳德可用的工具

Claude 代理 SDK：

该项目使用了官方的Claude Agent SDK，该SDK：

需要 Claude 命令行界面（CLI） 待安装
运行具有完整工具支持的代理
自动管理对话上下文
支持通过MCP工具（进行操作/提供支持等，具体根据上下文确定） @tool 装饰器

🚀 安装指南

先决条件

python 3.11+
Docker （用于本地测试和部署）
WhatsApp商业账户 具有API访问权限
Anthropic API密钥 为克劳德（或：致克劳德）
渲染账户 （免费层级可用）

1. 克隆并安装依赖项

# Clone the repository
git clone https://github.com/billsusanto/whatsapp_mcp.git
cd whatsapp_mcp

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python dependencies
pip install -r requirements.txt

2. 设置环境变量

创建一个 .env 根目录下的文件：

# Anthropic API
ANTHROPIC_API_KEY=sk-ant-api03-...

# WhatsApp Business API
WHATSAPP_ACCESS_TOKEN=EAA...
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your_secure_random_token

# Optional: Custom system prompt
AGENT_SYSTEM_PROMPT="You are a helpful WhatsApp assistant..."

在哪里可以得到这些：

ANTHROPIC_API_KEY: Anthropic 控制台
WhatsApp 凭证： Meta 商业套件根据全局信息和原文内容，翻译如下：“WhatsApp” → “WhatsApp” → “API 设置”
WHATSAPP_WEBHOOK_VERIFY_TOKEN:（可翻译为）WhatsApp Webhook 验证令牌: 创建你自己的安全随机字符串（例如。， my_secret_token_12345）

3. 在本地进行测试

测试Claude SDK（不使用Docker）：

# Requires Claude Code CLI to be installed locally
python test_claude_sdk.py

# Interactive mode
python test_claude_sdk.py --interactive

使用 Docker 进行测试（推荐）：

# Build Docker image
docker build -f Dockerfile.render -t whatsapp-mcp .

# Run container
docker run -p 8000:8000 --env-file .env whatsapp-mcp

# Service available at http://localhost:8000

使用ngrok在本地测试webhook：

# Install ngrok: https://ngrok.com/
ngrok http 8000

# Copy HTTPS URL (e.g., https://abc123.ngrok-free.app)
# Configure in WhatsApp Business webhook settings

🚢 部署到Render（或：在Render上部署）

部署步骤：

1. 准备仓库

确保你的代码已推送到GitHub：

git add .
git commit -m "Ready for Render deployment"
git push origin main

2. 创建渲染服务

选项A：使用render.yaml（推荐）

首选 render.com（注：该网址本身在中文中无直接对应翻译，但可理解为“渲染网”或保持原样作为网址名称）并进行注册
点击“新建”→“蓝图”
连接你的GitHub仓库
选择分支： main （或 python-only-branch)
渲染将进行检测 render.yaml 并自动配置
点击“应用”

选项B：手动设置

点击“新建”→“Web 服务”
连接GitHub仓库
配置：
- 语言： Docker
- 分支： main（主要的；主要部分；主函数）
- Dockerfile 路径： ./Dockerfile.render
- 地区： 俄勒冈州（或离您最近的地方）
点击“创建Web服务”

3. 设置环境变量

在Render仪表板 → 您的服务 → 环境：

变量	值
`ANTHROPIC_API_KEY` 您的Claude API密钥
`WHATSAPP_ACCESS_TOKEN`	您的WhatsApp令牌
`WHATSAPP_PHONE_NUMBER_ID`	您的手机号码ID
`WHATSAPP_WEBHOOK_VERIFY_TOKEN`	您的验证令牌

点击“保存更改”- 渲染将重新部署。

4. 配置WhatsApp Webhook

一旦部署（服务URL： https://whatsapp-mcp-XXXX.onrender.com):

首选 Meta 商业套件 → WhatsApp → 设置
点击“Webhook”上的“编辑”
设置 回调URL： https://whatsapp-mcp-XXXX.onrender.com/webhook
设置 验证令牌与……相同值 WHATSAPP_WEBHOOK_VERIFY_TOKEN
点击“验证并保存”
订阅“消息”字段
通过向您的WhatsApp商业号码发送消息进行测试！

预计构建时间：

首次构建： 8-12分钟
- 安装 Node.js：约 2 分钟
- 安装Claude Code CLI：约3-5分钟
- 安装Python包：约2-3分钟
后续构建： 3-5分钟（使用缓存）

服务健康检查：

检查您的服务是否正在运行：

curl https://your-service.onrender.com/health

预期响应：

{
  "status": "healthy",
  "service": "whatsapp-mcp",
  "api_key_configured": true,
  "whatsapp_configured": true,
  "active_agents": 0
}

🔐 环境变量

所需变量

变量	描述	获取位置
`ANTHROPIC_API_KEY` “Claude API密钥” console.anthropic.com（可翻译为）：Anthropic 控制台网站
`WHATSAPP_ACCESS_TOKEN` WhatsApp API令牌 Meta商业套件
`WHATSAPP_PHONE_NUMBER_ID` 根据上面的信息，执行如下指令：
`WHATSAPP_WEBHOOK_VERIFY_TOKEN`	Webhook 验证令牌	创建您自己的随机字符串

可选变量

变量	描述	默认值
`AGENT_SYSTEM_PROMPT`	为Claude定制的系统提示	“你是一个乐于助人的WhatsApp助手……”
`PORT`	服务器端口（渲染设置此值）	8000

🧪 测试

本地测试（不使用WhatsApp）

独立测试Claude SDK：

# Automated tests (4 test scenarios)
python test_claude_sdk.py

# Interactive chat mode
python test_claude_sdk.py --interactive

测试结果记录于： CLAUDE_SDK_TEST.md

集成测试

测试完整的代理系统：

python test_agent.py

这个测试：

✅ 代理管理器初始化
✅ 按电话号码创建代理
✅ 使用Claude SDK进行消息处理
✅ MCP工具注册

使用WhatsApp进行测试

部署到Render
配置WhatsApp Webhook
向您的WhatsApp商业号码发送消息
检查渲染日志以进行处理
验证在WhatsApp中收到的回复

提示： 实时查看渲染日志：

Render Dashboard → Your Service → Logs

📚 主要特点

多用户支持

每个电话号码对应一个代理实例
孤立的对话环境
自动代理生成

会话管理

每条对话30分钟的存活时间（TTL）
20条消息历史记录限制
自动清理过期会话

工具集成

WhatsApp MCP工具： send_whatsapp(to, text)
克劳德可以自主发送消息
可扩展以支持更多工具

错误处理

向用户显示优雅的错误信息
全面记录
Webhook验证

准备就绪，可用于生产

Docker 容器化
健康检查端点
非阻塞异步处理
安全性（Docker中的非root用户）

📖 资源

文档

API参考

工具与库

🛠️ 开发

本地运行

# Without Docker
source venv/bin/activate
python src/python/main.py

# With Docker
docker build -f Dockerfile.render -t whatsapp-mcp .
docker run -p 8000:8000 --env-file .env whatsapp-mcp

项目命令

# Install dependencies
pip install -r requirements.txt

# Run tests
python test_claude_sdk.py
python test_agent.py

# Format code (if using black)
black src/python/

# Type checking (if using mypy)
mypy src/python/

🏛️ 建筑档案

对于详细的架构文档：

ARCHITECTURE.md 翻译为中文是：“架构.md”（其中，“.md”通常表示Markdown文件格式） - 系统整体设计及模块分解
`IMPLEMENTATION_COMPLETE.md` 翻译为中文是：“实施完成说明文件”或“实施完毕文档” - 功能实现概要
CLAUDE_SDK_TEST.md 翻译为中文是：“CLAUDE_SDK测试文档.md” 或者 “CLAUDE_SDK测试文件.md”（具体翻译可能根据上下文有所调整，但基本意思是“CLAUDE_SDK的测试相关文件”） - SDK测试结果及示例
PRE_DEPLOYMENT_CHECKLIST.md 翻译为中文是：“预部署检查清单.md” - 部署验证检查清单

🤝 贡献（或：参与贡献）

欢迎投稿！请：

为仓库创建分支（或：克隆仓库）
创建一个特性分支
做出你的更改
彻底测试
提交拉取请求

📄 许可证

MIT 许可证 - 详情请参见 LICENSE 文件

🙏 致谢

Anthropic（公司名，直译为“人类中心论者”，但在此上下文中通常保持原样不译，或译为“安萨提克”等音译名称，具体根据语境和品牌策略而定） - Claude AI 和 Agent SDK
Meta（公司名，通常不翻译，直接保留原名） - WhatsApp商业版API
渲染 - 托管平台

使用Claude Agent SDK、FastAPI、Python和Docker构建

部署： 渲染服务（https://whatsapp-mcp-p0ti.onrender.com）