使用 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 与你的智能体之间的约定被刻意设计得很小。你的智能体接收入站消息并返回文本,可选地附带富消息附件。其余一切,包括会话接线、记忆绑定和投递调度,都会替你处理。
以下示例是一个 SMART 项目的完整 agent.py。脚手架命令(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 记忆,因此历史记录会在记忆保留期(默认 7 天)内跨会话和部署保留。
socialagent_notify_context() 包装器是另一个值得保留的模式。工具有时需要在智能体仍在工作时发送内容,例如按钮列表或进度更新。立即发送会破坏对话历史,用户的下一条消息会失败。包装器会改为收集这些消息,并在本轮结束后按顺序发出。你的工具正常发送消息,不必处理时机问题。
架构
下图展示了入站消息如何从 WhatsApp 传到你的智能体并返回,以及共享基础设施所在的位置。

图 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 Bedrock AgentCore 构建 WhatsApp AI 智能体
入站事件通过 Amazon Simple Notification Service (Amazon SNS) 到达。对于每个事件,webhook Lambda 函数会验证 SNS 消息签名、规范化负载,并对每个用户进行速率限制(默认每分钟 20 条消息,需启用 DynamoDB 状态表)。然后它会触发已读回执和正在输入指示器,让对话在模型完成之前显得有生气。语音消息通过 Amazon Transcribe 处理。其他媒体会变成描述符,或者如果你想要自定义处理,会进入你注册的钩子。当智能体被限流或失败时,用户会收到一条可自定义的可读消息,而不是沉默。
基于 SMART 构建的智能体会直接与最终用户交互,因此生产部署应包含适当的防护措施。Terraform 堆栈默认创建并配置 Amazon Bedrock Guardrails 资源。通过环境配置中的单个 guard
使用 Amazon Bedrock AgentCore 构建 WhatsApp AI agent
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 agent,没有任何工具、skills 或消息模板。从零开始构建就从这里起步。
- personal-assistant:一个通用助手,具备会话记忆、按用户隔离的状态、调度、skills 以及富媒体/语音/图片工具,基于 Strands 构建。要做对话式、全能型 agent 就从这里起步。
- appointment-scheduler:一个预约 agent,引导用户浏览条目目录和时间段,确认预约,将其存为按用户隔离的状态,并发送提醒。要做日程安排和预约流程就从这里起步。
你会得到一个项目,其中包含 agent.py、socialagent.dev.yaml(该项目的部署配置)、webhook、notification、event 和 scheduler 各路径的 handler 桩,以及一份随项目附带的 socialagent_runtime/ 副本。personal-assistant 和 appointment-scheduler 蓝图还会带上工具、skills 以及用于消息模板的 templates.yaml。minimal 不包含其中任何一项,需要时得自己加。
接下来,在本地迭代,完全不需要任何基础设施。
cd projects/my-bot
uv run socialagent dev --entrypoint agent.py
socialagent dev 命令会在终端 read-eval-print loop(REPL)中运行你真实的 agent 循环和真实的工具,AWS 通道 I/O 则被打桩。记忆变成基于本地文件的 session,状态变成一份在多个 dev session 之间共享的本地 JSON 文件。通知会打印到终端,包括按钮和列表行。一次性日程立即执行。周期性日程会被注册,但不会触发。工具调用会内联显示。回复以一条消息的形式到达,和在 WhatsApp 上一样。/event 和 /schedule 命令用于走通 handler 路径。整个过程不涉及部署,所以保存改动后马上就能测试。
有两点需要注意。模型调用是真实的,因此除 minimal 之外的蓝图需要 AWS 凭证和 Amazon Bedrock 访问权限。REPL 也不会模拟 IAM 或 Meta 的模板审核。在认为某件事完成之前,强烈建议通过已部署的 stack 进行测试。
你可以通过 recipe 添加能力。每个 recipe 是一个普通的 Python 函数,外加一份 markdown skill,用来教会 agent 何时使用它。
uv run socialagent recipe add voice-reply # or rich-messages, generate-image
把 recipe 接到 agentic 层是开发者的责任,这也正是 recipe 在更换 agent 框架时仍保持可移植的原因。
当本地行为符合预期后,部署 stack。
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 指向 stack 创建的 Amazon SNS topic。这项设置在 business account 上,不在 stack 里。使用管理控制台的 Bind 操作,或通过 CLI 的 aws socialmessaging put-whatsapp-business-account-event-destinations,把 WABA 的事件目标指向 stack 的 SNS topic。在完成关联之前,入站消息无处可去,而且不会报任何错。
当项目包含 templates.yaml 时,deploy 步骤还会把你的消息模板与 Meta 同步。如果需要单独同步模板,运行 uv run socialagent templates sync,它会从 socialagent.dev.yaml 读取 phone number ID 和前缀,并从 templates.yaml 读取模板定义。被拒绝的模板会导致 deploy 失败,所以要先改好措辞再重试。
文章标题:使用 Amazon Bedrock AgentCore 构建 WhatsApp AI 代理
正文: Meta 按用途对模板进行分类,事务性模板的发送规则比营销性模板更宽松。措辞保持平实。表情符号和营销话术是模板被重新归类为营销性模板的常见原因。运行 templates sync --force 会重新注册所有模板,把已批准的模板送回 Meta 重新审核。普通 sync 会跳过它们。除非你需要更改已批准模板的内容,否则不要动它们。
现在你可以给 WhatsApp 号码发消息了。
运行它
交付一个机器人是一个项目。运营一群机器人则是没人做过预算的部分,因此你还获得一个可选的管理控制台,它有自己的 Terraform root。部署一次即可。每个设置了 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 # 如果你部署了控制台
Terraform 不会移除三样东西。媒体和审计 S3 桶在存有对象时会阻止销毁,除非设置了 enable_force_destroy。向 Meta 注册的模板会保留。你的号码注册是账户级别的,会保留在原处。
开始使用
构建 WhatsApp AI 产品时,代理是你的差异化所在。渠道集成才是吞噬你路线图的部分。SMART 为你移动了这条边界。写一个提示词、几个工具和你的业务逻辑。作为回报,你得到 webhook 摄取、媒体处理、对话记忆、调度和模板管理。所有这些都由一条命令的基础设施、本地开发循环和运行在你自己的 AWS 账户中的管理控制台支撑。
要进一步深入,请采取以下后续步骤。
- 从 GitHub 上的 SMART 仓库获取代码。
- 使用 AWS End User Messaging Social 设置你的 WhatsApp Business Account。
- 从 socialagent init 和 socialagent dev 开始,它们不需要 AWS 基础设施。
- 阅读仓库中的文档,了解本文概括的各个领域,包括通知、媒体处理、事件与调度、按用户状态和消息模板。
- 如需进一步研究,请参阅 AgentCore 文档。
我们很期待看到你用它能构建出什么。