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つの設定が必要です。まず、conversation_config.conversation.file_input.enabledをTrueに設定します（エージェント作成時のAPIまたは設定＞詳細設定＞ファイル入力で設定可能）。次に、エージェントにビジョン・ドキュメント対応モデルを設定してください。フラグだけでは、モデルが画像やドキュメントブロックを処理できない場合は効果がありません。両方の設定が必要です。

SDKとWebSocket

Webやモバイルでファイル入力を使うには、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ではアップロードと参照の手順を1回の呼び出しで抽象化し、ファイル識別子を内部で処理します。詳細なメッセージ形式はmultimodal_message仕様をご覧ください。アプリケーション側でアップロードを行うため、その時点でファイルは手元にあります。会話中のみ必要な場合は、アップロードして識別子を参照するだけで十分です。セッションを超えて保持したい場合は、アップロード時にアプリケーション側で保存するのが最も簡単です。また、セッションをまたぐコンテキストの項目で解説するポストコールWebhook経由でも取得できます。

WhatsApp

WhatsAppでは、アップロードにアプリケーション側の操作は不要です。お客様が画像・ドキュメント・ステッカーを送信すると、ファイルはまずMetaのインフラに届きます。MetaがWhatsApp Business APIのWebhookでElevenLabsに通知し、ElevenLabsは連携済みのWhatsApp Businessアカウントの認証情報を使ってサーバー間でファイルをダウンロードし、自社で保存、WebやSDKアップロードと同じ方法で会話に紐付けます。エージェントはこれをマルチモーダル入力として受け取り、トランスクリプトにはfile_inputイベントが記録されます。

アプリケーション側でアップロード処理をしないため、ファイルを直接保持することはありません。Webやモバイルのようにアップロード時に取得する方法はありません。ファイルはポストコールWebhookのfile_url経由でシステムに届きます。これはElevenLabsが保存したコピーへの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が発火し、システムから本人情報やビジネスコンテキストを付与できます。それ以外は、セッション開始時にconversation_initiation_client_dataで同じフィールドを渡します。ElevenAgentsはチャネルをまたいでセッションを統合しません。WhatsAppとWebの会話は、同じお客様でも別セッションです。ただし、Webhook出力と動的変数注入はすべてのチャネルで同じ仕組みなので、1つの永続化レイヤーで全チャネルをカバーできます。一度構築すれば、エージェントが稼働するすべてのチャネルで利用可能です。コンテキスト注入は名前や注文ID、要約、構造化フィールドなどテキスト型データに対応します。ファイルは別途対応が必要です。

ファイルの引き継ぎ

ファイルは1つの会話単位で管理され、自動で引き継がれません。次回の会話でファイルの情報が必要か、ファイル自体が必要かによって対応が異なります。多くの場合、必要なのは情報だけです。エージェントはアップロードされたファイルをそのターンで解釈しますが、その解釈結果を自動で永続化することはありません。構造化出力はポストコールデータ（トランスクリプト、要約、定義したデータ収集フィールド）から得られます。例えば、お客様が割れたドアシールの写真を送り、1週間後に保険請求の続きで再度連絡した場合、エージェントが必要なのは「割れたドアシールの請求」であることです。これをポストコールデータから抽出し、顧客識別子に紐付けて保存し、再来時に動的変数として注入すれば十分です。短い要約やいくつかの構造化フィールドで対応できます。

原本ファイルが必要な場合（記録・コンプライアンス・他システム連携など）は、ポストコールWebhookが取得経路です。アップロードされたファイルはすべてトランスクリプト内にfile_inputイベントとして記録され、署名付きファイルURLが付与されます。このURLは15分間有効なので、Webhook受信時にダウンロード・保存してください。ウィンドウを逃した場合でも会話が残っていれば、GET conversation APIで新しいURLを再発行できます。file_inputがゼロリテンションモードなどで存在しない場合もあるため、すべてのファイル参照型ターンにURLがあると仮定しないでください。

これでファイルのライフサイクル全体をカバーできます。ファイルがセッションに入り、モデルがネイティブに処理し、構造化出力がWebhookで外部に渡り、永続化レイヤーが次回エージェントの知識を決めます。

まとめ

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

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