将您自己的 AI 智能体接入 WhatsApp：通过 Webhook 端点连接任何框架（LangGraph、ADK、自定义）

您几乎可以在不重写的情况下，把任何 AI 智能体接入 WhatsApp。让您用 LangGraph、Google ADK、CrewAI 或自己的代码构建的智能体运行在 HTTPS 端点之后，然后在 MonoChat 中把它添加为使用自定义提供方的 AI Harness：一个端点 URL 和一个共享密钥。在流程中放置一个 AI 智能体节点，连接您的 WhatsApp 号码，您的智能体就会在 WhatsApp 和 MonoChat 连接的所有其他渠道上回复客户，并配有共享收件箱和转人工机制。

本指南面向已经有智能体、或希望完全掌控其工作方式的团队。内容包括：何时适合带上自己的智能体、您的端点需要负责什么、在 MonoChat 中的设置，以及在生产环境中重要的细节。

为什么要带上自己的智能体？

大多数客户消息平台只自带一个内置 AI 智能体。这很方便，直到出现以下情况：

• 您的智能体已经构建好了。 您的开发人员花了几个月构建 LangGraph 图或 ADK 多智能体方案，并有评估和测试。在厂商的机器人构建器中重建它，等于把这些工作丢掉。
• 您需要自己的逻辑。 定价规则、资格检查、合规步骤，或只有您的代码才能访问的内部系统。
• 您想自己选择框架。 框架更新很快。今天是 LangGraph，明年可能是别的。您的渠道和收件箱不应随之改变。
• 数据必须留在您手中。 有些组织希望智能体的推理和工具调用在自己的基础设施上运行。

MonoChat 的 Agent Harness 正是为此而建：带上您自己的智能体框架，并把围绕它的一切（渠道、收件箱、人员）集中在一处。

自定义 Harness 如何工作

可以把它看作一种分工。

MonoChat 负责会话层：

• 与 WhatsApp、Instagram、Messenger、TikTok、Telegram、网页聊天、短信和语音的官方连接（MonoChat 是官方 Meta Business Partner）。
• 通过 AI 智能体节点决定何时调用智能体的流程。
• 共享团队收件箱，真人可在其中带着完整历史记录接手。

您的端点负责智能体：

• 接收来自 MonoChat 的会话。
• 运行您的智能体：它的推理、工具和记忆。
• 返回智能体的回复。

两者之间有一个共享密钥，即双方都知道的值，使您的端点能够验证请求来自您的 MonoChat 账户。MonoChat 定义了您的端点要实现的具体请求和响应格式；如果您还没有，请联系我们，我们会提供给您的开发人员。

您的端点应该做什么

无论使用哪种框架，一个可用于生产的智能体端点都有几项职责。

验证每个请求

每次调用都检查共享密钥，并拒绝任何不匹配的请求。把密钥存放在密钥管理器或环境变量中，而不是代码里，一旦暴露就要轮换。

让每场会话相互独立

客户会并行发消息。请确保智能体的状态、记忆和任何工作文件都限定在一场会话内，这样一位客户的信息就不会泄露到另一位客户的答复中。

以适合聊天的篇幅作答

为网页应用构建的智能体往往写出冗长、带格式的答案。WhatsApp 是在手机上阅读的。请要求您的智能体发送简短的消息，一次一个问题，并避免在回复中使用大量 Markdown。

失败时要明确，而不是悄无声息

如果工具超时或您的模型提供方返回错误，请返回明确的失败，而不是一个未完成的答案。可预期的失败能让流程做出正确的处理，例如把会话转交给真人。

要快

客户期望几秒内得到回复。尽可能把耗时较长的工作移出回复路径，并让您的工具快速或异步。

在 MonoChat 中分步操作

1. 在 HTTPS 之后部署您的智能体

把您的 LangGraph、ADK、CrewAI 或自定义智能体托管在您自己的服务器或云上，并可通过 HTTPS 访问。实现 MonoChat 的请求和响应格式以及共享密钥检查。

2. 添加使用“自定义”提供方的 AI Harness

在 MonoChat 中添加 AI Harness，选择自定义，并输入您的端点 URL 和共享密钥。Harness 只需添加一次，即可在任意多个流程中使用。

3. 在流程中添加 AI 智能体节点

在接收进线会话的流程中，添加一个 AI 智能体节点并选择您的自定义 Harness。把流程最擅长的事交给围绕它的流程：问候、按语言或主题路由、营业时间，以及通往真人的路径。

4. 为每次运行设置预算

每个 AI 智能体节点都支持每次运行的预算限制。请把它们用作安全网，与您在自己代码中已设置的限制并用。

5. 连接 WhatsApp 和其他渠道

连接您的 WhatsApp Business 号码，然后把同一个流程接入您使用的其他渠道。每个渠道无需额外的集成工作：您的端点看到的是会话，而不是渠道 API。

6. 测试，然后上线

用真实的客户消息在流程中回放。检查工具调用、响应时间、语气和转人工。密切关注上线最初几天的实际流量，然后再逐步扩大智能体被允许做的事情。

框架说明

LangGraph。 由节点和边构成的图天然适合客服流程（分诊、查询、解决、升级）。把编译好的图封装在一个小型 HTTP 服务中，在每次请求时加载会话状态并返回最终消息。

Google ADK。 ADK 的多智能体树，即一个协调者加若干专业子智能体，与客服、销售和账务团队的结构很匹配。通过您的端点公开根智能体，让 ADK 在内部路由。

CrewAI。 基于角色的智能体团队（crew）适合交接明确的任务，例如先研究再作答。在聊天中请保持团队精简：每多一个智能体就多一分延迟。

您自己的代码。 一个带模型 API 和几个函数的简单循环往往就足够了。您保持完全控制，而 MonoChat 为您提供渠道和收件箱。

转人工：在流程中决定

在流程中决定哪些会话转给真人、由哪个团队接收，并让您的智能体在无法提供帮助时如实告诉客户，而不是猜测。随后流程会带着完整历史记录把会话转交给共享收件箱中合适的团队。WhatsApp 的 Business Messaging Policy 也要求自动回复提供一条通往真人的清晰路径。

同时请让您的智能体留在您的业务范围之内。自 2026 年 1 月 15 日起，WhatsApp 禁止通用 AI 助手出现在该平台上；服务于您自己客户的智能体则没有问题。我们的 WhatsApp AI 聊天机器人政策指南解释了这一规则。

何时不必自己构建

自定义智能体是最灵活的选项，也是需要您自己维护的选项。如果您从零开始，内置选项能让您更快上线，且无需托管任何东西：

• MonoChat 的内置 Harness，基于您的 MonoChat AI 模型。
• OpenAI Agents SDK，在 MonoChat 内部运行（指南）。
• Claude Agent SDK 或 Pi，在 MonoChat 的智能体运行器上运行（Claude 指南）。
• 托管智能体：OpenAI Agents API 或 Claude Managed Agents，使用您自己的密钥。

由于每个选项都使用同一个 AI 智能体节点，您可以先从一个开始，之后再迁移到您自己的智能体，而无需改动您的渠道或转人工机制。请在 Agent Harness 页面对它们进行比较。