WhatsApp AIエージェントのチャネル実装を簡素化するSMART――AgentCoreとTerraformで構築


ADVERTISEMENT

エージェント開発の障壁は、モデルよりチャネル統合にある

Amazon Bedrock AgentCore上で動くエージェントをWhatsAppに接続する際、難所になるのはエージェント本体よりも、その前後を支えるチャネル基盤だ。受信イベントには型ごとに異なる深い階層のペイロードが含まれ、署名検証と正規化を経て初めてエージェントが処理できる。さらに、音声メモ、画像、文書ではそれぞれ異なるメディア処理が必要になる。

運用面では、セッションをまたぐ会話メモリ、リマインダーなどの永続スケジュール、外部システムからの認証済み送信経路も欠かせない。特に、ユーザーの最終メッセージから24時間を超えて送信する場合は、Metaが事前承認したメッセージテンプレートを使う必要がある。これらを個別に実装すると、10を超えるAWSサービスの構成に加えて、WhatsApp固有の挙動への対応が開発・運用負担となる。

AWSが紹介するSMART(Social Messaging Agent Runtime Toolkit)は、このチャネル層をまとめて提供するオープンソースのPython SDKとTerraformスタックだ。開発者はAgentCore Runtimeで動くエージェントを用意し、SMARTにWebhook受信、メディア処理、メモリ連携、スケジューリング、テンプレート管理などを任せる。socialagent deployは内部でTerraformを実行し、必要なインフラをAWSアカウントに展開する。

メッセージの入口から返信までを担う構成

受信メッセージはAWS End User Messaging SocialからAmazon SNSを通じて取り込まれ、Webhook用Lambdaに渡される。このLambdaはSNSメッセージの署名を検証し、ペイロードを正規化する。DynamoDBの状態テーブルを有効にした場合、ユーザーごとのレート制限はデフォルトで毎分20メッセージとなる。処理中には既読通知と入力中インジケーターを返し、モデル応答を待つ間も会話が停止したように見えないようにする。

音声メモはAmazon Transcribeに渡される。その他のメディアは、内容を表す記述子として扱うか、開発者が登録する独自の処理フックに送る。エージェントがスロットリングまたは失敗した場合には、無応答で終わらせず、カスタマイズ可能なメッセージをユーザーに返す設計だ。

処理済みの入力はAgentCore Runtimeに渡され、AgentCore Memoryがセッションをまたぐ会話履歴を保持する。メモリは電話番号単位でスコープされ、保持期間はデフォルトで7日間。AgentCore Observabilityは、デバッグや監査に利用できるよう処理の各段階をトレースする。返信と、ツールが処理中にキューへ追加したメッセージは、ターン終了後に順序立てて送信される。

ターン外の通知には専用の通知機能を使う。外部システムからのイベントは、APIキーとLambda authorizerで保護されたAmazon API Gatewayエンドポイントで受け付け、Amazon SNS経由でイベント用Lambdaに渡す。時刻指定の通知や定期的な連絡にはAmazon EventBridge Schedulerを利用し、24時間のセッションウィンドウ外ではメッセージテンプレートを使う。

このスタックは、AgentCore RuntimeとMemoryに加え、Webhook・通知・イベント・スケジューラー用のLambda関数、SNSの取り込みトピック、イベントAPI、EventBridge Scheduler、メディアおよび監査用のS3バケット、CloudWatchのダッシュボードとアラームを展開する。各LambdaはPython 3.12で、AWS X-Rayトレーシングとデッドレターキューを備える。エージェントのコンテナイメージとLambdaレイヤーはapply中にAWS CodeBuildでビルドされるため、ローカル環境にDockerを用意する必要はない。

小さなエージェント契約と、導入時に外せない設定

SMARTとエージェント間の契約は、受信メッセージを受け取り、テキストと任意のリッチメッセージ添付を返すという小さなものだ。セッション配線、メモリ結合、送信タイミングなどはチャネル層が受け持つ。create_session_manager(payload)は電話番号に対応するAgentCore Memoryをエージェントに結び付ける。socialagent_notify_context()は、ツールからターン中に送るボタン一覧や進捗通知などをいったん収集し、ターン終了後に配信する。即時送信によって会話履歴が崩れ、ユーザーの次のメッセージ処理に影響するのを避けるための仕組みだ。

SMARTはフレームワークに依存しない。Strands Agentsではメモリを自動配線でき、LangGraphやPydantic-AIなど、会話ループを制御できるフレームワークも同じメモリ・セッションフックを利用できる。フレームワーク、モデル、プロンプト、業務ロジックは開発者が保持し、チャネル固有の処理を共通基盤に委ねる構成となる。

開発はsocialagent initでプロジェクトを作り、socialagent devでローカルから始められる。ローカル実行では、AWSのチャネルI/Oをスタブ化しつつ、実際のエージェントループとツールをREPLで試せる。メモリはファイルベースのセッション、ユーザー状態はローカルJSONファイルとなり、通知は端末に表示される。一回限りのスケジュールは即時実行され、定期スケジュールは登録のみで発火しない。モデル呼び出し自体は実際に行われるため、minimal以外のブループリントではAWS認証情報とAmazon Bedrockへのアクセスが必要だ。また、この環境ではIAMやMetaのテンプレート審査を再現できないため、デプロイ後のテストも推奨される。

デプロイ前には、WhatsApp Business Account(WABA)と登録済み電話番号をAWS End User Messaging Socialに用意し、対象リージョンでAgentCore Runtime、AgentCore Memory、モデルへのアクセスを確認する。Python 3.11以降、Terraform 1.7以降、uv、AWS CLIも必要となる。デプロイ後には別途、WABAのイベント送信先をスタックが作成したSNSトピックへバインドしなければならない。この設定はTerraformでは完了せず、未設定でもエラーにならず受信メッセージが届かないため、導入時の重要な確認点だ。

テンプレート定義がある場合、デプロイ時にMetaとの同期が行われる。テンプレートは用途に応じて分類され、トランザクション用途のものはプロモーション用途より送信ルールが緩やかとされる。テンプレートの再登録は承認済みのものも審査に戻すため、内容変更が必要な場合に限る運用が望ましい。

本記事のSMARTはサンプルコードであり、非本番利用向けと明記されている。Terraformはメディア・監査用S3バケットにオブジェクトが残っている場合、既定ではそれらの削除を妨げる。また、Metaに登録済みのテンプレートと電話番号登録はスタック削除後も残る。継続費用の防止や情報保持の観点から、破棄前後のリソース確認が必要だ。

開発者・エンジニア視点での考察

  1. チャネル層の抽象化は、境界を明確にして初めて保守性につながる。 SMARTは受信メッセージと応答を中心に契約を小さく保ち、通知のキューイングやセッション管理をSDK側に寄せている。独自ツールを追加する際も、この境界を維持すれば、チャネル制御と業務ロジックが結合するのを抑えられる。フレームワーク移行を想定するなら、ツールが依存するメモリ・セッションフックを早期に洗い出すべきだ。

  2. ローカルREPLと本番相当環境の検証範囲を分ける必要がある。 socialagent devは反復開発を速める一方、IAM、Metaのテンプレート審査、WABAのイベント送信先設定までは検証しない。したがって、ローカルテストを通過条件とせず、デプロイ後に受信経路、認証、テンプレート、スケジュール、失敗時メッセージを含む統合テストを行う段階を設けるのが実務的だ。

  3. 運用機能と安全策は、採用時に自組織の要件へ読み替えるべきだ。 SMARTはデフォルトでAmazon Bedrock Guardrailsリソースを作成し、既定のガードレール利用、持ち込み、無効化を環境設定で選べる。一方、適用する制御は利用者側の判断に委ねられている。会話閲覧や手動返信などを提供する任意の管理コンソールも、Cognitoによるサインイン、必須MFA、APIルートごとのロールベース権限を備えるが、サンプルコード自体は非本番利用向けである。セキュリティ、規制、コンプライアンス要件との照合を、導入前の作業として明示しておきたい。

Source / 元記事

この記事について

著者
AIBloom AI編集部
初回公開
最終更新

この記事は、公開されているニュース、論文、公式発表、RSSフィードなどをもとに、AIが要約・補足調査・考察を行って作成しています。

元記事の完全な翻訳・逐語的な要約ではなく、AIによる背景説明や開発者向けの考察を含みます。

重要な技術仕様・価格・提供状況などは、必ず元記事または公式情報をご確認ください。

About AIBloom

ADVERTISEMENT