如何以 Amazon Bedrock AgentCore 和 SMART 建構 WhatsApp AI 智能體
Build WhatsApp AI agents with Amazon Bedrock AgentCore
SMART(Social Messaging Agent Runtime Toolkit)是一套開源 Python SDK 及 Terraform 堆疊,可配合 Amazon Bedrock AgentCore 建構 WhatsApp AI 智能體並處理通道整合。
文章梳理 WhatsApp 智能體的通道工程負擔,並呈現 SMART 如何整合訊息驗證、媒體處理、記憶及排程,讓讀者瞭解端到端接入流程。
在拉丁美洲、印度及東南亞,WhatsApp 是最廣泛使用的即時通訊應用程式之一。因此,這裡顯然是建立 AI 智能代理的理想選擇。對很多終端用戶而言,他們預期會透過 WhatsApp 與企業互動。不過,即使你的智能代理已在 Amazon Bedrock AgentCore 上運行,WhatsApp 仍然是個確實很難開發的平台。
智能代理本身通常不是難點,整合才是。傳入訊息會以深度巢狀、按類型而異的承載資料送達,必須先完成身份驗證及正規化,智能代理才能讀取。語音訊息、圖片及文件等媒體,各自需要專屬的處理流程。除訊息處理外,你還需要可跨工作階段保留的對話記憶、用於提醒的持久排程,以及一條經身份驗證的途徑,讓外部系統觸發發送訊息。此外,若距離終端用戶上次發送訊息已超過 24 小時,你發送的任何訊息都必須使用 Meta 預先核准的訊息範本。
要串接這些服務,意味著你必須設定 10 多項 AWS 服務,並瞭解一系列 WhatsApp 系統行為;大多數團隊都是遇上問題後才會發現這些行為。客戶看不到這些部分,但每一環都必須正常運作。大多數團隊會選擇從零開始構建,或把整合工作交給第三方服務。
SMART (Social Messaging Agent Runtime Toolkit) 提供第三種選擇:一套開源 Python SDK 和 Terraform 技術堆疊,為你提供完整的渠道層。你只需提供一個在 Amazon Bedrock AgentCore 執行環境上運行的智能代理,其餘工作由 SMART 處理。一條命令即可將整套基礎設施部署到你的 AWS 帳戶。
已有團隊使用 SMART 和 Amazon Bedrock AgentCore 運行。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 之間的介面契約刻意保持精簡。你的 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
@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() 函數會將 Agent 綁定至以該電話號碼為範圍的 AgentCore 記憶,讓歷史記錄在不同工作階段及部署之間持續保留,直至記憶保留期屆滿(預設為 7 天)。
另一個值得保留的模式是 socialagent_notify_context() 包裝器。有時工具需要在 Agent 仍在處理時傳送內容,例如按鈕清單或進度更新。若立即傳送,便會破壞對話歷史記錄,導致用戶的下一則訊息無法處理。包裝器會先收集這些訊息,待回合結束後再按順序傳送。你的工具照常傳送訊息,無須處理傳送時機。
架構
以下圖表展示傳入訊息如何由 WhatsApp 傳送至你的 Agent,再傳回 WhatsApp,以及共用基礎設施所在的位置。
圖 1:傳入的 WhatsApp 訊息如何經 SMART 通道層傳送至 Agent,再傳回 WhatsApp
SMART 核心技術堆疊分為不同層級:訊息處理層、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) 等支援服務,則為整個技術堆疊提供狀態管理、憑證、監控及儲存功能。
傳入事件會經 Amazon Simple Notification Service (Amazon SNS) 抵達。每當收到事件,Webhook Lambda 函數便會驗證 SNS 訊息簽章、正規化資料內容,並對每位用戶實施速率限制(預設每分鐘 20 則訊息,並啟用 DynamoDB 狀態資料表)。接著,系統會發送已讀回條及輸入中指示,讓對話在模型完成處理前也有即時互動感。語音訊息會交由 Amazon Transcribe 處理。其他媒體會轉換為描述項;如需自訂處理方式,也可交由你註冊的 hook 處理。當 Agent 遭遇限流或發生故障時,用戶會收到可自訂且易於理解的訊息,而非全無回應。
以 SMART 建構的 Agent 會直接與終端用戶互動,因此正式環境部署應配備適當的防護措施。Terraform 技術堆疊預設會建立並設定 Amazon Bedrock Guardrails 資源。只需在環境設定中加入一個 guardrail 變數,便可使用技術堆疊的預設防護機制、自備防護機制,或完全不使用防護機制。你可自行決定要套用哪些控制措施;SMART 已預先接妥所需整合。
訊息準備好後,webhook 函數會將訊息傳送至 AgentCore runtime。AgentCore memory 會在不同工作階段之間保留對話脈絡,而 Amazon Bedrock AgentCore 的功能之一 AgentCore Observability,則會追蹤每個步驟,方便除錯及稽核。
webhook 函數會傳送回覆,以及你的工具在該回合排入佇列的訊息。通知函數負責處理回合以外的傳送,例如主動傳送或排程訊息。外部系統會向受 API 金鑰及 Lambda authorizer 保護的 Amazon API Gateway 端點發送請求,觸發你的事件處理常式。事件會發佈至 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 儀錶板及警示。
Agent 容器映像及 Lambda layer 會在執行 apply 時於 AWS CodeBuild 中建置。本機無須安裝 Docker。
所需項目
部署前,請確認你具備以下項目。
- AWS End User Messaging Social,並已連結 WhatsApp Business Account (WABA) 及登記電話號碼。該帳戶是 Meta 發給商戶的身份。逐步指南請參閲 開始使用 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 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,不含工具、技能或訊息範本。若要從頭開始建構,請由此入手。personal-assistant:以 Strands 建構的通用助理,具備對話記憶、每位用戶的狀態、排程、技能,以及豐富媒體、語音和圖片工具。若要建立可處理各類任務的對話式 Agent,請由此入手。appointment-scheduler:預約 Agent,會引導用戶瀏覽項目目錄及時段、確認預約、將預約儲存為每位用戶的狀態,並傳送提醒。若要建立排程及預約流程,請由此入手。
你會取得一個專案,內含你的 agent.py、socialagent.dev.yaml(專案的部署設定)、Webhook、通知、事件及排程器路徑的處理常式 stub,以及 socialagent_runtime/ 的隨附副本。個人助理及預約排程器藍圖亦包含工具、技能,以及供訊息範本使用的 templates.yaml。minimal 不會隨附上述任何項目,因此你需要按需要自行加入。
接下來,可在本機反覆迭代,完全毋須基礎設施。
cd projects/my-bot
uv run socialagent dev --entrypoint agent.pysocialagent dev 指令會在終端機的讀取-求值-輸出循環(REPL)中執行真正的代理循環和工具,並以 stub 代替 AWS 通道的輸入/輸出。記憶會變成本機檔案儲存的工作階段,狀態則會變成本機 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 執行 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 重新分類某個範本時查看警告。
主控台亦負責管理前文所述的電話號碼綁定,因此,將號碼重新綁定至不同堆疊是一項 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 consoleTerraform 不會移除以下三項內容。只要媒體及稽核 S3 儲存貯體內仍有物件,就會阻止 destroy,除非已設定 enable_force_destroy。在 Meta 註冊的範本會繼續保留。電話號碼註冊屬於帳戶層級,亦會繼續保留。
開始使用
建立 WhatsApp AI 產品時,Agent 是你建立差異化的關鍵;渠道整合則會佔用你的開發資源。SMART 替你處理這部分。只需撰寫提示詞、幾個工具及業務邏輯,即可使用 webhook 接收、媒體處理、對話記憶、排程及範本管理功能。所有功能均由可透過單一命令部署的基礎設施、本機開發流程,以及在你自己的 AWS 帳戶中運行的管理主控台提供支援。
如要進一步探索,請採取以下步驟。
- 從 GitHub 上的 SMART 存放庫取得程式碼。
- 使用 AWS End User Messaging Social設定 WhatsApp Business 帳戶。
- 先從
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 之前,他曾任解決方案架構師多年,協助企業建立可擴展的雲端架構。在 AWS 工作以外,他喜歡旅行、演奏音樂及聽音樂。
Diego Galaviz
Diego 是 AWS Generative AI Innovation Center 的深度學習架構師,協助客戶設計及大規模部署生成式 AI 解決方案。他在金融服務、大型科技企業及網絡安全領域擔任數據科學家,累積逾 9 年經驗,並持有人工智能碩士學位。工作以外,他會花時間動手研究機械人及實體 AI 項目。
Artemio Padilla
Artemio 是 AWS Generative AI Innovation Center 的深度學習架構師,為拉丁美洲各地的客戶交付可投入生產環境的生成式 AI 系統。加入 GenAIIC 前,他曾在一家信貸資料機構建立 MLOps 平台。在 AWS 以外,他喜歡游泳及在大自然中散步。
來源:AWS Machine Learning Blog · aws.amazon.com
