正文 · AI 翻译
在拉丁美洲、印度和东南亚,WhatsApp 是使用最广泛的即时通讯应用之一。这使它成为构建 AI 智能体的自然选择。对许多终端用户来说,他们期望通过它与企业互动。然而,即使你的智能体已经运行在 Amazon Bedrock AgentCore 上,要为 WhatsApp 构建集成仍然确实很困难。难点很少在智能体本身,而在集成。收到的消息以深度嵌套、因类型而异的载荷形式到达,必须经过身份验证和规范化,智能体才能读取。语音消息、图片和文档等媒体各自需要专门的处理流程。除了处理消息,你还需要能跨会话保留的对话记忆、可靠的提醒计划,以及供外部系统触发消息发送的经过身份验证的通道。而且,在终端用户上次发送消息超过 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 的项目最初计划用时 2 个月,后来将交付周期缩短至 6 周,并在全面发布前让其内部团队进入受控生产阶段。无论你是从头开始,还是迁移现有智能体,智能体逻辑都由你掌控。渠道交给 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 为你处理。 以下示例是一个完整的 SMART 项目 agent.py。脚手架命令(socialagent init)会创建围绕该文件的项目结构和配置。该文件存放你的代理逻辑。# --- AgentCore:运行时入口点 --- from bedrock_agentcore.runtime import BedrockAgentCoreApp from strands import Agent from strands.models import BedrockModel # --- SMART:渠道辅助函数 --- from socialagent_runtime import create_session_manager, socialagent_notify_context, SocialAgentResponse app = BedrockAgentCoreApp() # AgentCore 运行时模型 model = BedrockModel(model_id="us.anthropic.claude-haiku-5-5") # 或任何 Bedrock 模型 @app.entrypoint async def invoke(payload: dict, context: object = None) -> SocialAgentResponse: agent = Agent( model=model, system_prompt="你是一个乐于助人的 WhatsApp 助手。回复要简短。", session_manager=create_session_manager(payload), # AgentCore Memory,已预先接入 ) with socialagent_notify_context() as outbound: # SMART:收集出站消息 result = agent(payload["prompt"], invocation_state={"phone": payload["phone"]}) return SocialAgentResponse(result=str(result), outbound_messages=outbound) # SMART:响应封装 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 Simple Notification Service(Amazon SNS)到达。每次收到事件时,Webhook Lambda 函数都会验证 SNS 消息签名、规范化负载,并对每位用户实施速率限制(启用 DynamoDB 状态表时,默认为每分钟 20 条消息)。随后,它会发送已读回执和正在输入指示,让模型完成处理前的对话也显得有回应。语音留言会经过 Amazon Transcribe 处理。其他媒体会转换为描述信息;如果你希望自定义处理,也可以将其交给你注册的钩子。当代理限流或发生故障时,用户会收到一条你可以自定义的易读消息,而非得不到回应。基于 SMART 构建的代理会直接与最终用户互动,因此生产环境部署应包含适当的防护措施。Terraform 技术栈默认创建并配置一个 Amazon Bedrock Guardrails 资源。通过环境配置中的一个防护栏变量,你可以使用该技术栈的默认防护栏、自带防护栏,或完全停用。应用哪些控制措施由你决定。SMART 会确保相关连接已配置到位。消息准备好后,Webhook 函数会将其传给 AgentCore 运行时。 AgentCore memory 跨会话维护对话上下文,而 Amazon Bedrock AgentCore 的一项功能 AgentCore Observability 会追踪每一步,以便调试和审计。Webhook 函数发送回复以及工具在本轮交互中排队的消息。通知函数负责在交互轮次之外发送消息,例如主动发送或定时发送的消息。外部系统通过向受 API 密钥和 Lambda 授权程序保护的 Amazon API Gateway 端点发出 POST 请求来触发事件处理程序。事件发布到 Amazon SNS,事件 Lambda 随后运行你的处理程序。Amazon EventBridge Scheduler 负责基于时间的主动联系,例如提醒和定期跟进。借助通过 AWS End User Messaging 管理的消息模板,你可以在 24 小时 WhatsApp 会话窗口之外发送结构化通知。一次 socialagent deploy 会预置以下资源(其底层运行 terraform apply):Amazon Bedrock AgentCore runtime 和 AgentCore memory;Webhook、通知、事件和调度器 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 向企业颁发的身份。如需分步指南,请参阅《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 命令行界面(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 标志用于选择项目蓝图。项目提供 3 种蓝图;如果不传入参数,默认使用 minimal:minimal:仅具备回显功能的基础代理,没有工具、技能或消息模板。若要从零开始构建,可从这里入手。personal-assistant:基于 Strands 构建的通用助手,具备对话记忆、按用户保存的状态、调度、技能,以及丰富的语音、图像等媒体工具。若要构建能够处理各种任务的对话代理,可从这里入手。appointment-scheduler:预约代理,可引导用户浏览项目和时间段目录、确认预约、将预约保存为按用户区分的状态,并发送提醒。若要构建排期和预约流程,可从这里入手。生成的项目包含 agent.py、socialagent.dev.yaml(项目的部署配置)、Webhook、通知、事件和调度器路径的处理程序桩代码,以及随项目附带的 socialagent_runtime/ 副本。personal-assistant 和 appointment-scheduler 蓝图还包含工具、技能及用于消息模板的 templates.yaml。minimal 不附带这些内容,你可以按需添加。接下来,无需任何基础设施即可在本地迭代。 cd projects/my-bot uv run socialagent dev --entrypoint agent.py `socialagent dev` 命令会在终端的读取—求值—打印循环(REPL)中运行真实的智能体循环和真实工具,同时用桩代码替代 AWS 通道的输入输出。记忆会变成由本地文件支持的会话,状态则会变成在各次开发会话之间共享的本地 JSON 文件。通知会打印到终端,包括按钮和列表行。一次性计划任务会立即运行。周期性计划任务会被注册,但不会触发。工具调用会以内联方式显示。回复会像在 WhatsApp 上一样,以一条消息送达。`/event` 和 `/schedule` 命令可用于测试处理程序路径。此过程不涉及部署,因此保存更改后即可测试。有两点需要注意。模型调用是真实的,因此使用 `minimal` 以外的蓝图需要 AWS 凭证和 Amazon Bedrock 访问权限。REPL 也不会模拟 IAM 或 Meta 的模板审核。在认为工作完成之前,强烈建议通过已部署的技术栈进行测试。你可以通过配方添加功能。每个配方由一个普通的 Python 函数和一份 Markdown 技能说明组成,后者告诉智能体何时使用该功能。uv run socialagent recipe add voice-reply # 或 rich-messages、generate-image 将配方接入智能体层是开发者的责任;正因如此,即使更换智能体框架,配方仍可移植。本地行为符合预期后,部署技术栈。uv run socialagent bootstrap # 每个账户和阶段执行一次 # 在 socialagent.dev.yaml 中设置 whatsapp.phone_number_id,然后运行:uv run socialagent deploy 有一步是 Terraform 无法代你完成的。AWS End User Messaging Social 需要知道将收到的消息投递到哪里。将你的 WhatsApp Business Account 指向技术栈创建的 Amazon SNS 主题。该设置属于企业账户,而不属于技术栈。使用管理控制台中的 Bind 操作,或在 CLI 中运行 aws socialmessaging put-whatsapp-business-account-event-destinations,将 WABA 的事件目标指向技术栈的 SNS 主题。在完成关联之前,收到的消息不会送达任何地方,也不会报错。如果项目包含 templates.yaml,部署步骤还会将你的消息模板同步到 Meta。如果需要单独同步模板,请运行 uv run socialagent templates sync;它会从 socialagent.dev.yaml 读取电话号码 ID 和前缀,并从 templates.yaml 读取模板定义。模板被拒绝会导致部署失败,因此请先修改措辞,再重试。Meta 按用途对模板分类,事务性模板的发送规则比促销性模板更宽松。措辞应保持朴素。表情符号和营销用语通常是模板被重新归类为促销性模板的原因。运行 templates sync --force 会重新注册每个模板,使已获批准的模板再次接受 Meta 审核。普通同步会跳过这些模板。除非需要修改内容,否则不要改动已获批准的模板。现在你可以向自己的 WhatsApp 号码发送消息了。运营它。交付一个机器人是一个项目。运营一整批机器人才是没人为之编列预算的部分,因此你还可以使用一个可选的管理控制台,它有自己的 Terraform 根目录。只需部署一次。每个设置了 admin_registry_bucket 的 SMART 技术栈都会在部署时将自身注册到共享的 Amazon S3 注册表,管理控制台会从那里发现这些技术栈。控制台让你一眼了解整批机器人的运行状况,并深入查看各个机器人。在单个技术栈视图中,你可以执行以下操作。阅读真实对话并手动回复。检查和取消 Amazon EventBridge 计划任务,并浏览各用户的状态。重启单个 Lambda 函数或运行时。查看部署历史、近期错误和 Amazon CloudWatch 日志。触发测试事件。通过 WhatsApp 风格的呈现方式管理消息模板,并在 Meta 重新分类某个模板时看到警告。控制台还负责前文所述的电话号码绑定,因此将号码重新绑定到其他技术栈是一项界面操作。登录通过 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 不会移除以下 3 项。媒体和审计 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 文档。我们很期待看到您用它构建的成果。关于作者 Marco Larrea Marco 是 AWS Generative AI Innovation Center 的高级数据科学家,帮助客户将创意转化为可投入生产的生成式 AI 产品。他拥有利兹大学数理逻辑博士学位。Emmanuel Hernández Emmanuel 是 AWS Generative AI Innovation Center 的深度学习架构师,与拉丁美洲各地的客户合作,设计并交付具有重大影响的生成式 AI 解决方案。加入 GenAIIC 之前,他曾担任解决方案架构师多年,帮助企业构建可扩展的云架构。工作之余,他喜欢旅行、演奏音乐和听音乐。Diego Galaviz Diego 是 AWS Generative AI Innovation Center 的深度学习架构师,帮助客户大规模设计和部署生成式 AI 解决方案。他拥有超过 9 年的数据科学家经验,曾涉足金融服务、大型科技企业和网络安全领域,并拥有人工智能硕士学位。工作之余,他喜欢钻研机器人技术和物理 AI 项目。Artemio Padilla Artemio 是 AWS Generative AI Innovation Center 的深度学习架构师,为拉丁美洲各地的客户交付生产级生成式 AI 系统。加入 GenAIIC 之前,他曾在一家征信机构构建 MLOps 平台。工作之余,他喜欢游泳和在大自然中散步。