在线AI教程 / AI部署
[Amazon Bedrock] 使用 Amazon Bedrock AgentCore 构建 WhatsApp AI 代理
人工智能 使用 Amazon Bedrock AgentCore 构建 WhatsApp AI 代理 在拉丁美洲、印度和东南亚,WhatsApp 是使用最广泛的消息应用之一。这使它
人工智能
使用 Amazon Bedrock AgentCore 构建 WhatsApp AI 代理
在拉丁美洲、印度和东南亚,WhatsApp 是使用最广泛的消息应用之一。这使它自然成为构建 AI agent 的地方。对许多终端用户来说,这正是他们期望与企业互动的方式。然而,它也是一个真正难以开发对接的平台,即便你的 agent 已经运行在 Amazon Bedrock AgentCore 上。
难的部分很少是 agent 本身,而是集成。入站消息以深度嵌套、依类型而异的 payload 形式到达,必须先完成认证和规范化,agent 才能读取。语音消息、图片和文档等媒体各自需要自己的处理流水线。除消息处理之外,你还需要能跨会话保留的对话记忆、用于提醒的持久调度,以及一条经过认证的路径,让外部系统可以触发外发消息。并且,在终端用户最后一条消息之后超过 24 小时发送的任何内容,都必须使用事先通过审核的 Meta 消息模板。
把这些接起来,意味着要配置 10 多个 AWS 服务,并了解一组 WhatsApp 系统行为——大多数团队都是踩坑之后才知道它们。这些对客户都不可见,但每一处都必须正常工作。大多数团队要么从零自建,要么把集成交给第三方服务。
SMART(Social Messaging Agent Runtime Toolkit) 是第三种选择:一个开源 Python SDK 与 Terraform stack,为你提供完整的渠道层。你只需提供一个运行在 Amazon Bedrock AgentCore runtime 上的 agent,其余由 SMART 处理。一条命令即可把整套基础设施部署到你的 AWS 账户。
已有团队在使用 SMART 配合 Amazon Bedrock AgentCore 运行。Webmotors 最初按两个月的工期立项,最终把交付压缩到六周,并在正式上线之前就让内部团队进入受控生产环境。
无论你是从零开始,还是迁移已有的 agent,agent 的逻辑都由你掌控,渠道交给 SMART。
你不必自己构建的渠道层
下表对比了各项关注点自行构建的成本与 SMART 提供的能力。
关注点自行构建使用 SMART Webhook 接入签名校验、嵌套 payload、十几种消息类型已处理,你收到的是干净的 prompt 媒体下载、转写、存储、清理,以及发送前上传外发文件双向全生命周期 消息模板与 24 小时窗口Meta 审核流程、类别规则、跟踪每个对话处于哪个窗口在 YAML 中声明,由 CLI 同步 对话记忆多层记忆、会话中断处理Amazon Bedrock AgentCore memory,一次函数调用 调度与触发Amazon EventBridge Scheduler 接线、认证入口、路由内置 基础设施10 多个 AWS 服务拼装在一起一次 terraform apply 本地开发每次改动都要重新部署并开隧道用 CLI 在本地测试,无需重新部署
agentic 层
Amazon Bedrock AgentCore 是一个用于大规模构建、连接和优化 agent 的平台,支持任意框架或模型。SMART 建立在其两项主要能力之上:
AgentCore runtime 负责托管并扩缩容你的 agent,无需你管理基础设施。 AgentCore memory 在会话与部署之间持久保留对话历史,并自动按每个电话号码限定作用域。
由于 AgentCore 与框架无关,SMART 同样如此。Strands Agents 会自动接好记忆。LangGraph、Pydantic-AI,或其他让你掌控对话循环的框架也可以集成。无论使用哪种框架,SDK 都暴露相同的记忆与会话钩子。你的产品中真正带来差异化的部分——框架、模型、prompt 与业务逻辑——仍完全由你掌控。
SMART 与你的 agent 之间的接口约定刻意保持得很小:agent 接收入站消息,返回文本,可选附带富消息附件。其余一切——会话接线、记忆绑定、发送调度——都由系统替你处理。
下面的示例是一个 SMART 项目完整的 agent.py。脚手架命令(socialagent init)会在其周围创建项目结构与配置。你的 agent 逻辑就写在这个文件里。
--- 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 .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() 函数把 agent 绑定到按该电话号码限定作用域的 AgentCore memory,因此历史在会话与部署之间都能保留,保留期为记忆的留存时长(默认 7 天)。
socialagent_notify_context() 包装器是另一个值得保留的模式。工具有时需要在 agent 仍在工作时发送内容,例如按钮列表或进度更新。立即发送会破坏对话历史,用户的下一条消息就会失败。这个包装器则先把这些消息收集起来,等本轮结束后再按顺序发出。你的工具仍照常发送消息,无需处理时机问题。
架构
下图展示了一条入站消息如何从 WhatsApp 传到你的 agent 再返回,以及共享基础设施所处的位置。

图 1:一条入站 WhatsApp 消息如何经由 SMART 渠道层流向 agent 并返回
SMART 核心 stack 划分为若干独立的层:消息处理层、agent 层和服务层。AWS End User Messaging Social 接收入站 WhatsApp 消息,并将它们路由到处理层。一个 AWS Lambda 函数负责渠道逻辑,而 Amazon Bedrock AgentCore 为 agent 本身提供运行时、记忆和可观测性。Amazon DynamoDB(可选,用于按用户保存状态)、AWS Secrets Manager、Amazon CloudWatch 和 Amazon Simple Storage Service(Amazon S3)等支撑服务,为整套 stack 提供状态管理、凭证、监控和存储。
入站事件通过 Amazon Simple Notification Service(Amazon SNS)到达。每收到一个事件,webhook Lambda 函数会校验 SNS 消息签名、规范化 payload,并对每个用户做限流(启用 DynamoDB 状态表时,默认每分钟 20 条消息)。随后它会发出已读回执和「正在输入」提示,让对话在模型完成之前就有回应感。语音消息走 Amazon Transcribe。其他媒体会变成一个描述符,或者送入你注册的 hook,以便自定义处理。当 agent 被限流或失败时,用户会收到一条可自定义的可读消息,而不是一片沉默。
基于 SMART 构建的 agent 会直接与终端用户交互,因此生产部署应当包含适当的安全防护。Terraform stack 默认会创建并配置一个 Amazon Bedrock Guardrails 资源。通过环境配置中的一个 guardrail 变量,你可以使用 stack 的默认护栏、自带护栏,或完全退出。施加哪些控制由你决定,SMART 只负责确保接线已经就位。
消息准备好后,webhook 函数把它传给 AgentCore runtime。AgentCore memory 在会话之间维护对话上下文;Amazon Bedrock AgentCore 的能力之一 AgentCore Observability 会追踪每一步,便于调试与审计。
webhook 函数负责发送回复,以及本轮中你的工具排队发出的消息。通知函数处理轮次之外的发送,例如主动推送或定时消息。外部系统向由 API key 和 Lambda authorizer 保护的 Amazon API Gateway 端点发送 POST 请求,即可触发你的事件处理器。事件发布到 Amazon SNS 后,由 event Lambda 运行你的处理器。Amazon EventBridge Scheduler 负责基于时间的触达,例如提醒和周期性回访。借助通过 AWS End User Messaging 管理的消息模板,你可以在 24 小时 WhatsApp 会话窗口之外发送结构化通知。
一次 socialagent deploy 会预置以下资源(底层执行的是 terraform apply)。
Amazon Bedrock AgentCore runtime 与 AgentCore memory。 webhook、notification、event 和 scheduler 四个 Lambda 函数,运行 Python 3.12,各自带有 AWS X-Ray 追踪和死信队列。 Amazon SNS 摄取主题与事件 API。 Amazon EventBridge Scheduler。 用于媒体和审计日志的 Amazon S3 存储桶。 Amazon CloudWatch 仪表板与告警。
agent 容器镜像和 Lambda layer 会在 apply 期间由 AWS CodeBuild 构建。本地不需要 Docker。
你需要什么
部署之前,请确认你已具备以下条件。
AWS End User Messaging Social,且已关联 WhatsApp Business Account(WABA)并注册了电话号码。该账户就是 Meta 发放给企业的身份标识。分步指南见 Getting started with AWS End User Messaging Social,其中会带你完成 WABA 关联和电话号码注册。 一个 AWS 账户,且你的 AWS 区域中已提供 AgentCore runtime 和 AgentCore memory,并已启用模型访问权限。本演练默认使用 Amazon Bedrock 上的 Claude Haiku 5.5。你可以通过 Bedrock 访问更多基础模型(FM)。参见各区域的模型支持。 本地 Python 3.11 或更高版本。 Terraform 1.7 或更高版本、uv,以及 AWS Command Line Interface(AWS CLI)。仓库为部署者角色附带了一份起步用的 AWS Identity and Access Management(IAM)策略。完整操作列表见基础设施的 README。
注意:这是示例代码,不适用于生产用途。部署前,你应当与安全与法务团队合作,以满足组织的安全、监管与合规要求。
发布上线
首先克隆仓库并生成项目脚手架。
git clone 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 桩,以及一份 vendored 的 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 则被替换为桩实现。记忆变成由本地文件支撑的会话,状态变成一份在你的多个开发会话之间共享的本地 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 层是开发者的职责,正因如此,即使更换 agent 框架,recipe 也仍然可移植。
本地行为调好之后,部署 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 主题。该设置保存在业务账户上,而不在 stack 里。你可以在管理控制台中使用 Bind 操作,或用 CLI 执行 aws socialmessaging put-whatsapp-business-account-event-destinations,把 WABA 的事件目标指向 stack 的 SNS 主题。在完成关联之前,入站消息会无处可去,而且不会报任何错。
当项目包含 templates.yaml 时,部署步骤还会把消息模板与 Meta 同步。如果你需要单独同步模板,请运行 uv run socialagent templates sync,它会从 socialagent.dev.yaml 读取电话号码 ID 和前缀,从 templates.yaml 读取模板定义。被拒的模板会导致部署失败,因此请先修正措辞再重试。
Meta 按用途对模板分类,事务性模板的发送规则比营销类模板更宽松。请保持措辞朴素。emoji 和营销式语言通常是模板被重新归类为营销类的原因。运行 templates sync --force 会重新注册所有模板,把已审核通过的也重新送交 Meta 审核;普通的 sync 会跳过它们。除非需要修改内容,否则不要动已审核通过的模板。
现在你就可以给自己的 WhatsApp 号码发消息了。
运维
上线一个 bot 是一个项目;运维一批 bot 则是没人做过预算的部分,因此你还获得一个可选的、拥有独立 Terraform root 的管理控制台。它只需部署一次。每个设置了 admin_registry_bucket 的 SMART stack 会在部署时把自己注册到一个共享的 Amazon S3 registry,管理控制台再从那里发现这些 stack。
控制台让你一眼看到整个 bot 队列的健康状况,再深入到单个 bot。在单个 stack 视图中,你可以做以下事情。
查看真实对话并人工回复。 查看并取消 Amazon EventBridge 调度,浏览按用户存储的状态。 重启单个 Lambda 函数或 runtime。 查看部署历史、最近的错误和 Amazon CloudWatch 日志。 触发测试事件。 管理消息模板(提供 WhatsApp 风格的渲染效果),并在 Meta 重新归类某个模板时看到警告。
前面提到的电话号码绑定也由控制台负责,因此把号码重新绑定到另一个 stack 只是一个界面操作。
登录通过 Amazon Cognito 完成,强制要求多因素认证(MFA)。随后每条 API 路由都会执行基于角色的权限控制。控制台本身通过 Amazon CloudFront 从私有 Amazon S3 存储桶提供服务。
控制台端到端运行在 AWS 服务上。所有对话只涉及两个提供方:Meta 和 AWS。模型调用可能通过 Amazon Bedrock 的跨区域推理在其他 AWS 区域处理。关于推理路由、媒体处理和服务退出选项的细节,请参见仓库中的 docs/data-flows.md。
清理
为避免持续计费,请按以下顺序拆除这些 stack。
uv run socialagent destroy make ui-destroy # if you deployed the console
Terraform 不会移除三样东西。存放着对象的媒体和审计 S3 存储桶会阻止销毁,除非设置了 enable_force_destroy。注册到 Meta 的模板会保留。你的电话号码注册属于账户级别,会原地保留。
开始使用
构建 WhatsApp AI 产品时,差异化在于 agent,而渠道集成会吃掉你的路线图。SMART 为你挪动了这条边界。你只需写一个 prompt、几个工具和业务逻辑,换来的是 webhook 接入、媒体处理、对话记忆、调度与模板管理;这一切背后,是一条命令即可完成的基础设施、本地开发循环,以及运行在你自己的 AWS 账户中的管理控制台。
要进一步深入,可以采取以下后续步骤。
从 GitHub 上的 SMART 仓库获取代码。 用 AWS End User Messaging Social 设置好你的 WhatsApp Business Account。 从 socialagent init 和 socialagent dev 开始,它们不需要任何 AWS 基础设施。 阅读仓库中的文档,了解本文概述的各个主题,包括通知、媒体处理、事件与调度、按用户状态和消息模板。 如需进一步研究,参见 AgentCore 文档。
我们很期待看到你用它构建出什么。
关于作者