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

現場監督者が工事現場で資材不足に気づきます。写真を撮ってWhatsAppで調達エージェントに送り、音声で配送先住所を確認します。エージェントは写真を処理して不足品を特定し、その会話内ですべて完結する形で緊急発注を行います。エンタープライズのワークフローには、言葉だけでは伝えられないコンテキストが含まれることがよくあります。リクエストの解決に必要な情報は、破損品の写真や規約の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アカウントをインポートし、エージェントでインテグレーションを有効にして接続します。単一のエージェントを、これらすべてのトランスポートに同時にデプロイできます。

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

入力表現：ファイル参照型とインライン

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

ファイル参照型入力

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

インライン

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

この違いが重要な理由

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

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

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

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

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

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

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

セッション間でコンテキストを引き継ぐ

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

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

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

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

ファイルを次の会話へ引き継ぐ

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

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

以上がライフサイクル全体です。ファイルがセッションに入り、モデルがネイティブに処理し、構造化出力がwebhookを通じて外部へ渡され、永続化レイヤーが次回エージェントが把握する内容を決定します。

まとめ

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

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