구축하게 될 내용: Google Gemini로 구동되는 AI 에이전트가 답변하는 WhatsApp 번호입니다. 여러분은 Gemini(Gemini CLI 또는 IDE의 Gemini Code Assist를 통해)를 페어 프로그래밍 코파일럿(copilot)으로 사용하여 코드를 스캐폴딩(scaffold), 디버깅(debug) 및 확장할 것이며, 따라서 Gemini는 에이전트의 런타임(runtime) 두뇌인 동시에 이를 구축하는 어시스턴트 역할을 수행하게 됩니다.

구성 요소 간의 결합 방식

WhatsApp 사용자
     │  메시지
     ▼
...

두 가지 구동 요소:

• WhatsApp Cloud API (Meta) — 웹훅(webhook)을 통해 들어오는 메시지를 수신하고 Graph API를 통해 답장을 보냅니다. 무료 티어(Free tier)를 사용할 수 있습니다.
• Gemini API (Google) — 에이전트의 응답을 생성합니다.

Gemini의 두 가지 역할: 런타임(runtime) 시에는 Gemini API가 WhatsApp 사용자에게 보낼 답장을 생성합니다. 구축(building) 시에는 Gemini를 코딩 코파일럿(copilot)으로 사용합니다. 터미널에서 Gemini CLI(npm install -g @google/gemini-cli 설치 후 gemini 실행)를 사용하거나, VS Code / JetBrains 내부에서 Gemini Code Assist를 사용하면 됩니다. 여러분이 원하는 내용을 평이한 영어로 설명하면, Gemini가 아래의 코드를 작성, 설명 및 수정합니다.

사전 요구 사항

• Python 3.10 이상
• Meta for Developers 계정 (무료)
• Gemini를 위한 Google AI Studio API 키 (무료 티어 사용 가능)
• 로컬 서버를 Meta의 웹훅(webhook)에 노출하기 위한 ngrok 또는 유사한 도구
• Gemini CLI 설치(npm install -g @google/gemini-cli) 또는 IDE에서 Gemini Code Assist 활성화 후 에디터와 함께 열어두기

1단계 — Gemini API 키 가져오기

1. aistudio.google.com으로 이동 → Get API key 클릭.
2. 키를 안전한 곳에 복사해 둡니다.

Gemini에게 질문하기: _"Gemini API 키가 무엇에 접근할 수 있는지, 그리고 환경 변수(environment variable)로서 어떻게 안전하게 저장할 수 있는지 설명해줘."

2단계 — WhatsApp Cloud API 설정

1. Meta for Developers에서 앱을 생성합니다. → 유형은 Business를 선택하세요.
2. WhatsApp 제품을 추가합니다. Meta는 **테스트 전화번호 (test phone number)**와 **임시 액세스 토큰 (temporary access token)**을 제공합니다.
3. WhatsApp → API 설정 (API Setup) 페이지에서 다음 세 가지 값을 기록해 두세요:
   • 전화번호 ID (Phone number ID)
   • 임시 액세스 토큰 (Temporary access token) (24시간 동안 유효하며, 나중에 영구적인 시스템 사용자 토큰 (System User token)으로 교체해야 합니다)
   • 앱 비밀 키 (App secret) (앱 설정 (App Settings) → 기본 (Basic) 섹션에 있음)
4. 테스트를 위해 본인의 전화번호를 **수신자 (recipient)**로 추가합니다.

Gemini에게 질문하기: _"Meta Business Suite에서 시스템 사용자 (System User)를 사용하여 영구적인 WhatsApp 액세스 토큰을 생성하는 과정을 단계별로 알려줘."

3단계 — 프로젝트 설정 (Project setup)

mkdir whatsapp-gemini-agent && cd whatsapp-gemini-agent
python -m venv .venv && source .venv/bin/activate
pip install flask google-genai requests python-dotenv

.env 파일을 생성합니다:

GEMINI_API_KEY=your_gemini_key
WHATSAPP_TOKEN=your_whatsapp_access_token
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
...

Gemini에게 질문하기: _"Python 프로젝트를 위한 .gitignore 파일을 생성해주고, .env 파일이 제외되도록 해줘."

4단계 — 웹훅 서버 (The webhook server)

Meta는 엔드포인트(endpoint)에 다음 두 가지를 요구합니다:

1. GET /webhook — 일회성 검증 핸드셰이크 (verification handshake).
2. POST /webhook — 수신 메시지가 도착하는 지점.

app.py를 생성합니다:

import os
import requests
from flask import Flask, request
...

Gemini에게 질문하기: _"이 파일을 붙여넣고 각 함수를 한 줄씩 설명해줘. 그리고 내가 놓치고 있는 에러 처리 (error handling) 방법을 제안해줘."

5단계 — 서버 노출 및 웹훅 연결

서버를 실행한 다음, 터널링(tunneling)을 수행합니다:

python app.py            # 터미널 1
ngrok http 5000          # 터미널 2  → https URL을 복사하세요

Meta의 WhatsApp → 설정 (Configuration) 섹션에서:

• 콜백 URL (Callback URL): https://<your-ngrok-id>.ngrok.io/webhook
• 검증 토큰 (Verify token): .env 파일에 설정한 것과 동일한 VERIFY_TOKEN
• Verify and save를 클릭합니다 (이 작업이 GET 핸드셰이크를 트리거합니다).

Gemini에게 질문하기: "내 웹훅 검증(webhook verification)이 403을 반환합니다. 여기 내 코드와 ngrok 로그가 있습니다 — 무엇이 잘못되었나요?"

Step 6 — 테스트하기

등록된 번호에서 테스트 번호로 WhatsApp 메시지를 보냅니다. 1~2초 이내에 Gemini가 생성한 답변을 받을 수 있어야 합니다.

만약 아무런 응답이 오지 않는다면, Claude에게 로그 읽는 것을 도와달라고 요청하세요:

Gemini에게 질문하기: "웹훅이 POST를 수신하지만 응답이 전송되지 않습니다. 여기 JSON 페이로드와 내 서버 로그가 있습니다 — 어디서 끊기는지 추적해 주세요."

Step 7 — 챗봇을 _에이전트(agent)_로 전환하기

챗봇은 답변을 합니다. **에이전트(agent)**는 행동을 취합니다. Gemini는 **함수 호출 (function calling)**을 지원합니다. 즉, 도구(tools)를 선언하면 모델이 이를 호출할 시점을 결정합니다.

예시: 에이전트에게 check_reservation 도구를 부여합니다.

def check_reservation(confirmation_code: str) -> dict:
    # 실제 조회 로직으로 교체하세요 (DB, 내부 API 등)
    return {"code": confirmation_code, "status": "confirmed", "checkin": "2026-08-14"}
...

Gemini SDK는 함수의 시그니처(signature)와 독스트링(docstring)을 읽어 도구 스키마(tool schema)를 구축하고, 사용자가 예약에 대해 물어볼 때 이를 호출하며, 그 결과를 답변에 포함시킵니다.

Gemini에게 질문하기: "예약을 취소하는 두 번째 도구를 추가하고, 에이전트가 동일한 채팅 내의 이전 메시지들을 기억할 수 있도록 대화 메모리(conversation memory)를 추가해 주세요."

Claude의 도움을 받아 구축하기 좋은 다음 도구들:

• 대화 메모리 (Conversation memory) — 전화번호별로 최근 대화 턴(turns)을 저장(dict, Redis 또는 DB)하고 이를 contents로 전달합니다.
• 상담원 연결 (Handoff to a human) — 사용자의 좌절감이나 특정 키워드를 감지하여 실제 상담원에게 알림을 보냅니다.
• 도메인 도구 (Domain tools) — 자체 데이터를 기반으로 한 예약, 주문 상태, FAQ 등입니다.

Step 8 — 프로덕션(production)에 배포하기 전

• 임시 WhatsApp 토큰을 **영구적인 시스템 사용자 토큰 (permanent System User token)**으로 교체하세요.
• 모든 POST 요청 시 App Secret을 사용하여 X-Hub-Signature-256 헤더를 검증하세요 — 서명되지 않은 모든 요청은 거부해야 합니다.
• 200 응답을 빠르게 반환하고, Gemini 호출은 **백그라운드 작업/큐 (background task/queue)**에서 처리하세요 (응답이 느리면 Meta가 재시도합니다).
• 속도 제한 (rate limiting) 및 **로깅 (logging)**을 추가하세요.
• ngrok에서 벗어나 실제 호스팅 환경(Cloud Run, Render, Fly.io, VM 등)으로 이동하세요.

Gemini에게 질문하기: "내 Flask 앱을 위한 X-Hub-Signature-256 검증 미들웨어를 작성해주고, 웹훅이 즉시 200을 반환할 수 있도록 Gemini 호출을 백그라운드 스레드에서 실행되도록 리팩터링해줘."

Gemini를 효과적으로 사용하는 방법

• 단순히 에러만 전달하지 말고 컨텍스트 (context)를 제공하세요. 코드와 로그/페이로드 (payload)를 함께 붙여넣으세요.
• 수정 사항뿐만 아니라 설명도 요구하세요. 이후에는 당신이 이 코드를 관리해야 합니다.
• 작은 단계로 반복하세요. 한 번에 하나의 도구, 하나의 기능, 하나의 버그씩 처리하세요.
• 배포하기 전에 보안 및 예외 케이스 (edge cases)에 대해 Gemini에게 리뷰를 요청하세요. Gemini CLI에서는 파일을 직접 지정할 수 있습니다 (gemini "review app.py for security issues").

빠른 참조 (Quick reference)

모델 참고: gemini-2.5-flash는 채팅용으로 빠르고 저렴하며, 더 어려운 추론이 필요한 경우 gemini-2.5-pro로 전환하세요. 최신 ID는 Google의 모델 목록을 확인하세요.