WhatsApp에서 Claude Agent SDK 에이전트를 실행하는 방법 (MonoChat 사용)

Claude Agent SDK는 Anthropic의 에이전트 하네스입니다. Claude Code를 구동하는 것과 같은 추론, 도구 사용, 자체 점검의 루프를 개발자가 자신의 에이전트를 만들 수 있도록 패키지로 제공한 것입니다. WhatsApp에서 실행하려면 그 주변에 세 가지가 더 필요합니다. WhatsApp Business Platform과의 연결, 에이전트에 비즈니스 도구를 제공하는 방법, 에이전트가 멈춰야 할 때 사람에게 안전하게 넘기는 경로입니다. MonoChat의 Agent Harness에서는 Claude Agent SDK를 AI 하네스로 추가하고, 플로우에 AI 에이전트 노드를 넣고, WhatsApp 번호를 연결한 뒤 테스트하면 됩니다. 운영할 서버는 없습니다.

이 가이드에서는 Claude Agent SDK가 고객 대화에 가져오는 것, MonoChat에서의 설정 방식, 고객이 메시지를 보내기 시작하기 전에 갖춰야 할 사항을 설명합니다.

Claude Agent SDK란 무엇이며 왜 고객 지원에 적합한가

오늘날 WhatsApp의 AI 대부분은 단일 모델 호출입니다. 메시지가 들어오면 모델이 답변을 쓰고 끝입니다. “영업시간이 어떻게 되나요?” 같은 질문에는 충분합니다. 하지만 “주문한 상품이 아직 안 왔는데 금요일에 여행을 가요” 같은 문의에서는 한계가 드러납니다.

하네스는 모델을 루프로 실행합니다. 모델이 다음에 할 일을 결정하면, 하네스가 그 단계(조회, 도구 호출, 파일 읽기)를 실행하고 결과를 다시 전달하며, 작업이 끝나거나 사람이 필요할 때까지 반복합니다. Claude Agent SDK는 Anthropic이 만든 그 루프입니다. Claude Code의 기반이며, 도구 사용, MCP 지원, 서브 에이전트, 긴 세션을 위한 컨텍스트 관리, 권한 제어 등 개발자가 의존하는 구성 요소를 제공합니다.

고객 메시징에서는 이 루프가 답변을 해결로 바꿔 줍니다.

• 약속하기 전에 확인합니다. 재고, 배송 상태, 예약 가능 시간, 환불 규정을 추측하지 않고 답하는 순간에 조회합니다.
• 여러 단계로 사례를 처리합니다. 주문을 찾고, 택배사를 확인하고, 소포가 멈춘 것을 파악하고, 교환을 제안하는 일을 한 번의 대화에서 처리합니다.
• 멈출 때를 압니다. 좋은 하네스는 할 수 있는 일의 한계에 닿으면 즉흥으로 대응하지 않고 사례를 사람에게 넘깁니다.

하네스와 단순 추론의 차이에 대한 배경은 에이전트 하네스란 무엇이며 WhatsApp 지원에 왜 필요한가에서 읽어 보세요.

MonoChat에서 Claude 에이전트를 사용하는 세 가지 방법

MonoChat은 Claude 기반 에이전트를 사용하는 세 가지 경로를 지원합니다. 셋 모두 같은 AI 에이전트 노드, 같은 채널, 같은 상담원 연결을 사용합니다.

옵션	실행 위치	필요한 것
Claude Agent SDK	MonoChat의 에이전트 러너, 각 실행은 격리된 Claude Code 방식의 에이전트 프로세스	추가로 필요 없음, MonoChat 게이트웨이를 통해 보유한 AI 모델 사용
Claude Managed Agents	Anthropic 클라우드	본인의 Anthropic API 키
커스텀(자체 Claude Agent SDK 서비스)	자체 서버	엔드포인트 URL과 공유 시크릿

대부분의 팀에는 첫 번째 옵션이 알맞은 시작입니다. 아무것도 배포하거나 유지 관리하지 않고 Claude Agent SDK 하네스를 사용할 수 있습니다. 이미 Anthropic의 호스팅형 에이전트로 개발하고 있어 그대로 유지하고 싶다면 Claude Managed Agents를 선택하세요. 개발자가 SDK로 자체 에이전트를 만들고 검증했으며 자체 인프라에서 계속 실행하려는 경우 커스텀을 선택하세요. 이 경로는 나만의 AI 에이전트를 WhatsApp에 연결하기 가이드에서 다룹니다.

단계별 안내: WhatsApp의 Claude Agent SDK 에이전트

1. AI 하네스 추가

MonoChat에서 AI 하네스는 한 번 추가해 재사용하는 서비스 정의입니다. 하나를 추가하고 제공업체로 Claude Agent SDK를 선택하세요. 제공업체 자체에 설정할 것은 더 없습니다. MonoChat의 에이전트 러너에서 실행되며 MonoChat 게이트웨이를 통해 보유한 AI 모델에 접근합니다.

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

들어오는 대화를 처리하는 플로우를 열거나 새로 만들고 AI 에이전트 노드를 추가하세요. 방금 만든 하네스를 선택합니다. 에이전트가 맡을 업무를 정하는 단계로, 누구를 응대하는지, 무엇을 할 수 있는지, 언제 상담원에게 넘겨야 하는지를 설명하는 지침을 작성하세요.

3. 메인, 폴백, 고속 모델 선택

각 AI 에이전트 노드에는 세 가지 모델 역할이 있습니다.

• 메인 모델: 추론하고, 판단하고, 답변을 작성합니다.
• 폴백 모델: 소프트 한도에 도달하거나 메인 모델이 실패하면 이어받아 고객이 계속 답변을 받을 수 있게 합니다.
• 고속 모델: 백그라운드 작업을 처리합니다.

실행당 예산 한도도 설정하세요. 고객 대화에 긴 단계의 연쇄가 필요한 경우는 드물며, 예산이 있으면 특이한 사례가 비싼 사례로 번지는 것을 막을 수 있습니다. 모델 조합을 고르는 방법은 고객 응대 에이전트에 폴백 모델이 필요한 이유 글에서 설명합니다.

4. 에이전트에 도구 제공

도구가 없는 에이전트는 말만 할 수 있습니다. MonoChat에서 에이전트는 다음을 사용할 수 있습니다.

• AI 함수 도구로 구조화된 입력을 사용해 API를 호출합니다. 예: “주문 상태 조회”, “반품 생성”.
• MCP 서버로 MCP를 지원하는 모든 시스템의 도구를 가져옵니다.
• AI 지식 베이스로 자체 정책과 문서에 근거한 답변을 제공합니다.
• 맞춤 함수로 대화 안에서 실행되는 비즈니스 로직을 처리합니다.

가장 흔한 요청을 다루는 도구 두세 개로 시작하세요. 도구를 추가할 때마다 에이전트가 할 수 있는 일이 하나 늘고, 테스트할 일도 하나 늘어납니다.

5. WhatsApp과 다른 채널 연결

아직 연결하지 않았다면 WhatsApp Business 번호를 MonoChat에 연결하세요(MonoChat은 공식 Meta Business Partner이며 공식 WhatsApp Business Platform을 사용합니다). 에이전트는 플로우 안에 있으므로, 아무것도 다시 만들지 않고 같은 플로우를 Instagram, Messenger, TikTok, Telegram, 웹 채팅, SMS, 음성에 연결할 수 있습니다.

6. 테스트 후 운영 시작

고객이 실제로 보내는 메시지를 에이전트에 보내 보세요. 짧은 문장, 오타, 여러 언어, 한 메시지에 담긴 세 가지 질문 등입니다. 올바른 도구를 사용하는지, 규칙을 지키는지, 적절한 시점에 상담원에게 넘기는지 확인한 다음 실제 트래픽에 플로우를 켜세요.

WhatsApp 에이전트용 지침 작성

Claude Agent SDK는 코딩 분야에서 성장했으며, 그곳에서는 길고 상세한 답변이 환영받습니다. WhatsApp은 정반대입니다. 몇 가지 규칙이 큰 차이를 만듭니다.

• 답변은 짧게. 메시지당 두세 문장, 한 번에 질문 하나. 고객은 휴대폰으로 읽습니다.
• 실행 전에 확인. 비용이 들거나 되돌릴 수 없는 일 전에는 “주문 4821을 취소하고 €39를 환불해 드릴 수 있습니다. 진행할까요?”라고 묻습니다.
• 상담원 연결 규칙을 명시. 예: “직원에 대한 불만, 법적 위협, €100를 초과하는 환불, 고객이 사람을 요청할 때는 상담원에게 연결합니다.”
• 비즈니스 범위 안에서. 2026년 1월 15일부터 WhatsApp 약관은 범용 AI 어시스턴트를 플랫폼에서 제외합니다. 자사 고객을 응대하는 에이전트는 괜찮지만, 아무 주제에나 에세이를 쓰는 에이전트는 안 됩니다. 이 규칙은 WhatsApp AI 챗봇 정책 가이드에서 설명합니다.
• 24시간 창 준수. 자유 형식 답변은 고객의 마지막 메시지 후 24시간 이내에 허용됩니다. 그 이후에는 승인된 템플릿이 필요합니다.

상담원 연결: 신뢰를 좌우하는 부분

고객은 “동료를 연결해 드리겠습니다”라고 말하는 에이전트는 용서하지만, 같은 말을 반복하는 에이전트는 용서하지 않습니다. MonoChat에서 에이전트는 고객이 물어본 내용, 에이전트가 조회한 내용, 이미 시도한 내용 등 전체 기록과 함께 공유 인박스의 팀에 대화를 넘깁니다. 이어받는 담당자가 고객에게 처음부터 다시 설명해 달라고 할 필요가 없습니다.

도구를 계획하기 전에 상담원 연결 규칙부터 계획하세요. 에이전트가 혼자 처리해서는 안 되는 사례, 이를 받을 사람, 기다리는 동안 에이전트가 고객에게 전할 말을 정하세요.

비용과 제어

에이전트를 쓰면 MonoChat 요금제 외에 두 가지 비용이 더 듭니다. AI 모델 사용료와 Meta의 WhatsApp 요금입니다. 2026년 10월 1일부터 Meta는 비즈니스 번호당 월 처음 1,000건 이후의 서비스 답변에 요금을 부과합니다. 자세한 내용은 WhatsApp API 요금 가이드를 참고하세요.

AI 측면에서는 자체 제공업체 키를 사용하면 MonoChat이 추가 요금을 붙이지 않습니다. 실행당 예산 한도, 알맞은 폴백 모델, 백그라운드 작업용 고속 모델이 있으면 발송량이 늘어도 사용량을 예측할 수 있습니다.

다른 하네스를 선택해야 할 때

Claude Agent SDK는 여러 단계를 거쳐 추론해야 하는 에이전트에 강력한 기본 선택입니다. 하지만 Agent Harness는 특정 방식에 묶이지 않도록 만들어졌습니다. 팀이 이미 OpenAI Agents SDK, Pi, 호스팅형 OpenAI 또는 Anthropic 에이전트, 자체 프레임워크로 작업하고 있다면 다른 AI 하네스를 추가해 AI 에이전트 노드를 전환할 수 있으며, 채널, 도구, 상담원 연결은 그대로 유지됩니다. 모든 옵션은 Agent Harness 페이지에서 확인하세요.