ElevenAgents에서 이미지 및 문서 처리하기

현장 감독자가 작업 현장에서 자재 부족을 발견합니다. 그는 사진을 찍어 WhatsApp의 구매 담당 에이전트에게 전송하고, 음성으로 배송 주소를 확인합니다. 에이전트는 사진을 처리해 누락된 항목을 파악하고, 긴급 주문까지 한 번의 대화로 처리합니다. 엔터프라이즈 워크플로우에서는 말로만 전달할 수 없는 컨텍스트가 자주 오갑니다. 요청을 해결하는 데 필요한 정보가 손상된 물품의 사진이나 정책 PDF로 입력될 수 있습니다. 이를 에이전트에게 직접 전달하면 대화가 간결해지고, 해결 속도가 빨라집니다. 고객이 설명 대신 보여줄 수 있으면, 에이전트는 채널을 전환하라는 요청 없이 더 빠르게 문제를 파악할 수 있습니다.Rohlik은(는) 유럽 최대 온라인 식료품 플랫폼 중 하나로, 전화, 웹, 앱, WhatsApp 등 6개 언어로 에이전트를 운영하며 고객 문의의 90%를 자동으로 해결합니다. 멀티모달 입력은 고객이 설명이 아닌 '보여줘야' 하는 순간에도 동일한 해결률을 제공합니다. ElevenAgents는 파일을 음성, WhatsApp, 웹, 모바일을 이미 처리하는 동일한 에이전트에서 1급 입력으로 다룹니다. 파일은 네이티브 메시지로 모델에 도달하므로, 하나의 에이전트가 모든 입력 유형을 한 대화 스레드 내에서 처리할 수 있습니다.

이 글에서는 플랫폼에서 멀티모달리티가 의미하는 바, 파일이 고객 기기에서 모델 컨텍스트로 이동하는 과정, 각 채널이 지원하는 기능, 고객이 다시 돌아왔을 때 세션 간 컨텍스트를 어떻게 이어갈 수 있는지 다룹니다.

채널 및 입력

ElevenAgents는 기업이 이미 고객과 소통하는 채널(웹 및 모바일 앱, 지원 플랫폼, 전화, SMS, 이메일, WhatsApp 등)을 중심으로 구축되었습니다. 에이전트 설정(프롬프트, 모델, 도구, 지식 베이스, 음성)은 한 번 정의하면 모든 채널에서 공유됩니다. 채널마다 다른 점은 두 가지입니다: 전송 계층과 지원하는 입력 유형입니다. 웹 및 모바일 앱은 임베디드 위젯, SDK 중 하나, 또는 Agents WebSocket을 통해 연결됩니다. 전화 통화는 네이티브 Twilio, SIP 트렁킹 또는 네이티브 WebSocket 기반 통합을 통해 연결됩니다. SMS는 네이티브 Twilio 통합을 사용합니다. WhatsApp은 WhatsApp Business 계정을 가져와 에이전트에서 통합을 활성화하면 연결됩니다. 하나의 에이전트가 이 모든 전송 방식에 동시에 배포될 수 있습니다.

파일 입력(이미지 및 PDF)은 현재 웹, 모바일, WhatsApp에서 지원됩니다. 입력 처리는 채널이 아니라 유형 중심으로 이루어집니다. 즉, 동일한 WhatsApp 세션에서 사진과 음성 메모가 도착하면, 각각 완전히 다른 파이프라인을 거쳐 모델에 도달합니다. 채널이나 입력 유형에 상관없이 모든 입력은 모델에 네이티브 컨텍스트로 전달되기 전 동일한 전처리 계층에서 합쳐지며, 이후 두 가지 경로 중 하나를 따릅니다.

입력 표현 방식: 파일 기반 vs. 인라인

입력 유형이나 채널에 상관없이, 플랫폼은 모든 입력을 모델에 전달하기 전에 두 가지 내부 표현 중 하나로 정규화합니다. 이 분류에 따라 입력이 모델의 컨텍스트 윈도우에 어떻게 인코딩되는지, 그리고 통합에서 어떤 처리가 필요한지가 결정됩니다.

파일 기반 입력

이미지와 PDF는 텍스트 요약이 아닌 네이티브 파일 참조로 모델에 전달됩니다. 플랫폼은 파일을 저장하고, file_id를 할당한 뒤, 해당 식별자를 사용자의 턴에 연결합니다. 비전 또는 문서 처리 모델은 파생된 표현이 아닌 원본 파일을 컨텍스트 윈도우에서 받습니다. 통합 요구사항은 간단합니다: 업로드 엔드포인트에서 반환된 file_id를 캡처해 메시지 페이로드에 포함하면 됩니다. 메시지를 file_id 없이 보내면, 업로드가 성공했더라도 모델은 파일을 참조할 수 없습니다. 파일 저장은 대화에 한정됩니다. 즉, 세션 이후에도 파일 자체, 추출된 필드, 구조화된 출력 등이 필요하다면 통합에서 별도로 처리해야 합니다. 이 방식은 채널과 사용 사례에 따라 다릅니다.

인라인

두 번째 표현 방식은 인라인이며, 나머지 모든 입력에 해당합니다. 음성 및 음성 메모는 전사됩니다. 입력된 텍스트, 전사된 음성, WhatsApp 위치 핀, 연락처 카드는 모두 모델 실행 전 트랜스크립트에서 일반 텍스트로 정규화됩니다. 위치 핀은 좌표와 선택적 주소로, 연락처는 이름과 전화번호로 변환됩니다. 이들은 파일로 저장되거나 파일 참조를 생성하지 않습니다. 이러한 입력은 트랜스크립트에 직접 기록됩니다.

구분이 중요한 이유

이 구분에 따라 통합 작업의 방향이 달라집니다. 인라인 경로는 대화 중 별도의 작업이 필요 없습니다. 플랫폼이 입력을 텍스트로 정규화해 트랜스크립트에 바로 기록합니다. 파일 기반 경로는 별도의 통합 처리가 필요합니다. 파일 내용을 모델 실행 전 텍스트로 변환하는 대신, 오케스트레이터가 원본 파일을 모델의 컨텍스트 윈도우에 직접 전달합니다. 모델은 파생된 텍스트 표현이 아닌 파일의 구조 자체를 처리하므로, 공간적 관계, 시각적 레이아웃, 문서 포맷 등이 그대로 보존됩니다. 이 구분을 이해했다면, 이후 내용에서는 에이전트 설정 방법, 파일이 각 채널을 통해 이동하는 과정, 세션 간 컨텍스트를 이어가는 방법을 다룹니다.

멀티모달 입력 설정하기

멀티모달 입력 활성화는 웹, 모바일, WhatsApp에서 동일한 에이전트 설정으로 시작합니다. 이후 파일 업로드 및 이후 파일을 가져오는 방식은 채널에 따라 달라집니다.

파일 입력 활성화

파일 입력이 동작하려면 에이전트 설정에서 두 가지 항목이 필요합니다. 첫째, conversation_config.conversation.file_input.enabled를 True로 설정해야 합니다(API로 에이전트 생성 시 또는 설정 > 고급 설정 > 파일 입력에서 설정 가능). 둘째, 에이전트에 비전 및 문서 처리 모델이 설정되어야 합니다. 플래그만 켜져 있고 모델이 이미지나 문서 블록을 처리하지 못하면 동작하지 않으니, 두 가지 모두 설정 후 테스트해야 합니다.

SDK 및 WebSocket

웹 또는 모바일에서 파일 입력을 사용하려면 SDK 기반의 커스텀 채팅 클라이언트나 원시 Agents WebSocket 연결이 필요합니다. 세 방식 모두 흐름은 동일하며, 순서가 매우 중요합니다. 파일은 메시지 전송 전에 업로드되어야 하며, 메시지 페이로드는 업로드에서 반환된 식별자를 참조합니다.

먼저 파일을 업로드하세요:

from elevenlabs import ElevenLabs

client = ElevenLabs(api_key="YOUR_API_KEY")

response = client.conversational_ai.conversations.files.create(
    conversation_id="your_conversation_id",
    file=open("example_file.jpg", "rb"),
)

file_id = response.file_id  

전체 요청 및 응답 예시는 파일 업로드에서 확인할 수 있습니다:

그 다음, 반환된 file_id를 참조하는 메시지를 연결을 통해 전송합니다:

{ 
	"type": "multimodal_message",
	"text": { 
		"type": "user_message", 
		"text": "What does this show?" 
	 },
	"file": { 
		"type": "file_input", 
		"file_id": "<file_id>" 
 	}
}

SDK는 업로드와 참조 단계를 하나의 호출로 추상화하여 파일 식별자를 내부적으로 처리합니다. 전체 메시지 포맷은 multimodal_message 사양에서 확인하세요. 업로드를 애플리케이션에서 직접 수행하므로, 이 시점에 이미 파일을 보유하고 있습니다. 현재 대화에서만 필요하다면 업로드 후 식별자만 참조하면 충분합니다. 세션 이후에도 파일이 필요하다면, 업로드 시 애플리케이션에서 저장하는 것이 가장 깔끔합니다. 이후에는 세션 간 컨텍스트 섹션에서 다루는 post-call webhook을 통해서도 파일을 가져올 수 있습니다.

WhatsApp

WhatsApp에서는 애플리케이션이 업로드 과정에 관여하지 않습니다. 고객이 이미지, 문서, 스티커를 보내면 파일은 먼저 Meta 인프라로 전송됩니다. Meta가 WhatsApp Business API webhook을 통해 ElevenLabs에 알리면, ElevenLabs는 연결된 WhatsApp Business 계정 자격 증명으로 서버 간 파일을 다운로드하고, 자체 사본을 저장한 뒤 웹 또는 SDK 업로드와 동일하게 대화에 첨부합니다. 에이전트는 이를 멀티모달 입력으로 받고, 트랜스크립트에는 file_input 이벤트가 기록됩니다.

애플리케이션이 업로드를 직접 처리하지 않으므로, 파일을 직접 보유하지 않습니다. 웹 및 모바일처럼 업로드 시점에 파일을 캡처할 수 있는 경로가 없습니다. 파일은 post-call webhook의 file_url을 통해 시스템에 도달하며, 이는 ElevenLabs가 저장한 사본을 가리킵니다. Meta의 미디어 URL은 수집에만 사용되고 외부에 노출되지 않습니다. 다운로드 시점 등 파일 가져오기 방식은 세션 간 컨텍스트 섹션에서 다룹니다.

WhatsApp에서는 고객이 채팅에서 파일을 보냅니다. ElevenLabs가 Meta에서 파일을 받아 저장하고, 플랫폼 측에 file_id를 부여합니다. 즉, 클라이언트 측 업로드 단계가 없습니다. 웹 및 모바일과 달리, 애플리케이션이 POST /v1/convai/conversations/{id}/files를 호출하거나 WebSocket으로 multimodal_message를 전송하지 않습니다. ElevenLabs가 전달, 저장, 에이전트 턴을 모두 처리합니다.

세션 간 컨텍스트 이어가기

ElevenAgents는 각 대화를 독립적으로 처리합니다. 고객이 보낸 내용이나 에이전트가 대화 중 해결한 내용은 다음 대화로 자동으로 이어지지 않습니다. 에이전트는 완료된 대화의 모든 정보를 post-call webhook을 통해 시스템에 전달하지만, 여러 대화에 걸친 기억은 ElevenLabs 외부에 저장해야 합니다. 연속성 관리는 여러분의 몫입니다.

이러한 아키텍처 경계는 의도적으로 설계할 가치가 있습니다. 멀티모달 입력이 중요한 대화(고객이 손상된 물품을 사진으로 찍어 보내거나, 정책 문서를 업로드하거나, 위치를 공유하는 경우)는 한 번의 세션에서 해결되지 않는 경우가 많습니다. 예를 들어, 고객이 부품 사진을 보내고 콜백을 예약했다면, 다시 전화할 때 에이전트가 그 사진을 기억하길 기대합니다. 명시적인 컨텍스트 관리가 없으면 에이전트는 매번 처음부터 시작하고, 고객은 같은 말을 반복해야 합니다. 이를 해결하는 패턴은 두 단계로 나뉩니다. 대화가 끝나면 post-call webhook이 트랜스크립트, 분석 결과, 정의한 구조화 데이터 필드, 세션을 거친 파일의 URL을 전달합니다. 백엔드는 이를 전화번호, 사용자 ID, 계정 키 등 내구성 있는 고객 식별자에 저장합니다. 고객이 다시 돌아오면, 애플리케이션이 저장된 컨텍스트를 동적 변수로 세션 시작 시 주입해 에이전트가 이미 알고 있는 정보로 대화를 시작할 수 있습니다. 파일 기반 입력의 경우, webhook 페이로드의 파일 URL이 ElevenLabs 저장 사본을 가리키며, 대화 종료 후 파일을 가져올 수 있는 유일한 경로입니다. 플랫폼의 사본은 세션에 한정되므로, 이후 대화나 자체 시스템에서 파일이 필요하다면, 해당 창이 닫히기 전에 webhook 페이로드에서 다운로드해야 합니다. 얼마나 빨리 처리해야 하는지는 보존 정책에 따라 다르며, 자세한 내용은 레퍼런스 문서에서 확인할 수 있습니다. webhook이 상태를 외부로 전달하고, 동적 변수가 다시 주입합니다. 그 사이의 모든 과정은 여러분 시스템의 책임이며, 고객이 돌아오거나, 이슈가 심화되거나, 중간에 이어지는 모든 사용 사례에서 실제 통합 작업이 필요한 부분입니다.

컨텍스트 주입은 채널에 따라 다름

주입 방식은 채널마다 다르지만, 기본 패턴은 동일합니다. 전화의 경우, ElevenLabs가 통화 연결 전에 서버를 호출해 발신자 번호로 고객을 조회하고, 이름, 주문 ID, 계정 등급 등 동적 변수를 반환할 기회를 제공합니다. WhatsApp에서는 각 수신 메시지마다 프리-메시지 webhook이 실행되어, 에이전트가 처리하기 전에 시스템에서 신원 및 비즈니스 컨텍스트를 추가할 수 있습니다. 그 외에는 세션 시작 시 conversation_initiation_client_data 필드에 동일하게 전달됩니다. ElevenAgents는 채널 간 세션을 하나의 스레드로 합치지 않습니다. WhatsApp 대화와 웹 대화는 동일 고객이라도 별도 세션입니다. 하지만 webhook 출력과 동적 변수 주입 방식이 모든 채널에서 동일하게 동작하므로, 하나의 영속성 계층으로 모두 관리할 수 있습니다. 한 번 구축하면 에이전트가 동작하는 모든 채널을 커버할 수 있습니다. 컨텍스트 주입은 이름, 주문 ID, 요약, 구조화 필드 등 텍스트 형태의 데이터에 해당합니다. 파일은 별도의 접근이 필요합니다.

파일 이어가기

파일은 한 대화에 한정되며 자동으로 이어지지 않습니다. 다음 대화에서 파일의 정보가 필요한지, 파일 자체가 필요한지에 따라 이어갈 내용이 달라집니다. 대부분의 경우 정보만 필요합니다. 에이전트는 업로드된 파일을 도착한 턴에서 해석하지만, 그 해석 결과를 자동으로 영구 저장하지는 않습니다. 구조화된 출력은 post-call 데이터(트랜스크립트, 요약, 데이터 수집 결과 등)에서 얻을 수 있습니다. 예를 들어, 고객이 깨진 문 도어 실 사진을 보내고 일주일 뒤 클레임을 이어간다면, 에이전트는 사진 자체가 아니라 '클레임이 깨진 도어 실에 관한 것'임을 알면 충분합니다. post-call 데이터에서 해당 정보를 추출해 고객 식별자에 저장하고, 재방문 시 동적 변수로 주입하면 됩니다. 간단한 요약이나 몇 개의 구조화 필드면 충분한 경우가 많습니다.

원본 파일이 필요하다면(기록, 컴플라이언스, 후속 시스템 등), post-call webhook이 파일을 가져오는 경로입니다. 업로드된 각 파일은 트랜스크립트에 file_input 이벤트와 서명된 파일 URL로 기록됩니다. 이 URL은 15분간 유효하므로, webhook 도착 시 바로 다운로드해 저장해야 합니다. 해당 창을 놓쳤지만 대화가 아직 존재한다면, GET conversation API로 새 URL을 받을 수 있습니다. file_input이 없는 경우(예: 무보존 모드)도 있으니, 모든 파일 기반 턴에 URL이 있다고 가정하지 마세요.

이로써 전체 라이프사이클이 마무리됩니다: 파일이 세션에 들어오고, 모델이 네이티브로 처리하며, 구조화된 출력이 webhook을 통해 나가고, 영속성 계층이 다음에 에이전트가 알 정보를 결정합니다.

결론

동일한 에이전트 설정으로 웹, 모바일, WhatsApp에서 이미지와 PDF를 별도 빌드 없이 받을 수 있습니다. 파일은 정규화되어 턴에 연결되고, 텍스트 요약이 아닌 네이티브 블록으로 모델에 전달되어 공간 레이아웃, 시각적 구조, 문서 포맷이 그대로 모델에 도달합니다. 세션 간 컨텍스트도 모든 채널에서 동일한 패턴을 따릅니다: post-call webhook이 상태를 외부로 전달하고, 동적 변수가 다시 주입합니다.

ElevenLabs Agents로 구축 중이고, 에이전트가 음성 및 텍스트와 함께 이미지와 문서도 처리하길 원한다면 멀티모달 입력을 활성화하고, 의견을 들려주세요.