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

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

이 게시물에서는 플랫폼에서 멀티모달이 의미하는 바, 파일이 고객 기기에서 모델 컨텍스트로 이동하는 방식, 채널별 지원 기능, 그리고 고객이 다시 돌아왔을 때 세션 간 컨텍스트를 유지하는 방법을 다룹니다.

채널 및 입력 

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

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

입력 표현: 파일 기반과 인라인

입력 유형이나 채널과 관계없이 플랫폼은 모든 입력을 모델에 전달하기 전에 두 가지 내부 표현 중 하나로 정규화합니다. 이 분류에 따라 입력이 모델의 컨텍스트 윈도우에 인코딩되는 방식과 통합에서 업스트림으로 처리해야 할 항목이 결정됩니다.

파일 기반 입력

이미지와 PDF는 텍스트 요약이 아닌 네이티브 파일 참조로 모델에 전달됩니다. 플랫폼은 파일을 저장하고 file_id를 할당한 뒤, 그 식별자를 사용자 턴에 연결합니다. 비전 또는 문서 처리 기능을 갖춘 모델은 파생된 표현이 아닌 원본 파일을 컨텍스트 윈도우에서 받습니다. 통합 요구 사항은 간단합니다. 업로드 엔드포인트가 반환하는 file_id를 캡처하여 메시지 페이로드에 포함하세요. 메시지를 file_id 없이 전송하면 업로드 성공 여부와 관계없이 모델은 파일을 참조할 수 없습니다. 파일 스토리지는 대화 범위로 제한됩니다. 즉, 세션 이후에도 유지해야 하는 모든 항목(파일 자체, 추출된 필드 또는 구조화된 출력)은 통합에서 명시적으로 처리해야 합니다. 이를 수행하는 방식은 채널과 사용 사례에 따라 다릅니다.

인라인

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

이 구분이 중요한 이유

이 구분은 통합 작업이 어디에 필요한지를 결정합니다. 인라인 경로에서는 대화 중 별도로 할 일이 없습니다. 플랫폼이 이러한 입력을 텍스트로 정규화하고 트랜스크립트에 직접 저장하기 때문입니다. 파일 기반 경로에는 별도의 통합 지점이 있습니다. 오케스트레이터는 모델 실행 전에 파일 콘텐츠를 텍스트로 변환하는 대신 원본 파일을 모델의 컨텍스트 윈도우에 직접 전달합니다. 모델은 파생된 텍스트 표현이나 설명이 아니라 파일의 구조를 기반으로 작동하므로, 그렇지 않으면 손실될 공간적 관계, 시각적 레이아웃, 문서 서식을 보존합니다. 이 구분을 염두에 두고, 이후에는 에이전트 구성 방법, 파일이 채널별로 이동하는 방식, 세션 간 컨텍스트 유지 방법 등 구현을 살펴보겠습니다.

멀티모달 입력 설정 

멀티모달 입력 활성화는 웹, 모바일, WhatsApp에서 동일한 에이전트 구성으로 시작합니다. 그 이후 파일 업로드 방식과 사후 검색 방식은 채널에 따라 달라집니다.

파일 입력 활성화

파일 입력이 작동하려면 에이전트 구성에 두 가지 설정이 필요합니다. 먼저 conversation_config.conversation.file_input.enabled를 True로 설정하세요. 에이전트 생성 시 API를 통해 설정하거나 대시보드의 설정 > 고급 설정 > 파일 입력에서 설정할 수 있습니다. 둘째, 에이전트는 비전 및 문서 처리 기능을 갖춘 모델로 구성되어야 합니다. 기반 모델이 이미지 또는 문서 블록을 처리할 수 없다면 플래그만 설정해도 아무런 효과가 없습니다. 테스트 전에 두 가지 모두 설정해야 합니다.

SDK 및 WebSocket

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

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

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를 호출하거나 WebSocket을 통해 multimodal_message를 전송하지 않습니다. 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이 있다고 가정하지 말고, 보존 기간 0 모드 등의 경우에는 file_input이 없을 수 있음을 고려해 설계하세요.

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

결론

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

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