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

現場監督が工事現場で資材不足に気づきます。写真を撮ってWhatsAppで調達エージェントに送り、音声で配送先住所を確認します。エージェントは写真を処理し、不足しているものを特定して、すべて1回の会話で緊急発注を行います。企業のワークフローには、言葉だけでは伝えきれないコンテキストが日常的に含まれます。依頼を解決するために必要な情報は、破損品の写真や規約のPDFとして入力される場合があります。これを直接エージェントに渡すことで、会話を短縮し、解決までの時間を短くできます。顧客が説明する代わりに見せられれば、エージェントはチャネルの切り替えを求めることなく、より迅速に問題を切り分けられます。 Rohlikはヨーロッパ最大級のオンライン食料品プラットフォームの一つで、電話、Web、アプリ、WhatsAppにまたがり、6言語でエージェントを運用しています。顧客からの問い合わせの90％を自動で解決しています。マルチモーダル入力により、顧客が言葉で伝えるのではなく、見せる必要がある場面にも同じ解決率を広げられます。ElevenAgentsでは、音声、WhatsApp、Web、モバイルをすでに処理している同じエージェントに対し、ファイルを第一級の入力として扱います。ファイルはネイティブメッセージとして基盤モデルに渡されるため、単一のエージェントが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なしで送信された場合、アップロードが成功していても、モデルはファイルを参照できません。ファイルストレージのスコープは会話単位です。つまり、セッションを超えて保持する必要があるもの（ファイル自体、抽出したフィールド、構造化出力）は、インテグレーションで明示的に処理する必要があります。その方法はチャネルとユースケースによって異なります。

インライン

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

この違いが重要な理由

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

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

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

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

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

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仕様を参照してください。アプリケーションがアップロードを実行するため、この時点でファイルはすでに手元にあります。現在の会話でのみ必要な場合は、アップロードして識別子を参照すれば十分です。セッションを超えて保持する必要がある場合は、アップロード時にアプリケーションから保存するのが最も簡単です。セッション間のコンテキストのセクションで説明する、通話後Webhookから後で取得することもできます。

WhatsApp

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

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

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

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

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

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

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

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

ファイルを引き継ぐ

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

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

これでライフサイクル全体を説明しました。ファイルがセッションに入り、モデルがネイティブに処理し、構造化出力がWebhookを通じて出力され、次回エージェントが何を知っているかは永続化レイヤーが決定します。

まとめ

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

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