나만의 AI 에이전트를 WhatsApp에 연결하기: 웹훅 엔드포인트로 모든 프레임워크(LangGraph, ADK, 커스텀) 연결

거의 모든 AI 에이전트를 다시 작성하지 않고 WhatsApp에 연결할 수 있습니다. LangGraph, Google ADK, CrewAI 또는 직접 작성한 코드로 만든 에이전트를 HTTPS 엔드포인트 뒤에서 실행한 다음, MonoChat에서 커스텀 제공업체로 AI 하네스를 추가하세요. 필요한 것은 엔드포인트 URL과 공유 시크릿입니다. 플로우에 AI 에이전트 노드를 놓고 WhatsApp 번호를 연결하면, 에이전트가 WhatsApp과 MonoChat이 연결하는 모든 채널에서 고객에게 답하고, 그 주변에 공유 인박스와 상담원 연결이 갖춰집니다.

이 가이드는 이미 에이전트가 있거나 작동 방식을 완전히 통제하고 싶은 팀을 위한 것입니다. 나만의 에이전트를 가져오는 것이 적합한 경우, 엔드포인트가 맡는 역할, MonoChat에서의 설정, 운영 환경에서 중요한 세부 사항을 다룹니다.

왜 나만의 에이전트를 가져올까요?

대부분의 고객 메시징 플랫폼에는 기본 제공 AI 에이전트가 하나 있습니다. 편리하지만 다음과 같은 경우에는 달라집니다.

• 이미 에이전트를 만들었습니다. 개발자들이 LangGraph 그래프나 ADK 멀티 에이전트 구성에 몇 달을 들였고 평가와 테스트도 마쳤습니다. 이를 벤더의 봇 빌더 안에서 다시 만들면 그 작업이 버려집니다.
• 자체 로직이 필요합니다. 가격 규칙, 자격 확인, 컴플라이언스 단계, 또는 내 코드만 접근할 수 있는 내부 시스템이 있습니다.
• 프레임워크를 직접 선택하고 싶습니다. 프레임워크는 빠르게 변합니다. 오늘은 LangGraph지만 내년에는 다른 것일 수 있습니다. 채널과 인박스는 그에 따라 바뀌지 않아야 합니다.
• 데이터가 내 쪽에 있어야 합니다. 일부 조직은 에이전트의 추론과 도구 호출을 자체 인프라에서 실행하기를 원합니다.

MonoChat의 Agent Harness는 이를 위해 만들어졌습니다. 나만의 에이전트 프레임워크를 가져오고, 그 주변의 채널, 인박스, 사람을 한곳에 유지하세요.

커스텀 하네스의 작동 방식

역할 분담이라고 생각하면 됩니다.

MonoChat은 대화 계층을 맡습니다.

• WhatsApp, Instagram, Messenger, TikTok, Telegram, 웹 채팅, SMS, 음성과의 공식 연결(MonoChat은 공식 Meta Business Partner입니다).
• AI 에이전트 노드를 통해 에이전트를 언제 호출할지 결정하는 플로우.
• 사람이 전체 기록과 함께 이어받을 수 있는 공유 팀 인박스.

내 엔드포인트는 에이전트를 맡습니다.

• MonoChat으로부터 대화를 수신합니다.
• 추론, 도구, 메모리 등 내 에이전트를 실행합니다.
• 에이전트의 답변을 반환합니다.

둘 사이에는 공유 시크릿이 있습니다. 양쪽이 알고 있는 값으로, 내 엔드포인트가 요청이 내 MonoChat 계정에서 온 것인지 확인할 수 있게 합니다. 엔드포인트가 구현해야 할 정확한 요청 및 응답 형식은 MonoChat이 정의하며, 아직 받지 못했다면 문의해 주세요. 개발자에게 공유해 드립니다.

엔드포인트가 해야 할 일

어떤 프레임워크를 사용하든 운영 환경에 적합한 에이전트 엔드포인트에는 몇 가지 역할이 있습니다.

모든 요청 검증

모든 호출에서 공유 시크릿을 확인하고 일치하지 않는 요청은 거부하세요. 시크릿은 코드가 아니라 시크릿 매니저나 환경 변수에 저장하고, 노출된 적이 있다면 교체하세요.

대화를 서로 분리

고객은 동시에 메시지를 보냅니다. 에이전트의 상태, 메모리, 작업 파일이 대화 하나에 한정되도록 해서 한 고객의 정보가 다른 고객의 답변에 새어 나가지 않게 하세요.

채팅에 맞는 길이로 답변

웹 앱용으로 만든 에이전트는 길고 서식이 많은 답변을 쓰는 경향이 있습니다. WhatsApp은 휴대폰으로 읽습니다. 에이전트가 한 번에 질문 하나씩 짧은 메시지로 답하게 하고, 답변에 복잡한 Markdown은 쓰지 않게 하세요.

조용히 실패하지 말고 분명히 실패

도구가 시간 초과되거나 모델 제공업체가 오류를 반환하면 미완성 답변 대신 명확한 실패를 반환하세요. 예측 가능한 실패라면 플로우가 대화를 사람에게 넘기는 등 올바르게 대응할 수 있습니다.

빠르게 응답

고객은 몇 초 안에 답변을 기대합니다. 가능한 한 오래 걸리는 작업은 답변 경로에서 빼고, 도구를 빠르거나 비동기로 만드세요.

MonoChat에서 단계별로

1. HTTPS 뒤에 에이전트 배포

LangGraph, ADK, CrewAI 또는 커스텀 에이전트를 HTTPS로 접근할 수 있는 자체 서버나 클라우드에 호스팅하세요. MonoChat의 요청 및 응답 형식과 공유 시크릿 확인을 구현합니다.

2. 커스텀 제공업체로 AI 하네스 추가

MonoChat에서 AI 하네스를 추가하고 커스텀을 선택한 다음 엔드포인트 URL과 공유 시크릿을 입력하세요. 하네스는 한 번만 추가하면 원하는 만큼 많은 플로우에서 사용할 수 있습니다.

3. 플로우에 AI 에이전트 노드 추가

들어오는 대화를 받는 플로우에 AI 에이전트 노드를 추가하고 커스텀 하네스를 선택하세요. 그 주변의 플로우는 인사, 언어나 주제별 라우팅, 영업시간, 사람으로 이어지는 경로처럼 플로우가 가장 잘하는 일에 쓰세요.

4. 실행당 예산 설정

각 AI 에이전트 노드는 실행당 예산 한도를 지원합니다. 자체 코드에서 이미 적용 중인 한도와 함께 안전망으로 사용하세요.

5. WhatsApp과 다른 채널 연결

WhatsApp Business 번호를 연결한 다음 사용 중인 다른 채널에 같은 플로우를 연결하세요. 채널마다 추가 연동 작업은 없습니다. 내 엔드포인트가 보는 것은 채널 API가 아니라 대화입니다.

6. 테스트 후 운영 시작

실제 고객 메시지를 플로우에 재생해 보세요. 도구 호출, 응답 시간, 어조, 상담원 연결을 확인합니다. 운영 첫 며칠은 트래픽을 면밀히 지켜본 다음, 에이전트가 할 수 있는 일의 범위를 넓히세요.

프레임워크별 참고

LangGraph. 노드와 엣지로 이루어진 그래프는 분류, 조회, 해결, 에스컬레이션으로 이어지는 지원 여정에 자연스럽게 맞습니다. 컴파일된 그래프를 작은 HTTP 서비스로 감싸고, 요청마다 대화의 상태를 불러와 최종 메시지를 반환하세요.

Google ADK. 조정자와 전문 서브 에이전트로 이루어진 ADK의 멀티 에이전트 트리는 지원, 영업, 결제 팀에 잘 대응합니다. 엔드포인트로 루트 에이전트를 노출하고 내부 라우팅은 ADK에 맡기세요.

CrewAI. 역할 기반 에이전트로 구성된 크루는 조사 후 답변처럼 인계가 분명한 작업에 적합합니다. 채팅에서는 크루를 작게 유지하세요. 에이전트가 하나 늘 때마다 지연이 늘어납니다.

직접 작성한 코드. 모델 API와 몇 개의 함수로 이루어진 단순한 루프만으로 충분한 경우가 많습니다. 모든 것을 직접 통제하고, MonoChat은 채널과 인박스를 제공합니다.

상담원 연결: 플로우에서 결정하세요

어떤 대화를 사람에게 넘기고 어느 팀이 받을지는 플로우에서 결정하고, 에이전트는 도울 수 없을 때 추측하지 않고 고객에게 솔직하게 말하도록 작성하세요. 그러면 플로우가 전체 기록과 함께 공유 인박스의 알맞은 팀에 대화를 넘깁니다. WhatsApp의 Business Messaging Policy도 자동 응답에 사람으로 연결되는 명확한 경로가 있기를 요구합니다.

에이전트는 비즈니스 범위 안에 두세요. 2026년 1월 15일부터 WhatsApp은 범용 AI 어시스턴트를 플랫폼에서 제외하며, 자사 고객을 응대하는 에이전트는 괜찮습니다. 이 규칙은 WhatsApp AI 챗봇 정책 가이드에서 설명합니다.

직접 만들지 말아야 할 때

커스텀 에이전트는 가장 유연한 옵션이지만 직접 유지 관리해야 하는 옵션이기도 합니다. 처음부터 시작한다면 기본 제공 옵션으로 호스팅할 것 없이 더 빨리 운영을 시작할 수 있습니다.

• MonoChat AI 모델로 실행하는 MonoChat 기본 제공 하네스.
• MonoChat 내부에서 실행되는 OpenAI Agents SDK(가이드).
• MonoChat의 에이전트 러너에서 실행되는 Claude Agent SDK 또는 Pi(Claude 가이드).
• 호스팅형 에이전트: 본인의 키를 사용하는 OpenAI Agents API 또는 Claude Managed Agents.

모든 옵션이 같은 AI 에이전트 노드를 사용하므로, 하나로 시작해 나중에 채널이나 상담원 연결을 건드리지 않고 나만의 에이전트로 옮길 수 있습니다. Agent Harness 페이지에서 비교해 보세요.