Build WhatsApp AI agents with Amazon Bedrock AgentCore
Quick Summary
SMART는 WhatsApp 메시지 처리와 발송을 맡는 오픈소스 Python SDK·Terraform 스택으로, 개발팀은 자체 AWS 계정에서 Amazon Bedrock AgentCore로 에이전트를 운영하며 모델과 비즈니스 로직을 직접 선택할 수 있다.
🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약
SMART는 WhatsApp 메시지 처리와 발송을 맡는 오픈소스 Python SDK·Terraform 스택으로, 개발팀은 자체 AWS 계정에서 Amazon Bedrock AgentCore로 에이전트를 운영하며 모델과 비즈니스 로직을 직접 선택할 수 있다.
📌 핵심 요약
- WhatsApp을 에이전트에 직접 연결하려면 10개가 넘는 AWS 서비스를 구성하고 메시지 인증, 미디어 처리, 대화 기억, 예약 발송을 연동해야 한다. SMART는 이 채널 인프라를 명령 하나로 배포한다.
- AgentCore runtime은 에이전트를 호스팅하고 확장하며, AgentCore memory는 전화번호별 대화 이력을 기본 7일간 보관해 세션이 바뀌거나 에이전트를 재배포해도 맥락을 이어 준다.
- SMART는 수신 메시지를 검증해 일정한 형식으로 전달하고, 에이전트가 응답을 생성하는 동안 도구가 보낸 메시지는 모아 두었다가 해당 차례가 끝나면 순서대로 발송한다.
- 사용자의 마지막 메시지로부터 24시간이 지난 뒤 발송하려면 Meta가 사전 승인한 메시지 템플릿이 필요하다. SMART는 템플릿을 YAML로 선언하고 CLI로 동기화하며, Amazon EventBridge Scheduler로 예약 알림을 처리한다.
- AWS에 따르면 Webmotors는 당초 2개월로 잡았던 작업을 6주 만에 마치고 정식 출시 전에 내부 팀이 참여하는 제한적 운영에 들어갔다. AWS는 글에 제공한 예제 코드를 비운영 환경용으로 명시한다.
🧩 주요 포인트
- 채널 통합은 SMART가 맡고 에이전트 로직은 개발팀이 소유하므로, 기존 에이전트를 옮길 때도 모델과 프레임워크 선택권이 유지된다.
- AgentCore memory의 기본 7일은 대화 이력의 보존 기간이고, WhatsApp의 24시간은 자유 형식 메시지의 발송 가능 기간이다. 대화 맥락이 남아 있어도 발송에는 템플릿이 필요할 수 있다.
- Amazon Bedrock Guardrails는 기본으로 구성되며 적용할 통제는 배포팀이 선택한다. AWS는 운영 배포 전에 보안·법무 팀과 조직의 요구사항을 검토하도록 안내한다.
🧠 상세 정리
1. WhatsApp 통합에 드는 작업
라틴아메리카, 인도, 동남아시아에서 WhatsApp은 널리 쓰이는 메신저이자 많은 사용자가 기업과 대화할 때 기대하는 접점이다. 이미 Amazon Bedrock AgentCore에서 에이전트를 실행하는 팀도 WhatsApp을 연결하려면 메시지 유형마다 구조가 다른 중첩 데이터를 인증하고, 에이전트가 읽을 수 있는 형식으로 바꿔야 한다. 음성 메모, 이미지, 문서는 처리 방식이 다르고, 대화가 끊긴 뒤에도 이력과 예약 알림을 유지해야 하며, 외부 시스템이 먼저 메시지를 보낼 때는 발송 요청을 인증해야 한다. AWS는 이 작업을 직접 구현하거나 외부 서비스에 맡기는 방법에 더해, 자체 AWS 계정에 SMART를 배포하는 선택지를 제시한다. AWS가 소개한 Webmotors 사례에서는 당초 2개월로 잡았던 작업을 6주 만에 마쳤으며, 당시 도달한 단계는 정식 출시 전 내부 팀을 대상으로 한 제한적 운영이었다.
2. SMART와 에이전트의 역할 분담
SMART는 오픈소스 Python SDK와 Terraform 스택을 함께 제공해 웹훅 수신, 양방향 미디어 처리, 메시지 템플릿 관리, 예약 발송 등 WhatsApp 채널에 공통으로 필요한 작업을 맡는다. 에이전트는 정리된 수신 메시지를 받아 텍스트를 반환하고, 필요하면 답변에 버튼이나 미디어 같은 요소를 덧붙인다. AgentCore runtime은 이 에이전트의 호스팅과 확장을 관리하고, 개발팀은 모델과 프레임워크, 비즈니스 로직을 선택한다. Strands Agents에서는 대화 기억이 자동으로 연결되며, 대화 처리 흐름을 직접 제어할 수 있는 LangGraph나 Pydantic-AI에서도 SDK가 제공하는 동일한 메모리·세션 연동 기능을 사용할 수 있다. 이 구조는 새 에이전트를 만드는 팀과 기존 에이전트에 WhatsApp을 추가하는 팀 모두에 적용된다.
3. 전화번호별 대화 기억과 응답 순서
SMART의 세션 관리 기능은 수신 메시지에 연결된 전화번호를 기준으로 에이전트를 AgentCore memory에 연결한다. 기본 보존 기간은 7일이며, 이 기간에는 사용자가 새 세션에서 대화를 시작하거나 개발팀이 에이전트를 재배포한 뒤에도 이전 대화 이력을 활용할 수 있다. 한 차례의 응답을 만드는 중에는 에이전트의 도구가 최종 답변에 앞서 버튼 목록이나 진행 상황을 사용자에게 보내려는 경우가 있다. AWS는 이 메시지를 즉시 발송하면 대화 이력의 순서가 어긋나 사용자의 다음 메시지 처리가 실패할 수 있다고 설명한다. SMART는 도구가 요청한 발송을 모아 두고 현재 응답 처리가 끝난 뒤 순서대로 전달하므로, 각 도구에 발송 시점을 조절하는 로직을 따로 넣을 필요가 없다.
4. 수신 메시지의 검증과 미디어 처리
AWS End User Messaging Social이 WhatsApp 메시지를 수신하면 Amazon SNS를 거쳐 웹훅을 담당하는 AWS Lambda 함수에 이벤트가 전달된다. 이 함수는 SNS 메시지의 서명을 검증하고 유형별 데이터를 일관된 형식으로 변환하며, 선택 사항인 Amazon DynamoDB 상태 테이블을 활성화한 경우 기본적으로 사용자당 분당 20건의 제한을 적용한다. 모델이 응답을 완성하기 전에는 읽음 확인과 입력 중 표시를 보내 사용자가 메시지 처리 여부를 알 수 있게 한다. 음성 메모는 Amazon Transcribe가 텍스트로 변환하고, 다른 미디어는 파일에 관한 설명 정보로 전달하거나 개발팀이 등록한 처리 함수에 넘긴다. 에이전트가 호출 제한에 걸리거나 실행에 실패하면 사용자에게 안내 문구가 전달되며, 개발팀은 이 문구를 바꿀 수 있다.
5. 안전 통제와 실행 추적
WhatsApp 에이전트는 최종 사용자에게 직접 답변하므로 AWS는 운영 환경에 적절한 보호 장치를 포함하도록 안내한다. SMART의 Terraform 스택은 Amazon Bedrock Guardrails 리소스를 기본으로 생성하고 연결하며, 배포팀은 환경 설정에서 기본 구성을 사용하거나 자체 가드레일을 지정하거나 이 기능을 끌 수 있다. 어떤 통제를 적용할지는 서비스 운영 조직이 결정한다. 메시지 처리가 끝나면 웹훅 함수가 AgentCore runtime에 요청을 전달하고, AgentCore Observability는 실행 단계를 추적해 디버깅과 감사를 지원한다. 스택은 자격 증명 관리에 AWS Secrets Manager를 사용하며, 모니터링에는 Amazon CloudWatch를, 미디어와 감사 기록 저장에는 Amazon S3를 사용한다.
6. 외부 이벤트와 24시간 이후의 발송
사용자 메시지에 답할 때는 웹훅 함수가 에이전트의 답변과 도구가 대기시킨 메시지를 보내고, 대화 차례 밖에서 먼저 연락하거나 예약된 알림을 보낼 때는 별도의 알림 함수가 발송을 맡는다. 외부 시스템의 요청은 API 키와 Lambda 인증 함수로 보호되는 Amazon API Gateway를 거치며, Amazon SNS에 이벤트가 게시되면 이벤트 처리 함수가 등록된 로직을 실행한다. 특정 시각에 보낼 알림이나 정기적으로 안부를 묻는 메시지의 일정은 Amazon EventBridge Scheduler가 관리한다. 발송 형식을 결정하는 기준은 사용자가 마지막으로 메시지를 보낸 시각이며, 그때로부터 24시간이 지난 뒤 보내는 메시지에는 Meta가 사전 승인한 템플릿을 써야 한다. SMART는 템플릿을 YAML로 선언하고 CLI로 동기화할 수 있게 하며, AWS End User Messaging을 통해 대화 가능 시간이 지난 뒤에도 승인된 형식의 알림을 보낼 수 있다.
7. 배포 범위와 사전 요건
SMART의 배포 명령은 내부적으로 Terraform을 실행해 AgentCore runtime과 메모리, 수신·알림·이벤트·예약용 Lambda 함수, 메시지 수신 주제, 이벤트 API, 저장소와 모니터링 리소스를 구성한다. 네 Lambda 함수는 Python 3.12에서 실행되며 각각 AWS X-Ray 추적과 처리 실패 메시지를 보관하는 대기열을 갖춘다. 에이전트 컨테이너 이미지와 Lambda 계층은 배포 중 AWS CodeBuild에서 빌드하므로 로컬 Docker는 필요하지 않다. 배포하려면 AWS End User Messaging Social에 WhatsApp Business Account를 연결하고 전화번호를 등록해야 하며, 사용할 AWS 리전에서 AgentCore runtime과 메모리를 이용할 수 있고 모델 접근도 활성화돼 있어야 한다. 예제의 기본 모델은 Amazon Bedrock의 Claude Haiku 5.5이며, 로컬 환경에는 Python 3.11 이상, Terraform 1.7 이상, uv와 AWS CLI가 필요하다. AWS는 예제 코드의 용도를 비운영 환경으로 한정하고, 운영 배포 전에는 보안·법무 팀과 조직의 보안·규제·규정 준수 요건을 검토하도록 안내한다.
8. 프로젝트 유형과 로컬 개발
SMART는 새 프로젝트의 출발점으로 세 가지 블루프린트를 제공한다. 기본값인 minimal은 입력을 되돌려 주는 단순한 에이전트로, 도구·스킬·메시지 템플릿 없이 시작해 필요한 기능을 직접 추가할 때 적합하다. personal-assistant는 Strands 기반의 범용 대화형 에이전트로, 대화 기억과 사용자별 상태, 일정 관리, 음성·이미지 등 여러 형식의 메시지를 처리하는 도구를 포함한다. appointment-scheduler는 사용자가 항목과 시간대를 고르면 예약을 확인하고 사용자별 상태에 저장한 뒤 알림을 보내는 흐름을 제공한다. 프로젝트를 생성하면 에이전트 로직 파일, 배포 설정, 경로별 처리 함수의 기본 파일과 런타임 코드가 마련되고, 뒤의 두 블루프린트에는 도구·스킬과 메시지 템플릿 파일도 포함된다. 개발팀은 인프라를 배포하기 전부터 CLI로 로컬에서 동작을 시험할 수 있다.
🧾 핵심 주장 / 시사점
- 같은 사용자에게 보내는 알림이라도 일정만으로 발송 형식이 정해지지는 않는다. 예약 시각이 사용자의 마지막 메시지로부터 24시간을 넘기는지가 Meta 승인 템플릿의 필요 여부를 결정한다.
- 도구 메시지를 잠시 모아 두는 이유는 대화 이력을 실제 발송 순서와 맞추기 위해서다. 이 순서가 다음 사용자 메시지를 정상적으로 처리하는 데 영향을 준다.
- Webmotors의 6주는 내부 팀의 제한적 운영에 도달한 개별 사례의 기간이다. 전체 서비스의 출시 일정이나 다른 팀의 예상 구축 기간을 이 수치에서 확정할 수는 없다.
✅ 액션 아이템
- 예정된 WhatsApp 알림 중 사용자의 마지막 메시지로부터 24시간이 지난 뒤 보낼 항목을 식별하고 Meta 사전 승인 템플릿을 준비한다.
- 사용자가 대화를 재개하는 시점을 고려해 AgentCore memory의 기본 7일 보존 기간이 서비스에 적합한지 검토한다.
- 운영 배포 전에 보안·법무 팀과 조직의 요구사항을 검토하고 Amazon Bedrock Guardrails에 적용할 통제를 정한다.
❓ 열린 질문
- 예약 알림 중 사용자의 마지막 메시지로부터 24시간이 지난 뒤 발송돼 Meta 사전 승인 템플릿이 필요한 것은 무엇인가?
- AgentCore memory의 기본 7일 보존 기간은 사용자가 이전 대화를 이어 가려는 시점까지 충분한가?
- Amazon Bedrock Guardrails의 기본 구성은 운영 배포에 필요한 조직의 보안 요구사항을 어느 범위까지 충족하는가?