whaagent

<div align="center"> # WhaAgent **多租户WhatsApp AI平台** [](https://python.org) [](https://go.dev) [](https://fastapi.tiangolo.com) [](https://github.com/langchain-ai/langgraph) [](LICENSE) [](https://github.com/MusadiqUrRahman/whaagent/actions) </div> --- ## 概述 WhaAgent连接AI代理到WhatsApp。Go网关处理WhatsApp协议，Python API运行LangGraph驱动的代理。支持多个WhatsApp号码、多个AI代理，单次部署。 ``` 用户发送WhatsApp消息 | v Go网关（whatsmeow）--> Python API（FastAPI）--> AI代理（LangGraph） | | v v 通过WhatsApp发送响应 工具 / 大型语言模型 / 内存 ``` --- ## 架构 ```mermaid flowchart TB subgraph Clients["客户端层"] WA1["WhatsApp用户A"] WA2["WhatsApp用户B"] WA3["WhatsApp用户C"] end subgraph Gateway["Go网关"] SM["会话管理器<br/>多租户WhatsApp连接"] QR["二维码生成器<br/>SSE流式传输到浏览器"] EVT["事件处理器<br/>异步消息处理"] HTTP["HTTP客户端<br/>转发到Python API"] end subgraph API["Python API — FastAPI"] ROUTE["Webhook路由器<br/>/api/v1/channels/whatsapp/message"] AUTH["API密钥身份验证<br/>X-API-Key头部"] POOL["租户代理池<br/>LRU逐出，按租户隔离"] DB["SQLite检查点<br/>对话内存持久性"] end subgraph Graph["LangGraph状态图"] SUM["摘要节点<br/>令牌阈值，上下文压缩"] ROUTER["路由器节点<br/>LLM意图分类"] AGENT["代理节点<br/>工具编排，ReAct循环"] end subgraph Agents["代理注册表"] A1["assistant<br/>通用编排器"] A2["developer<br/>代码探索和分析"] A3["news / br-news / es-news<br/>新闻聚合"] A4["learning / recipe / youtube<br/>特定领域代理"] A5["github-pr-reviewer<br/>拉取请求自动化"] A6["自定义代理<br/>@AgentRegistry.register"] end subgraph Tools["工具层"] LOCAL["本地工具<br/>文件操作，AST解析，代码搜索"] MCP["MCP服务器<br/>网页抓取，外部API"] DELEG["代理调用<br/>跨代理委托"] end subgraph LLM["LLM提供商"] OAI["OpenAI"] ANT["Anthropic"] GGL["Google Gemini"] OLL["Ollama（本地）"] OR["OpenRouter"] EXT["10+提供商"] end WA1 & WA2 & WA3 -->|"WhatsApp协议"| SM SM --> EVT --> HTTP QR -.->|"二维码扫描链接"| Clients HTTP --> AUTH --> ROUTE ROUTE --> POOL --> DB DB --> SUM --> ROUTER --> AGENT AGENT --> LOCAL & MCP & DELEG AGENT --> OAI & ANT & GGL & OLL & OR & EXT POOL -.->|"选择代理"| Agents style Clients fill:#25D366,color:#fff style Gateway fill:#00ADD8,color:#fff style API fill:#3776AB,color:#fff style Graph fill:#9945FF,color:#fff style Agents fill:#6C63FF,color:#fff style Tools fill:#FF6B35,color:#fff style LLM fill:#E91E63,color:#fff ``` --- ## 消息流程 ``` 1. 用户向关联的WhatsApp号码发送消息 2. Go网关通过WhatsApp协议接收消息（whatsmeow） 3. 网关通过HTTP POST转发到Python API 4. API验证请求，解析租户 5. 租户代理池提供正确的代理实例 6. LangGraph执行：摘要 -> 路由器 -> 代理 7. 路由器分类意图（聊天 / 工具使用 / 研究 / 委托） 8. 代理执行工具，调用LLM，生成响应 9. 响应流回：代理 -> API -> 网关 -> WhatsApp -> 用户 ``` --- ## 安装 ### 选项A：Docker ```bash git clone https://github.com/MusadiqUrRahman/whaagent.git cd whaagent docker compose up -d ``` Docker在单个容器中构建Go网关和Python API。暴露端口`8000`。 ### 选项B：手动设置 **前提条件：** - Python 3.12+ - Go 1.21+ - [uv](https://docs.astral.sh/uv/) 包管理器 ```bash # 克隆 git clone https://github.com/MusadiqUrRahman/whaagent.git cd whaagent # 安装Python依赖项 uv sync # 构建Go网关 make gateway-build ``` --- ## 配置 ### 1. 环境变量 复制`.env.example`到`.env`并设置您的LLM API密钥： ```bash cp .env.example .env ``` ```env # 必需 - 您的LLM提供商API密钥 OPENAI_API_KEY=sk-... # 可选 - 使用OpenRouter访问多个提供商 # OPENAI_BASE_URL=https://openrouter.ai/api/v1 # 可选 - 使用Ollama进行本地推理（无需API密钥） # OPENAI_BASE_URL=http://localhost:11434/v1 ``` ### 2. 应用程序配置 运行交互式设置向导： ```bash whaagent init ``` 这会生成`~/.whaagent.yaml`: ```yaml llm: provider: openai model: gpt-4o-mini temperature: 0.1 api: host: 127.0.0.1 port: 8000 auth: api_keys: "your-api-key": "tenant-id" whatsapp: tenants: - id: personal phone: "+1234567890" default_agent: assistant - id: business phone: "+0987654321" default_agent: assistant ``` ### 3. 链接WhatsApp 启动服务，然后在浏览器中打开二维码页面： ```bash # 启动Python API whaagent serve # 启动Go网关（在另一个终端） cd gateway && go run . ``` 打开`http://localhost:8000/api/v1/whatsapp/qr/personal/page`，使用WhatsApp扫描（设置 > 链接设备）。 --- ## 代理 WhaAgent自带12个内置代理。每个代理都有系统提示、工具访问权限，可以自定义。 ### 内置代理 | 代理 | 用途 | |-------|---------| | `assistant` | 通用编排器，路由到工具和子代理 | | `developer` | 代码探索、文件分析、开发任务 | | `committer` | Git提交消息生成 | | `news` | 新闻聚合和总结 | | `br-news` | 巴西葡萄牙语新闻 | | `es-news` | 西班牙语新闻 | | `learning` | 教育内容和解释 | | `recipe` | 食谱生成和烹饪助手 | | `youtube` | YouTube转录提取和分析 | | `github-pr-reviewer` | 自动拉取请求审查 | | `paywall_remover` | 付费墙绕过，用于网页内容 | | `ollama` | 通过Ollama本地LLM | ### 代理配置 在`~/.whaagent.yaml`中为WhatsApp号码分配代理： ```yaml whatsapp: tenants: - id: sales phone: "+1234567890" default_agent: assistant # 使用assistant代理 - id: support phone: "+0987654321" default_agent: developer # 使用developer代理 ``` ### 创建自定义代理 ```python from whaagent import AgentBase, AgentRegistry @AgentRegistry.register("my-agent") class MyAgent(AgentBase): @property def system_prompt(self) -> str: return "您是针对我的用例的专用代理。" def local_tools(self) -> list: return [] # 可选的自定义工具 ``` 将文件放在`src/whaagent/agents/`中，它会在启动时自动注册。 --- ## CLI命令 ```bash whaagent init # 交互式设置向导 whaagent serve # 启动API服务器（端口8000） whaagent chat "消息" # 与AI本地聊天 whaagent list # 列出所有注册的代理 whaagent info <代理> # 显示代理详细信息 ``` --- ## API端点 | 方法 | 端点 | 描述 | |--------|----------|-------------| | `GET` | `/health` | 健康检查 | | `GET` | `/ready` | 就绪探测 | | `GET` | `/api/v1/whatsapp/qr/{tenant_id}/page` | 二维码查看器（浏览器） | | `GET` | `/api/v1/whatsapp/qr/{tenant_id}` | SSE二维码流 | | `POST` | `/api/v1/channels/whatsapp/message` | 传入消息Webhook | | `POST` | `/api/v1/channels/whatsapp/audio` | 音频消息Webhook | --- ## 系统设计 ### Go网关 基于[whatsmeow](https://github.com/tulir/whatsmeow)直接访问WhatsApp协议。 - 多租户会话管理 — 多个电话号码的并发连接 - 基于LID的JID解析 — 处理WhatsApp的链接身份设备格式 - 异步事件管道 — 长LLM调用不会阻塞传入消息处理 - 持久性打字指示器 — 在代理推理期间每3秒重新发送 - 会话恢复 — 通过设备重用在重启后存活 ### Python API 带有依赖注入和异步请求处理的FastAPI服务器。 - 租户代理池 — LRU逐出，按租户隔离代理实例 - SSE二维码流式传输 — 实时二维码交付到浏览器 - API密钥身份验证 — 网关到API的安全性 - 健康/就绪端点 — Kubernetes-ready探测 - 检查点持久性 — SQLite支持的对话内存 ### 代理框架 LangGraph驱动的3节点状态图： ``` 摘要 -> 路由器 -> 代理 ``` - **摘要节点** — 令牌阈值检查，压缩旧消息至约128个令牌 - **路由器节点** — LLM分类意图（聊天，工具使用，研究，委托） - **代理节点** — 工具编排，子代理委托，ReAct循环 ### 工具层 | 层 | 描述 | |-------|-------------| | **本地工具** | 文件操作，AST解析，代码搜索（ripgrep），语法验证（tree-sitter） | | **MCP服务器** | 模型上下文协议 — 网页抓取，外部API，自定义集成 | | **代理调用** | 跨代理委托，隔离执行上下文 | --- ## 技术栈 | 组件 | 技术 | 角色 | |-----------|-----------|------| | 网关 | Go + whatsmeow | WhatsApp协议，会话管理 | | API | FastAPI + uvicorn | 异步HTTP服务器，Webhook处理 | | 代理 | LangGraph + LangChain | 状态图，工具编排，内存 | | 工具 | tree-sitter，ripgrep | 代码分析，搜索 | | MCP | 模型上下文协议 | 外部工具集成 | | 存储 | SQLite | 检查点持久性，租户数据 | | LLM | 10+提供商 | OpenAI，Anthropic，Google，Ollama，OpenRouter等 | | 测试 | pytest + mypy + ruff | 80%覆盖率，严格类型，lint | --- ## 项目结构 ``` whaagent/ ├── src/whaagent/ │ ├── agents/ # 代理实现 │ │ ├── assistant.py # 通用编排器 │ │ ├── developer.py # 代码探索和分析 │ │ ├── news.py # 新闻聚合 │ │ ├── youtube.py # YouTube转录提取 │ │ ├── github_pr_reviewer.py │ │ └── ... │ ├── api/ │ │ ├── server.py # FastAPI应用工厂 │ │ ├── pool.py # 租户代理池（LRU逐出） │ │ ├── routes/ │ │ │ ├── whatsapp.py # WhatsApp Webhook处理程序 │ │ │ └── agents.py # 代理管理端点 │ │ ├── auth.py # API密钥身份验证 │ │ └── deps.py # 依赖注入 │ ├── graph.py # 3节点StateGraph（摘要/路由器/代理） │ ├── agent.py # AgentBase类，初始化，工具加载 │ ├── registry.py # 代理发现和注册 │ ├── config.py # YAML配置加载 │ ├── mcp/ │ │ ├── provider.py # MCP连接管理 │ │ └── config.py # MCP服务器发现 │ ├── tools/ │ │ ├── codebase_explorer.py │ │ ├── code_searcher.py │ │ └── manifest.py # 工具清单 + 电路中断器 │ ├── llm/ │ │ └── providers.py # 10+LLM提供商工厂 │ ├── prompts/ # 系统提示（.md文件） │ └── storage/ │ ├── database.py # SQLite设置 │ └── scheduler.py # 调度任务 ├── gateway/ # Go WhatsApp网关 │ ├── main.go # 入口点 │ ├── session.go # 多租户会话管理 │ ├── message.go # 消息处理 + 自我消息检测 │ └── qr.go # 二维码生成 ├── tests/ # 测试套件 ├── .env.example # 环境变量模板 ├── docker-compose.yml # Docker部署 ├── Dockerfile # 多阶段构建（Go + Python） ├── Makefile # 构建命令 └── pyproject.toml # Python项目配置 ``` --- ## 部署 ### Docker ```bash docker compose up -d # 启动 docker compose logs -f # 日志 docker compose down # 停止 ``` ### 裸金属（Linux VPS） ```bash uv sync make gateway-build # 启动服务 whaagent serve & cd gateway && go run . & # 可选：生产环境systemd服务 sudo cp deploy/*.service /etc/systemd/system/ sudo systemctl enable whaagent-api whaagent-gateway sudo systemctl start whaagent-api whaagent-gateway ``` --- ## 开发 ```bash make install # 安装依赖项 make test # 运行测试并生成覆盖率报告 make check # Lint + 类型检查（mypy，ruff） make format # 自动格式化代码 make build # 构建轮和sdist ``` --- ## 许可证 MIT --- <div align="center"> [](https://python.langchain.com) [](https://github.com/langchain-ai/langgraph) [](https://go.dev) [](https://fastapi.tiangolo.com) [](https://modelcontextprotocol.io) </div>