人工智能

使用 Amazon Bedrock AgentCore 构建 WhatsApp AI 智能体

在拉丁美洲、印度和东南亚,WhatsApp 是最广泛使用的即时通讯应用之一。这使它成为构建 AI 智能体的显而易见之选。对许多终端用户而言,这正是他们期望与企业互动的方式。然而,即便你的智能体已经运行在 Amazon Bedrock AgentCore.

上,它也是一个真正难以构建的界面。智能体本身很少是难点,集成才是。入站消息以深度嵌套、依赖类型的负载形式到达,必须先经过身份验证和归一化,你的智能体才能读取它们。语音留言、图片和文档等媒体各自需要自己的处理流水线。除了消息处理之外,你还需要能跨会话存活的对话记忆、用于提醒的持久调度,以及供外部系统触发外发消息的经过身份验证的路径。而且,在终端用户最后一条消息之后超过 24 小时发送的任何内容,都必须使用预先批准的 Meta 消息模板。

要接通这一切,意味着需要配置 10 多个 AWS 服务,并了解一系列 WhatsApp 系统行为——大多数团队只有在实际遇到时才会发现它们。这些对客户都不可见,但每一部分都必须正常工作。大多数团队要么从零开始构建,要么把集成交给第三方服务。

SMART(Social Messaging Agent Runtime Toolkit) 是第三种选择:一个开源 Python SDK 和 Terraform 栈,为你提供完整的渠道层。你只需提供一个运行在 Amazon Bedrock AgentCore runtime 上的智能体,SMART 负责其余部分。一条命令即可将整个基础设施部署到你的 AWS 账户。

团队已经在使用基于 Amazon Bedrock AgentCore 的 SMART。Webmotors 最初的项目范围是两个月,但将交付时间压缩到了六周,并在全面上线之前将内部团队推进到了受控生产环境。

无论你是从零开始,还是迁移现有智能体,智能体的逻辑都由你掌控。渠道部分交给 SMART 处理。

你无需构建的渠道层

下表对比了自行构建各项关注点所需的成本与 SMART 所提供的功能。

关注点 自行构建 使用 SMART
Webhook 接入 签名验证、嵌套负载、十几种消息类型 均已处理,因此你收到的是干净的提示
媒体 下载、转写、存储、清理,并在发送前上传出站文件 完整生命周期,双向处理
消息模板与 24 小时窗口 Meta 审批流程、类别规则、跟踪每个会话所处的窗口 在 YAML 中声明,由 CLI 同步
会话记忆 多层级记忆,会话中断处理 Amazon Bedrock AgentCore memory,一次函数调用
调度与触发 Amazon EventBridge Scheduler 接线、经过身份验证的入口、路由 内置
基础设施 拼接了 10 多个 AWS 服务 一个 terraform apply
本地开发 每次更改后重新部署并建立隧道 使用 CLI 在本地测试,无需重新部署

智能体层

Amazon Bedrock AgentCore 是一个用于大规模构建、连接和优化智能体的平台,支持任意框架或模型。SMART 基于其两项主要能力构建:

  • AgentCore runtime 托管并扩展你的智能体,无需你管理基础设施。
  • AgentCore memory 会跨会话和部署持久保存对话历史,并自动按每个电话号码划定作用域。

由于 AgentCore 与框架无关,SMART 也同样如此。 Strands Agents 会自动接入记忆功能。LangGraph、Pydantic-AI 或其他让你能控制对话循环的框架也可以集成。无论使用哪种框架,SDK 都暴露相同的记忆和会话钩子。你仍然完全掌控那些让你的产品与众不同的要素:框架、模型、提示词和业务逻辑。

SMART 与你的智能体之间的契约被刻意设计得很小。你的智能体接收入站消息并返回文本,可选地附带富消息附件。其余一切——会话接线、记忆绑定、投递调度——都由系统为你处理。

以下示例是一个完整的 agent.py SMART 项目。脚手架命令(socialagent init)会围绕它创建项目结构和配置。这个文件就是你的智能体逻辑所在之处。

# --- AgentCore: runtime entry point ---
from bedrock_agentcore.runtime import BedrockAgentCoreApp
from strands import Agent
from strands.models import BedrockModel
# --- SMART: channel helpers ---
from socialagent_runtime import create_session_manager, socialagent_notify_context, SocialAgentResponse

app = BedrockAgentCoreApp()                                # AgentCore Runtime
model = BedrockModel(model_id="us.anthropic.claude-haiku-5-5")          #Or any Bedrock model

@app.entrypoint
async def invoke(payload: dict, context: object = None) -> SocialAgentResponse:
    agent = Agent(
        model=model,
        system_prompt="You are a helpful WhatsApp assistant. Keep replies short.",
        session_manager=create_session_manager(payload),   # AgentCore Memory, pre-wired
    )
    with socialagent_notify_context() as outbound:         # SMART: collects outbound messages
        result = agent(payload["prompt"], invocation_state={"phone": payload["phone"]})
    return SocialAgentResponse(result=str(result), outbound_messages=outbound)  # SMART: response envelope

app.run()

该 create_session_manager() 函数将智能体绑定到以该电话号码为作用域的 AgentCore memory,因此历史记录可在记忆保留期(默认 7 天)内跨会话和部署持续存在。

该 socialagent_notify_context() wrapper 是另一个值得保留的模式。工具有时需要在智能体仍在工作时发送一些内容,例如按钮列表或进度更新。立即发送会破坏对话历史,导致用户的下一条消息失败。wrapper 会改为收集这些消息,并在本轮结束后按顺序发出。你的工具可以正常发送消息,无需处理时序问题。

架构

下图展示了入站消息如何从 WhatsApp 传到你的智能体并返回,以及共享基础设施所处的位置。

SMART architecture showing a WhatsApp message flowing through AWS End User Messaging, AWS Lambda, and Amazon Bedrock AgentCore across the message, agent, and service layers

图 1:一条入站 WhatsApp 消息如何经由 SMART 渠道层流向智能体并返回

SMART 核心栈被组织为不同的层:消息处理层、智能体层和服务层。AWS End User Messaging Social 接收入站 WhatsApp 消息并将其路由到处理层。AWS Lambda 函数负责处理渠道逻辑,而 Amazon Bedrock AgentCore 为智能体本身提供运行时、记忆和可观测性。Amazon DynamoDB(可选,用于按用户状态)、AWS Secrets Manager、Amazon CloudWatch 和 Amazon Simple Storage Service(Amazon S3)等支持服务在整个栈中提供状态管理、凭证、监控和存储。

入站事件通过 Amazon Simple Notification Service(Amazon SNS)到达。对于每个事件,webhook Lambda 函数会验证 SNS 消息签名、规范化负载,并对每个用户进行限流(默认每分钟 20 条消息,需启用 DynamoDB 状态表)。随后它会触发已读回执和正在输入指示器,让对话在模型完成之前就显得生动。语音消息会经过 Amazon Transcribe 处理。其他媒体会转换为描述符,或者如果你希望自定义处理,则发送到你注册的钩子。当智能体被限流或失败时,用户会收到一条可读的消息(你可以自定义),而不是一片沉默。

基于 SMART 构建的智能体直接与最终用户交互,因此生产部署应包含适当的安全防护措施。Terraform 栈默认会创建并配置一个 Amazon Bedrock 护栏 资源。只需在环境配置中设置一个 guardrail 环境配置变量,你可以使用该栈的默认护栏、自带护栏,或完全选择退出。你应用哪些控制由你决定。SMART 会确保相关接线已经就位。

消息准备就绪后,webhook 函数会将其传递给 AgentCore 运行时。AgentCore memory 跨会话维护对话上下文,而 Amazon Bedrock AgentCore 的一项能力 AgentCore Observability 会追踪每一步,以便调试和审计。

webhook 函数会发送回复以及你的工具在该轮次中排队的消息。通知函数负责处理轮次之外的发送,例如主动消息或定时消息。外部系统通过向受 API 密钥和 Lambda 授权方保护的 Amazon API Gateway 端点发送请求来触发你的事件处理程序。事件会发布到 Amazon SNS,事件 Lambda 会运行你的处理程序。Amazon EventBridge Scheduler 负责处理基于时间的触达,例如提醒和定期回访。借助通过 AWS End User Messaging 管理的消息模板,你可以在 24 小时 WhatsApp 会话窗口之外发送结构化通知。

单条 socialagent deploy 会预置以下资源(它在底层运行 terraform apply 底层运行)。

  • Amazon Bedrock AgentCore 运行时和 AgentCore memory。
  • webhook、notification、event 和 scheduler 这四个 Lambda 函数均基于 Python 3.12,各自都启用了 AWS X-Ray 追踪并配置了死信队列。
  • Amazon SNS 摄取主题和事件 API。
  • Amazon EventBridge Scheduler。
  • 用于媒体和审计追踪的 Amazon S3 存储桶。
  • Amazon CloudWatch 仪表板和告警。

代理容器镜像和 Lambda 层会在 apply 期间于 AWS CodeBuild 中构建。本地不需要 Docker。

你需要准备什么

部署之前,请确认你已具备以下条件。

  • AWS End User Messaging Social,并已关联 WhatsApp Business Account(WABA)并注册了电话号码。该账户就是 Meta 向企业发放的身份。有关分步指南,请参阅 AWS End User Messaging Social 入门指南,其中会引导你关联 WABA 并注册电话号码。
  • 你需要在 AWS 区域中拥有一个可用的、已启用 AgentCore runtime 和 AgentCore memory 的 AWS 账户,并已启用模型访问权限。本演练默认使用 Amazon Bedrock 上的 Claude Haiku 5.5。你可以通过 Bedrock 访问更多基础模型(FM)。请参阅 各区域的模型支持.
  • 本地需安装 Python 3.11 或更高版本。
  • 需要 Terraform 1.7 或更高版本、uv 以及 AWS 命令行界面(AWS CLI)。该仓库为部署者角色提供了一个起始的 AWS Identity and Access Management(IAM)策略。完整操作列表请参阅基础设施 README。

注意: 这是示例代码,仅供非生产用途使用。在部署之前,你应与你的安全和法务团队合作,以满足你所在组织的安全、监管和合规要求。

部署吧

首先克隆仓库并搭建项目脚手架。

git clone https://github.com/awslabs/social-messaging-agent-runtime-toolkit smart && cd smart && make install
uv run socialagent init my-bot --blueprint personal-assistant

该 --blueprint 标志用于选择项目蓝图。共有三种蓝图, minimal 如果你不传入参数,则这是默认值:

  • minimal:一个没有任何工具、技能或消息模板的极简 echo 智能体。从这里开始从零构建。
  • personal-assistant:一个具备对话记忆、按用户保存状态、调度、技能以及富媒体/语音/图像媒体工具的通用助手,基于 Strands 构建。从这里开始构建对话式、全能型智能体。
  • appointment-scheduler:一个预约智能体,引导用户浏览项目目录和时间段,确认预约,将其存储为按用户的状态,并发送提醒。从这里开始了解调度和预约流程。

你会得到一个项目,其中包含 agent.py, socialagent.dev.yaml (项目的部署配置)、webhook、通知、事件和调度器路径的处理程序存根,以及一份内置的 socialagent_runtime/个人助理和预约调度器蓝图还带来了工具、技能以及一个 templates.yaml 用于你的消息模板。 minimal 它不附带这些内容,因此你需要按需添加它们。

接下来,在本地进行迭代,完全不需要任何基础设施。

cd projects/my-bot
uv run socialagent dev --entrypoint agent.py

该 socialagent dev 命令会在终端读取-求值-打印循环(REPL)中运行你真实的智能体循环和真实工具,并将 AWS 通道 I/O 打桩。内存变为本地文件支持的会话,状态变为在你的开发会话之间共享的本地 JSON 文件。通知会打印到终端,包括按钮和列表行。一次性调度会立即运行。重复性调度会被注册但不会触发。工具调用会内联显示。回复以一条消息的形式到达,就像在 WhatsApp 上一样。 /event 和 /schedule 命令会执行各处理程序路径。不涉及部署,因此保存更改后即可立即测试。

有两点需要注意。模型调用是真实的,因此除 minimal 需要 AWS 凭证和 Amazon Bedrock 访问权限。REPL 也不会模拟 IAM 或 Meta 的模板审核。在认为任务完成之前,强烈建议通过已部署的堆栈进行测试。

你可以将各项能力作为配方添加。每个配方都是一个普通的 Python 函数,外加一份 markdown 技能说明,用于教会智能体何时使用它。

uv run socialagent recipe add voice-reply    # or rich-messages, generate-image

将配方接入智能体层是开发者的责任,这也正是当更换智能体框架时配方仍能保持可移植性的原因。

当本地行为正确时,部署该堆栈。

uv run socialagent bootstrap   # once per account and stage
# set whatsapp.phone_number_id in socialagent.dev.yaml, then:
uv run socialagent deploy

Terraform 无法为你完成的一步。AWS End User Messaging Social 需要知道将入站消息投递到哪里。将你的 WhatsApp Business Account 指向该堆栈创建的 Amazon SNS 主题。该设置位于业务账户上,而不在堆栈中。使用管理控制台的 Bind 操作,或通过 CLI,将 WABA 的事件目标指向该堆栈的 SNS 主题。 aws socialmessaging put-whatsapp-business-account-event-destinations 在完成关联之前,入站消息无处可去,也不会报任何错误。

当项目包含一个 templates.yaml,部署步骤还会将你的消息模板与 Meta 同步。如果你需要独立同步模板,请运行 uv run socialagent templates sync,它会从 读取电话号码 ID 和前缀。 socialagent.dev.yaml 以及来自 的模板定义 templates.yaml被拒绝的模板会导致部署失败,因此在重试之前请先修正措辞。

Meta 按用途对模板进行分类,交易类模板的发送规则比营销类模板更宽松。措辞要保持平实。表情符号和营销用语是模板被重新归类为营销类的常见原因。运行 templates sync --force 会重新注册每个模板,并将已批准的模板送回 Meta 审核。普通同步会跳过它们。除非需要更改已批准模板的内容,否则不要动它们。

现在你可以给你的 WhatsApp 号码发消息了。

运营它

部署一个机器人是一个项目。运营一支机器人队伍则是没人做过预算的部分,因此你还获得一个可选的管理控制台,它有自己的 Terraform 根。部署一次即可。每个设置了 admin_registry_bucket 的 SMART 堆栈在部署时会自行注册到共享的 Amazon S3 注册表,管理控制台则从那里发现这些堆栈。

控制台让你一眼掌握整个机群的健康状况,再深入查看每个机器人的细节。在单一堆栈视图中,你可以执行以下操作。

  • 阅读真实对话并手动回复。
  • 检查并取消 Amazon EventBridge 调度,并浏览每个用户的状态。
  • 重启单个 Lambda 函数或运行时。
  • 查看部署历史、最近的错误以及 Amazon CloudWatch 日志。
  • 触发测试事件。
  • 使用 WhatsApp 风格的渲染方式管理消息模板,并在 Meta 重新分类某个模板时看到警告。

控制台还负责前面提到的电话号码绑定,因此将号码重新绑定到另一个堆栈属于 UI 操作。

登录通过 Amazon Cognito 进行,并要求启用多因素认证(MFA)。随后在每个 API 路由上强制执行基于角色的权限。控制台本身通过 Amazon CloudFront 从私有 Amazon S3 存储桶提供。

该控制台端到端运行在 AWS 服务上。每次对话都只涉及两个提供商:Meta 和 AWS。模型调用可能通过 Amazon Bedrock 跨区域推理在其他 AWS 区域进行处理。详情请参阅 docs/data-flows.md 仓库中有关推理路由、媒体处理和服务退出选项的详细信息。

清理

为避免持续产生费用,请按以下顺序拆除这些堆栈。

uv run socialagent destroy
make ui-destroy   # if you deployed the console

Terraform 不会移除三样东西。媒体和审计 S3 存储桶在存有对象时会阻止销毁,除非设置了 enable_force_destroy 已设置。通过 Meta 注册的模板会保留。你的电话号码注册是账户级别的,并且会保持不变。

开始使用

在构建 WhatsApp AI 产品时,智能体才是你差异化优势所在。而渠道集成则会吞噬你的路线图。SMART 为你移动了这条边界。你只需编写提示词、几个工具和业务逻辑。作为回报,你将获得 webhook 接入、媒体处理、对话记忆、调度和模板管理。所有这些都由一键式基础设施、本地开发循环以及运行在你自己的 AWS 账户中的管理控制台提供支持。

要进一步深入,请执行以下后续步骤。

  • 从 GitHub 上的 SMART 仓库获取代码。 GitHub 上的 SMART 仓库.
  • 使用 AWS End User Messaging Social 设置你的 WhatsApp Business 账户。 AWS 终端用户消息社交.
  • 首先, socialagent init , socialagent dev,无需任何 AWS 基础设施。
  • 请阅读仓库中针对本文所概述各领域的文档,包括通知、媒体处理、事件与调度、每用户状态以及消息模板。
  • 如需进一步研究,请参阅 AgentCore 文档.

我们很期待看到您用它构建出什么。


关于作者