ElevenAgentsでの画像・ドキュメント処理

現場監督者が工事現場で資材不足に気づきます。写真を撮ってWhatsAppで調達エージェントに送り、配送先住所を音声で確認します。エージェントは写真を処理し、不足しているものを特定して、1回の会話の中で緊急発注を行います。エンタープライズのワークフローには、言葉だけでは伝えられないコンテキストが含まれることがよくあります。リクエストの解決に必要な情報は、破損した品物の写真や規約のPDFとして入力される場合があります。それを直接エージェントに渡すことで、会話が短縮され、解決が速くなります。顧客が説明する代わりに見せられれば、エージェントはチャネルの切り替えを求めることなく、より迅速に問題を切り分けられます。 Rohlikは、欧州最大級のオンライン食品プラットフォームの一つです。電話、Web、アプリ、WhatsAppで6言語に対応するエージェントを運用し、顧客からの問い合わせの90%を自動で解決しています。マルチモーダル入力により、顧客が説明するのではなく見せる必要がある場面にも、同じ解決率を広げられます。ElevenAgentsでは、音声、WhatsApp、Web、モバイルをすでに処理している同一のエージェントで、ファイルも主要な入力として扱います。ファイルはネイティブメッセージとして基盤モデルに渡されるため、1つのエージェントが1つの会話スレッド内ですべての入力タイプを処理できます。 

この記事では、プラットフォームにおけるマルチモダリティの意味、顧客のデバイスからモデルのコンテキストへファイルが渡る仕組み、各チャネルでサポートされる機能、そして顧客が再び利用した際にセッションをまたいでコンテキストを引き継ぐ方法を解説します。

チャネルと入力 

ElevenAgentsは、企業がすでに顧客への連絡に使用しているチャネルを中心に構築されています。Web・モバイルアプリケーション、サポートプラットフォーム、電話、SMS、メール、WhatsAppなどです。エージェント設定（プロンプト、モデル、ツール、ナレッジベース、音声）は一度定義すれば、すべてのチャネルで共有されます。チャネルごとに異なるのは、トランスポート層と対応する入力タイプの2点です。Web・モバイルアプリケーションは、埋め込み可能なウィジェット、SDK、またはAgents WebSocket経由で接続します。電話での会話は、ネイティブTwilio、SIPトランキング、またはネイティブのWebSocketベースのインテグレーション経由で接続します。SMSはネイティブTwilioインテグレーション経由で接続します。WhatsAppは、WhatsApp Businessアカウントをインポートし、エージェントでインテグレーションを有効にして接続します。1つのエージェントを、これらすべてのトランスポートに同時にデプロイできます。

現在、ファイル入力（画像とPDF）はWeb、モバイル、WhatsAppでサポートされています。入力の処理はチャネルではなくタイプに基づきます。同じWhatsAppセッションで受信した写真とボイスメッセージも、モデルに届くまでにまったく異なるパイプラインで処理されます。チャネルや入力タイプにかかわらず、すべての入力は同じ前処理レイヤーに集約され、ネイティブコンテキストとしてモデルに渡される前に、2つの経路のいずれかをたどります。

入力表現：ファイルベースとインライン

入力タイプやチャネルにかかわらず、プラットフォームはモデルに渡す前に、すべての入力を2種類の内部表現のいずれかに正規化します。この分類によって、モデルのコンテキストウィンドウ内での入力のエンコード方法と、インテグレーション側で上流処理すべき内容が決まります。

ファイルベースの入力

画像とPDFは、テキスト要約ではなくネイティブのファイル参照としてモデルに渡されます。プラットフォームはファイルを保存し、file_idを割り当て、その識別子をユーザーのターンに紐付けます。画像またはドキュメントを処理できるモデルは、派生した表現ではなく生のファイルをコンテキストウィンドウ内で受け取ります。インテグレーションで必要なことはシンプルです。アップロードエンドポイントから返されるfile_idを取得し、メッセージペイロードに含めます。file_idなしでメッセージを送信すると、アップロードが成功していてもモデルはファイルを参照できません。ファイルストレージのスコープは会話単位です。つまり、セッションをまたいで保持する必要があるもの（ファイルそのもの、抽出したフィールド、構造化出力）は、インテグレーションで明示的に処理する必要があります。その方法はチャネルやユースケースによって異なります。

インライン

2つ目の表現はインラインで、それ以外のすべてを対象とします。音声とボイスメッセージは文字起こしされます。入力テキスト、文字起こしした音声、WhatsAppの位置情報ピン、連絡先カードはすべて、モデルが実行される前にトランスクリプト内でプレーンテキストに正規化されます。位置情報ピンは座標と任意の住所に、連絡先は名前と電話番号になります。これらはファイルとして保存されず、ファイル参照も生成されません。こうした入力はトランスクリプト内に直接保存されます。

この違いが重要な理由

この区分によって、インテグレーションで取り組むべき箇所が決まります。インライン経路では、会話中に対応する必要はありません。プラットフォームがこれらの入力をテキストに正規化し、トランスクリプトに直接保存します。一方、ファイルベース経路には固有のインテグレーション領域があります。モデルの実行前にファイル内容をテキストへ変換するのではなく、オーケストレーターが生のファイルをモデルのコンテキストウィンドウに直接渡します。モデルは派生したテキスト表現や説明ではなくファイルの構造を処理するため、失われてしまう空間的な関係、視覚的なレイアウト、ドキュメントの書式を維持できます。この違いを踏まえ、以降では実装方法を解説します。エージェントの設定、各チャネルでのファイルの流れ、セッションをまたぐコンテキストの引き継ぎについて説明します。

マルチモーダル入力の設定 

マルチモーダル入力を有効にするには、Web、モバイル、WhatsAppで共通のエージェント設定を使用します。その後のファイルのアップロード方法や取得方法は、チャネルによって異なります。

ファイル入力を有効にする

ファイル入力を機能させるには、エージェント設定で2つの設定が必要です。まず、エージェント作成時にAPI経由で、またはダッシュボードのconversation_config.conversation.file_input.enabledをTrueに設定します。ダッシュボードでは、Settings > Advanced Settings > File Inputから設定できます。次に、エージェントを画像とドキュメントに対応したモデルで構成する必要があります。基盤モデルが画像またはドキュメントのブロックを処理できなければ、フラグだけを設定しても機能しません。テスト前に両方を設定してください。

SDKとWebSocket

Webまたはモバイルでのファイル入力には、SDKまたは生のAgents WebSocket接続を基盤にしたカスタムチャットクライアントが必要です。フローは3つすべてで同一であり、順序は必須です。メッセージペイロードはアップロードで返された識別子を参照するため、メッセージを送信する前にファイルをアップロードする必要があります。

まずファイルをアップロードします：

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では、アップロードと参照の手順が1回の呼び出しに抽象化されており、ファイル識別子は内部で処理されます。メッセージ形式の詳細は、 multimodal_message仕様を参照してください。アプリケーションでアップロードを行うため、この時点でファイルはすでに手元にあります。現在の会話でのみ必要な場合は、アップロードして識別子を参照すれば十分です。セッションをまたいで保持する必要がある場合、最も簡単な方法はアップロード時にアプリケーションから保存することです。セッションをまたぐコンテキストのセクションで説明するpost-call webhook経由で、後から取得することもできます。

WhatsApp

WhatsAppでは、アプリケーションはアップロードに関与しません。顧客が画像、ドキュメント、ステッカーを送信すると、ファイルはまずMetaのインフラストラクチャに送られます。MetaはWhatsApp Business API webhookを通じてElevenLabsに通知し、ElevenLabsは接続済みのWhatsApp Businessアカウント認証情報を使用してサーバー間でファイルをダウンロードし、独自のコピーを保存します。そして、WebまたはSDKでのアップロードと同様に、そのファイルを会話に紐付けます。エージェントはこれをマルチモーダル入力として受け取り、トランスクリプトにはfile_inputイベントが記録されます。

アプリケーションはアップロードを一切処理しないため、ファイルを直接保持することもありません。Webやモバイルのように、アップロード時にファイルを取得する経路はありません。ファイルは、ElevenLabsが保存したコピーを指すpost-call webhook内のfile_urlを通じてシステムに届きます。MetaのメディアURLは取り込みにのみ使用され、外部に公開されることはありません。ダウンロードの時間制約を含む取得の仕組みは、セッションをまたぐコンテキストのセクションで説明します。

WhatsAppでは、顧客がチャットでファイルを送信します。ElevenLabsはMetaからファイルを取得、保存し、プラットフォーム側でfile_idを紐付けます。つまり、クライアント側でのアップロード手順はありません。Webやモバイルとは異なり、アプリケーションでPOST /v1/convai/conversations/{id}/filesを呼び出したり、WebSocket経由でmultimodal_messageを送信したりする必要はありません。ElevenLabsが配信、保存、エージェントのターンを処理します。

セッションをまたぐコンテキストの引き継ぎ

ElevenAgentsは各会話を個別に処理します。顧客が送信した内容も、エージェントが会話中に解決した内容も、次の会話に自動で引き継がれることはありません。エージェントは、完了した会話のすべてをpost-call webhook経由でシステムに渡しますが、会話をまたぐ記憶はElevenLabsの境界の外にあります。継続性を管理するのは、あなたです。

このアーキテクチャ上の境界を前提に、意図的に設計する価値があります。マルチモーダル入力が特に重要になる会話（顧客が破損品を撮影する、規約ドキュメントをアップロードする、位置情報を共有するなど）は、1回のセッションでは解決しないことがよくあります。壊れた部品の写真を送って折り返し電話を予約した顧客は、電話がかかってきたときにエージェントがその写真を覚えていることを期待します。明示的にコンテキストを管理しなければ、エージェントは毎回ゼロから始め、顧客は同じ説明を繰り返すことになります。この課題に対応するパターンは2つに分かれます。会話が終わると、post-call webhookからトランスクリプト、分析結果、定義した構造化データ収集フィールド、セッション中に渡されたファイルのURLが配信されます。バックエンドでは、電話番号、ユーザーID、アカウントキーなど、永続的な顧客識別子に対して関連情報を保存します。顧客が再び利用したとき、アプリケーションがセッション開始時に動的変数を通じて保存済みのコンテキストを挿入するため、エージェントは既知の情報をもとに会話を始められます。特にファイルベースの入力では、webhookペイロードのファイルURLがElevenLabsの保存済みコピーを指しており、会話終了後の唯一の取得経路です。プラットフォーム上のコピーのスコープはセッション単位のため、将来の会話や自社システムでファイルが必要なら、その有効期間が終了する前にwebhookペイロードからダウンロードする必要があります。対応の速さは、リファレンスドキュメントで説明している保持ポリシーによって異なります。webhookが状態を外に渡し、動的変数がそれを戻します。その間のすべてはシステム側の責任であり、顧客が再訪、エスカレーション、または解決途中からの再開を行うユースケースでは、そこに実際のインテグレーション作業があります。

コンテキストの挿入はチャネルによって異なる

挿入の仕組みはチャネルごとに異なりますが、基本パターンは共通しています。電話では、通話が接続される前にElevenLabsがサーバーを呼び出すため、エージェントが話し始める前に、電話番号から発信者を検索し、名前、注文ID、アカウントティアなどの動的変数を返せます。WhatsAppでは、受信メッセージごとにpre-message webhookが実行され、エージェントが処理する前に、自社システムからのID情報やビジネスコンテキストでメッセージを拡張できます。それ以外の場合は、セッション開始時に同じフィールドを conversation_initiation_client_dataで渡します。ElevenAgentsは、複数チャネルのセッションを1つのスレッドに統合しません。同じ顧客に関するものであっても、WhatsAppでの会話とWebでの会話は別々のセッションです。ただし、webhook出力と動的変数の挿入はすべてのチャネルで同じように機能するため、1つの永続化レイヤーですべてを処理できます。一度構築すれば、エージェントが稼働するすべてのチャネルをカバーできます。コンテキストの挿入で扱うのは、名前、注文ID、要約、構造化フィールドなどのテキスト形式のデータです。ファイルは別ケースであり、異なるアプローチが必要です。

ファイルを引き継ぐ

ファイルのスコープは1つの会話に限定され、自動的には保持されません。次の会話に引き継ぐべきものは、ファイルから得られる情報が必要なのか、ファイル自体が必要なのかによって決まります。ほとんどの場合に必要なのは情報だけです。エージェントはアップロードされたファイルを受信したターンで解釈しますが、その解釈を永続的な場所に自動で書き込むことはありません。構造化出力はpost-callデータ、つまりトランスクリプト、トランスクリプトの要約、定義したデータ収集結果フィールドから取得します。顧客がひび割れたドアシールの写真を送信し、1週間後に請求について確認するため再び利用した場合、エージェントに再び写真は必要ありません。必要なのは、請求がひび割れたドアシールに関するものだと知ることです。post-callデータからそれを抽出し、顧客識別子に対して保存して、再訪時に動的変数として挿入します。通常は短い要約または数個の構造化フィールドで十分です。

自社の記録、コンプライアンス、またはダウンストリームシステムのために元のファイルが必要な場合、取得経路はpost-call webhookです。アップロードされた各ファイルは、署名付きファイルURLを持つfile_inputイベントとしてトランスクリプトに表示されます。このURLは15分間有効です。そのため、後回しにせずwebhookが届いた時点でファイルをダウンロードして保存してください。会話がまだ存在している間にこの期限を逃した場合は、フォールバックとしてGET conversation APIから新しいURLを再発行できます。ファイルベースのすべてのターンにURLが含まれると想定するのではなく、ゼロ保持モードなど、一部のケースではfile_inputがない可能性を考慮してください。

以上がライフサイクル全体です。ファイルがセッションに入り、モデルがネイティブに処理し、構造化出力がwebhook経由で出ていき、次回エージェントが何を知っているかは永続化レイヤーが決定します。

まとめ

同じエージェント設定で、チャネルごとに別途構築することなく、Web、モバイル、WhatsAppで画像とPDFを受け付けられます。ファイルは正規化され、ターンに紐付けられ、テキスト要約ではなくネイティブブロックとしてモデルに渡されます。そのため、空間的なレイアウト、視覚的構造、ドキュメントの書式はそのままモデルに届きます。セッションをまたぐコンテキストは、すべてのチャネルで同じパターンに従います。post-call webhookが状態を外に渡し、動的変数がそれを戻します。

ElevenLabs Agentsで構築しており、音声やテキストに加えて画像やドキュメントもエージェントで扱いたい場合は、マルチモーダル入力を有効にして、ぜひご意見をお聞かせください。