Whatsapp 应用

将 Agent 作为 Whatsapp 应用托管。

Whatsapp 应用用于服务通过 WhatsApp 交互的 Agent 或团队，使用 FastAPI 服务器处理 webhook 事件和发送消息。

设置和配置

1. 先决条件

   请确保您拥有以下条件：

   • Meta 开发者账户
   • Meta 商务账户
   • 有效的 Facebook 账户
   • ngrok (用于开发)
   • Python 3.7+
2. 创建 Meta 应用

   1. 前往 Meta for Developers 并验证您的账户。
   2. 在 Meta Apps Dashboard 创建一个新应用。
   3. 在“用例”下，选择“其他”。
   4. 选择“商务”作为应用类型。
   5. 提供：
      • 应用名称
      • 联系邮箱
   6. 点击“创建应用”。
3. 设置 Meta 商务账户

   1. 导航至 Meta Business Manager。
   2. 创建新的商务账户或使用现有账户。
   3. 点击邮件链接验证您的企业。
   4. 前往您的应用页面，导航至“应用设置/基本设置”，然后在“企业验证”下点击“开始验证”。完成生产环境的验证过程。
   5. 将应用与您的商务账户关联并点击“创建应用”。
4. 设置 WhatsApp Business API

   1. 前往您应用的 WhatsApp 设置页面。
   2. 点击“开始使用 API”（API 设置）。
   3. 生成访问令牌。
   4. 复制您的手机号码 ID。
   5. 复制您的 WhatsApp Business 账户 ID。
   6. 添加一个您将用于测试的“收件人”号码（这可能通常是您的个人号码）。
5. 设置环境变量

   在您的项目根目录创建一个 .envrc 文件，并包含以下内容，将占位符值替换为您自己的凭证：

   export WHATSAPP_ACCESS_TOKEN="your_whatsapp_access_token"
   export WHATSAPP_PHONE_NUMBER_ID="your_phone_number_id"
   export WHATSAPP_WEBHOOK_URL="your_ngrok_url_plus_webhook_path" # 例如：https://xxxxx.ngrok-free.app/webhook
   export WHATSAPP_VERIFY_TOKEN="your_chosen_verify_token" # 您创建的字符串
   

   确保您的 shell 加载了此文件（例如，通过使用 direnv allow）。

6. 使用 ngrok 设置 Webhook

   1. 对于本地开发，请使用 ngrok 将您的本地服务器暴露给互联网。如果您没有静态 ngrok URL，每次 ngrok 分配新 URL 时都需要更新 WHATSAPP_WEBHOOK_URL 环境变量和您的 Meta 应用 webhook 配置。
   2. 运行 ngrok，确保端口与您的 Agno WhatsApp 应用运行的端口匹配（例如 8000）：
      ngrok http 8000
      # 或者，如果您有付费 ngrok 账户并使用静态域名：
      # ngrok http --domain=your-custom-domain.ngrok-free.app 8000
      

   3. 复制 ngrok 提供的 https:// URL。这是您的基础 ngrok URL。
   4. 通过在 ngrok URL 后面添加 /webhook（或者您选择的前缀）来构建完整的 webhook URL（例如 https://<random-string>.ngrok-free.app/webhook）。如有必要，请更新 .envrc 中的 WHATSAPP_WEBHOOK_URL。
   5. 在您的 Meta 应用的 WhatsApp 设置页面，导航至“Webhook”部分并点击“编辑”。
   6. 配置 webhook：
      • 回调 URL（Callback URL）: 输入您完整的 ngrok webhook URL。
      • 验证令牌（Verify Token）: 输入与您在 .envrc 文件中 WHATSAPP_VERIFY_TOKEN 相同的值。
   7. 点击“验证并保存”。您的 Agno 应用程序必须在本地运行才能成功验证。
   8. 在成功验证后，点击 Webhook 字段旁边的“管理”。在 whatsapp_business_account 下订阅 messages 字段。
7. 配置应用程序环境

   设置 APP_ENV 环境变量：

   • 开发模式:
     export APP_ENV="development"
     

     （此时 webhook 签名验证可能不严格或被绕过）。
   • 生产模式:
     export APP_ENV="production"
     

     您还需要设置 WHATSAPP_APP_SECRET 以进行 webhook 签名验证：
     export WHATSAPP_APP_SECRET="your_meta_app_secret"
     

     这应该是您在 Meta 应用的“应用设置 > 基本设置”页面中找到的“应用密钥”。

示例用法

创建一个 Agent，用 WhatsappAPI 包裹它，然后运行它：

from agno.agent import Agent
from agno.app.whatsapp.app import WhatsappAPI
from agno.models.openai import OpenAIChat
from agno.tools.openai import OpenAITools

image_agent = Agent(
    model=OpenAIChat(id="gpt-4o"), # 确保已设置 OPENAI_API_KEY
    tools=[OpenAITools(image_model="gpt-image-1")],
    markdown=True,
    show_tool_calls=True,
    debug_mode=True,
    add_history_to_messages=True,
)

# 默认使用异步路由 (use_async=True)
whatsapp_app = WhatsappAPI(
    agent=image_agent,
    name="Image Generation Tools",
    app_id="image_generation_tools",
    description="A tool that generates images using the OpenAI API.",
)

app = whatsapp_app.get_app()

if __name__ == "__main__":
    whatsapp_app.serve(app="image_generation_tools:app", port=8000, reload=True)

运行方式：

1. 如果使用 OpenAI 模型，请确保已设置 OPENAI_API_KEY 环境变量。
2. API 将会运行（例如，http://localhost:8000），但主要通过配置的 webhook 与 WhatsApp 进行交互。
3. API 文档（如果设置中已启用）可能位于 http://localhost:8000/docs。

核心组件

• WhatsappAPI: 通过 FastAPI 将 Agno Agent/Team 封装以实现 WhatsApp 集成。
• WhatsappAPI.serve: 使用 Uvicorn 运行 FastAPI 应用，并配置为支持 WhatsApp。

WhatsappAPI 类

Agno WhatsApp 应用的主入口点。

初始化参数

参数	类型	默认值	描述
agent	Optional[Agent]	None	Agno Agent 实例。
team	Optional[Team]	None	Agno Team 实例。
settings	Optional[APIAppSettings]	None	API 配置。如果为 None 则使用默认配置。
api_app	Optional[FastAPI]	None	现有的 FastAPI 应用。如果为 None 则创建一个新的。
router	Optional[APIRouter]	None	现有的 APIRouter。如果为 None 则创建一个新的。
app_id	Optional[str]	None	应用标识符（如果未设置则自动生成）。
name	Optional[str]	None	应用名称。
description	Optional[str]	None	应用描述。

请提供 agent 或 team 中的一个，但不要同时提供。

主要方法

方法	参数	返回类型	描述
get_app	use_async: bool = True prefix: str = ""	FastAPI	返回已配置的 FastAPI 应用。设置前缀、错误处理器，并包含 WhatsApp 路由。默认使用异步路由。

端点

端点可在 prefix（默认为根级别：""）访问。

1. GET /webhook

• 描述: 验证 WhatsApp webhook（challenge）。
• 响应:
  • 200 OK: 如果令牌匹配，则返回 hub.challenge。
  • 403 Forbidden: 令牌不匹配或模式无效。
  • 500 Internal Server Error: 未设置 WHATSAPP_VERIFY_TOKEN。

2. POST /webhook

• 描述: 接收传入的 WhatsApp 消息和事件。
• 处理:
  • 验证签名（如果 APP_ENV="production" 且 WHATSAPP_APP_SECRET 已设置）。
  • 通过 agent.arun() 或 team.arun() 处理消息（文本、图像、视频、音频、文档）。
  • 通过 WhatsApp 发送回复。
• 响应:
  • 200 OK: {"status": "processing"} 或 {"status": "ignored"}。
  • 403 Forbidden: 签名无效。
  • 500 Internal Server Error: 其他处理错误。

参数

参数	类型	默认值	描述
app	Union[str, FastAPI]	N/A	FastAPI 应用实例或导入字符串（必需）。
host	str	"localhost"	绑定的主机。
port	int	7777	绑定的端口。
reload	bool	False	为开发启用自动重载。