AI 상담원과 인간 상담원 전환 시 컨텍스트가 초기화되는 문제를 해결하기 위해 Twilio Agent Connect, Conversation Memory, Twilio Flex를 연결하는 Python 기반 구현 튜토리얼이다. 음성·SMS로 시작한 AI 상담 세션이 인간 상담원으로 전환될 때 Conversation Intelligence V3가 자동 요약을 생성해 Flex 대시보드에 컨텍스트를 전달하는 엔드투엔드 구조를 단계별로 설명한다.
핵심 포인트- Conversation Memory에 Language 같은 커스텀 특성을 저장해 재방문 사용자의 선호 언어를 세션 간 유지한다
- Orchestrator의 "Group by profile"로 음성·SMS 여러 채널의 상호작용을 같은 사용자 프로필에 연결한다
- Conversation Intelligence V3가 "대화 종료"와 "대화 비활성화" 두 트리거에서 자동으로 요약을 생성한다
- create_studio_handoff_tool이 Flex Studio Flow SID로 라우팅해 인간 상담원이 전체 컨텍스트와 요약을 수신한다
- 에이전트 시스템 지시사항은 memory_response.profile.traits에서 읽은 특성을 반영해 동적으로 수정된다
상세 정리- 전제 스택: Python 3.10+, pip install twilio-agent-connect openai python-dotenv, Twilio Flex 인스턴스, OpenAI API 키, ngrok
- Flex 연결 설정: Conversations > Addresses에서 전화번호에 Auto-create conversation = Yes, Conversation Service = Flex Conversation Service, 통합 = No(동적 라우팅)
- Orchestrator 설정: "Group by profile" + Observations/Summaries 메모리 활성화, 음성 트래픽 자동 캡처는 비활성화
- Intelligence 규칙 2개: "대화 종료"와 "대화 비활성화로 이동" 트리거 각각 생성 후 "Enable Conversation Memory for this rule" 체크
- ngrok 설정: ngrok http 8000으로 생성된 URL을 TWILIO_VOICE_PUBLIC_DOMAIN에 등록, /twiml(음성 웹훅)과 /webhook(Orchestrator) 경로 업데이트
- Studio Flow: "Twilio Agent Connect - Human Handoff" 템플릿에서 send_to_flex 위젯에 Flex Workflow를 지정하고 Flow SID를 .env에 추가
- Memory 커스텀 특성: Memory Store Traits 탭에서 Language(String) 특성 추가 — 에이전트가 contact_traits.get("language")로 읽어 응답 언어를 전환
- Memory 갱신 API: client.memory.v1.profiles("mem_store_id", "mem_profile_id").patch({"traits": {"Contact": {"language": "spanish"}}}) 형태
- 핸드오프 판단: 에이전트가 "사용자가 인간과 통화 원함"을 감지하면 create_studio_handoff_tool 호출, Studio Flow를 통해 Flex 대시보드로 라우팅
- Flex 수신: Intelligence가 생성한 자동 요약과 대화 기록이 함께 전달돼 인간 상담원이 문맥 파악 없이 바로 응대 가능
- 컨텍스트 보존: 핸드오프 후에도 Conversation Memory 프로필이 유지돼 후속 AI 세션에서 이전 상호작용 맥락을 재사용
왜 읽나음성·SMS AI 상담 시스템에서 컨텍스트 손실 없이 AI에서 인간 상담원으로 전환하는 핸드오프 구조를 Python으로 직접 구현하려는 AI 상담/통신 개발자에게.
Twilio Engineering·
인프런 (인프랩)·
네이버 D2·
Vercel Blog·