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

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

이 글에서는 플랫폼에서 멀티모달이 무엇을 의미하는지, 파일이 고객 기기에서 모델의 컨텍스트로 어떻게 이동하는지, 각 채널이 무엇을 지원하는지, 고객이 다시 찾아올 때 세션 간 컨텍스트를 어떻게 이어가는지 살펴봅니다.

채널 및 입력 

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 사양에서 확인하세요. 애플리케이션에서 업로드를 수행하므로 이 시점에는 이미 파일을 보유하고 있습니다. 현재 대화에만 파일이 필요하다면 업로드하고 식별자를 참조하는 것으로 충분합니다. 세션 이후에도 파일을 유지해야 한다면 업로드 시점에 애플리케이션에서 저장하는 것이 가장 깔끔한 방법입니다. 세션 간 컨텍스트 섹션에서 다루는 통화 후 웹훅을 통해 나중에 가져올 수도 있습니다.

WhatsApp

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

애플리케이션은 업로드를 처리하지 않으므로 파일을 직접 보유하지 않습니다. 웹 및 모바일과 달리 업로드 시점에 파일을 캡처할 경로가 없습니다. 파일은 통화 후 웹훅의 file_url을 통해 시스템에 전달되며, 이는 ElevenLabs가 저장한 사본을 가리킵니다. Meta의 미디어 URL은 수집 목적으로만 사용되며 외부에 노출되지 않습니다. 다운로드 시간 제약을 포함한 검색 메커니즘은 세션 간 컨텍스트 섹션에서 다룹니다.

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

세션 간 컨텍스트 이어가기

ElevenAgents는 각 대화를 독립적으로 처리합니다. 고객이 보낸 내용이나 에이전트가 대화 중 해결한 내용은 다음 대화로 자동 전달되지 않습니다. 에이전트는 통화 후 웹훅을 통해 완료된 대화의 모든 정보를 시스템에 전달하지만, 대화 간 기억은 ElevenLabs의 경계 밖에 존재합니다. 연속성은 직접 관리해야 합니다.

이 아키텍처 경계는 의도적으로 설계할 가치가 있습니다. 멀티모달 입력이 가장 중요한 대화, 즉 고객이 파손된 물품을 촬영하거나 정책 문서를 업로드하거나 위치를 공유하는 대화는 한 세션에서 해결되지 않는 경우가 많습니다. 파손된 부품 사진을 보내고 콜백을 예약한 고객은 다시 전화했을 때 에이전트가 그 사진을 기억하기를 기대합니다. 명시적인 컨텍스트 관리가 없으면 에이전트는 매번 아무 정보 없이 시작하고 고객은 같은 내용을 반복해야 합니다. 이를 해결하는 패턴은 두 부분으로 구성됩니다. 대화가 끝나면 통화 후 웹훅이 트랜스크립트, 분석 결과, 정의한 구조화된 데이터 수집 필드, 세션을 거친 모든 파일의 URL을 전달합니다. 백엔드는 전화번호, 사용자 ID, 계정 키 같은 지속 가능한 고객 식별자를 기준으로 관련 정보를 저장합니다. 고객이 다시 찾아오면 애플리케이션은 세션 시작 시 동적 변수를 통해 저장된 컨텍스트를 주입하므로, 에이전트는 이미 알고 있는 정보를 바탕으로 대화를 시작합니다. 특히 파일 기반 입력의 경우 웹훅 페이로드의 파일 URL은 ElevenLabs가 저장한 사본을 가리키며, 대화가 종료된 후 유일한 검색 경로입니다. 플랫폼의 사본은 세션 범위로 제한되므로, 향후 대화나 자체 시스템에서 파일이 필요하다면 해당 기간이 끝나기 전에 웹훅 페이로드에서 다운로드해야 합니다. 얼마나 신속히 처리해야 하는지는 레퍼런스 문서에서 다루는 보존 정책에 따라 달라집니다. 웹훅은 상태를 외부로 전달하고, 동적 변수는 상태를 다시 가져옵니다. 그 사이의 모든 것은 시스템의 책임이며, 고객이 다시 찾아오거나 에스컬레이션하거나 해결 중간부터 이어가는 모든 사용 사례에서 실제 통합 작업이 이루어지는 지점입니다.

컨텍스트 주입은 채널에 따라 달라집니다

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

파일 이어가기

파일의 범위는 하나의 대화로 제한되며 자동으로 유지되지 않습니다. 다음 대화로 무엇을 가져갈지는 파일의 정보가 필요한지, 파일 자체가 필요한지에 따라 달라집니다. 대부분의 경우 필요한 것은 정보뿐입니다. 에이전트는 업로드된 파일이 도착한 턴에서 이를 해석하지만, 그 해석을 자동으로 지속 가능한 위치에 기록하지는 않습니다. 구조화된 출력은 통화 후 데이터, 즉 트랜스크립트, 트랜스크립트 요약, 정의한 데이터 수집 결과 필드에서 얻습니다. 고객이 금이 간 도어 실 사진을 보내고 일주일 뒤 보상 청구를 후속 처리하기 위해 다시 찾아오는 경우, 에이전트에 사진이 다시 필요하지는 않습니다. 청구가 금이 간 도어 실에 관한 것임을 알면 됩니다. 통화 후 데이터에서 해당 정보를 추출해 고객 식별자 기준으로 저장하고, 고객이 돌아오면 동적 변수로 주입합니다. 일반적으로 짧은 요약이나 몇 개의 구조화된 필드면 충분합니다.

자체 기록, 규정 준수 또는 다운스트림 시스템을 위해 원본 파일이 필요한 경우 통화 후 웹훅이 검색 경로입니다. 업로드된 각 파일은 트랜스크립트에 file_input 이벤트로 표시되며 서명된 파일 URL을 포함합니다. 이 URL은 15분 동안 유효하므로 나중으로 미루지 말고 웹훅이 도착할 때 파일을 다운로드하고 저장하세요. 대화가 아직 존재하는 동안 이 시간을 놓쳤다면 GET conversation API가 대체 수단으로 새 URL을 다시 발급합니다. 모든 파일 기반 턴에 URL이 포함된다고 가정하지 말고, file_input이 무보존 모드와 같은 일부 경우에는 없을 수 있다는 점을 고려해야 합니다.

이것으로 전체 수명 주기를 살펴봤습니다. 파일이 세션에 들어오고, 모델이 이를 네이티브로 처리하며, 구조화된 출력은 웹훅을 통해 나가고, 영속성 계층이 다음번에 에이전트가 알 내용을 결정합니다.

결론

동일한 에이전트 구성으로 채널별 별도 구축 없이 웹, 모바일, WhatsApp에서 이미지와 PDF를 받을 수 있습니다. 파일은 정규화되어 해당 턴에 연결되고 텍스트 요약이 아닌 네이티브 블록으로 모델에 전달되므로, 공간 레이아웃, 시각적 구조, 문서 서식이 온전히 모델에 전달됩니다. 세션 간 컨텍스트는 모든 채널에서 같은 패턴을 따릅니다. 통화 후 웹훅이 상태를 외부로 전달하고, 동적 변수가 이를 다시 가져옵니다.

ElevenLabs Agents를 기반으로 구축 중이며 음성 및 텍스트와 함께 이미지와 문서를 처리하는 에이전트를 만들고 싶다면, 멀티모달 입력을 활성화하고 의견을 들려주세요.