在 ElevenAgents 中处理图片和文档

一名现场主管发现工地材料短缺。他拍下照片，通过 WhatsApp 发给采购智能体，再用语音确认收货地址。智能体处理照片、识别缺少的材料并下紧急订单，全程只需一次对话。企业工作流程经常包含仅靠文字无法传达的上下文。解决请求所需的信息，可能是一张损坏物品的照片，或一份政策 PDF。直接将这些信息交给智能体，可以缩短对话并加快处理。当客户可以展示而非描述时，智能体无需让客户切换渠道，就能更快排查问题。 Rohlik是欧洲最大的线上杂货平台之一，其智能体覆盖电话、网页、应用和 WhatsApp，支持 6 种语言，并能自动解决 90% 的客户咨询。多模态输入将同样的解决率延伸到客户需要展示而非说明的场景。ElevenAgents 将文件作为一等输入，交由同一个已处理语音、WhatsApp、网页和移动端请求的智能体处理。文件会以原生消息形式传递给底层模型，因此单个智能体能在同一对话线程中处理所有输入类型。 

本文介绍多模态在平台中的含义、文件如何从客户设备进入模型上下文、各渠道支持哪些功能，以及客户再次联系时如何跨会话保留上下文。

渠道与输入 

ElevenAgents 围绕企业已有的触达客户渠道构建，包括网页和移动应用、支持平台、电话、SMS、电子邮件、WhatsApp 等。智能体配置（提示词、模型、工具、知识库和音色）只需定义一次，即可在所有渠道共享。不同渠道只有两项差异：传输层和支持的输入类型。网页和移动应用可通过嵌入式小组件、任一 SDK 或 Agents WebSocket 连接。电话对话可通过原生 Twilio、SIP 中继或基于原生 websocket 的集成连接。SMS 通过原生 Twilio 集成连接。导入 WhatsApp Business 账户并为智能体启用集成，即可连接 WhatsApp。单个智能体可同时部署到所有这些传输方式。

目前，网页、移动端和 WhatsApp 支持文件输入（图片和 PDF）。输入按类型而非渠道处理：同一 WhatsApp 会话中收到的照片和语音消息，在到达模型前会经过完全不同的处理管线。无论渠道或输入类型如何，所有输入都会先汇入同一预处理层，再以原生上下文传递给模型，并分为以下两种路径。

输入表示：文件支持型与内联型

无论输入类型或渠道如何，平台都会先将每项输入标准化为两种内部表示之一，再传递给模型。该分类决定输入如何编码到模型的上下文窗口，以及集成需要在上游处理什么。

文件支持型输入

图片和 PDF 会作为原生文件引用传递给模型，而非文本摘要。平台存储文件，并为其分配 file_id，再将该标识符绑定到用户轮次。具备视觉或文档处理能力的模型会在上下文窗口中接收原始文件，而非派生表示。集成要求很简单：获取上传端点返回的 file_id，并将其加入消息负载。如果发送消息时未包含 file_id，无论上传是否成功，模型都无法引用该文件。文件存储范围仅限于当前对话。这意味着任何需要在会话结束后保留的内容（文件本身、提取字段或结构化输出）都必须由集成显式处理。具体方式因渠道和用例而异

内联型

第二种表示是内联型，涵盖其他所有输入。语音和语音消息会被转写。在模型运行前，输入的文本、转写后的语音、WhatsApp 位置图钉和联系人卡片都会在转录中标准化为纯文本。位置图钉会变成坐标和可选地址；联系人会变成姓名和电话号码。它们不会作为文件存储，也不会生成文件引用。这些输入直接存在于转录中。

为何这一差异很重要

这种划分决定集成工作应投入在哪里。内联路径在对话期间无需进行任何处理：平台会将这些输入标准化为文本，并直接存入转录。文件支持型路径则有不同的集成接口。编排器不会在模型运行前将文件内容转换为文本，而是直接将原始文件传入模型的 上下文窗口。模型基于文件结构而非派生的文本表示或描述进行处理，从而保留原本会丢失的空间关系、视觉布局和文档格式。明确这一差异后，本文接下来将介绍具体实现：如何配置智能体、文件如何通过各渠道传递，以及如何跨会话保留上下文。

设置多模态输入 

在网页、移动端和 WhatsApp 上启用多模态输入，首先要使用相同的智能体配置。之后，文件如何上传及如何在后续获取，取决于所用渠道。

启用文件输入

文件输入要正常工作，智能体配置中必须设置两项内容。首先，将 conversation_config.conversation.file_input.enabled 设为 True，可在创建智能体时通过 API 设置，也可在控制台的 设置 > 高级设置 > 文件输入中设置。其次，必须为智能体配置支持视觉和文档的模型。如果底层模型无法处理图片或文档块，仅设置该标志不会生效；测试前必须同时完成这两项设置。

SDK 和 WebSocket

在网页或移动端使用文件输入，需要基于 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 会将上传和引用步骤封装为一次调用，在内部处理文件标识符。完整消息格式请参阅 multimodal_message规范。由于应用负责上传，此时已经持有文件。如果只需用于当前对话，上传文件并引用该标识符即可。如果需要在会话结束后保留文件，最简洁的做法是在上传时由应用存储。之后也可以通过通话后 webhook 获取，详见“跨会话保留上下文”部分。

WhatsApp

在 WhatsApp 上，应用不参与上传。客户发送图片、文档或贴纸时，文件会先进入 Meta 的基础设施。Meta 通过 WhatsApp Business API webhook 通知 ElevenLabs，ElevenLabs 使用已连接的 WhatsApp Business 账户凭据，以服务器到服务器的方式下载文件、存储副本，并像网页或 SDK 上传一样将其附加到对话中。智能体会将其作为多模态输入接收，转录中则会记录一条 file_input 事件。

由于应用从不处理上传，因此不会直接持有文件。与网页和移动端不同，没有在上传时捕获文件的途径。文件通过通话后 webhook 中的 file_url 进入系统，该 URL 指向 ElevenLabs 存储的副本。Meta 的媒体 URL 仅用于摄取，绝不会对外公开。获取机制（包括下载时限）详见“跨会话保留上下文”部分。

在 WhatsApp 上，客户会在聊天中发送文件。ElevenLabs 从 Meta 获取并存储文件，然后在平台端附加 file_id。这意味着没有客户端上传步骤。与网页和移动端不同，应用不会调用 POST /v1/convai/conversations/{id}/files，也不会通过 WebSocket 发送 multimodal_message。ElevenLabs 负责传递、存储和智能体轮次。

跨会话保留上下文

ElevenAgents 会独立处理每段对话。客户发送的内容，以及智能体在对话中处理的内容，都不会自动延续到下一次对话。智能体会通过通话后 webhook 将已完成对话的全部内容交给系统，但跨对话记忆存在于 ElevenLabs 的边界之外。连续性由你负责。

这一架构边界值得在设计时审慎考虑。多模态输入最重要的对话（例如客户拍摄损坏物品、上传政策文档或分享位置）通常无法在一次会话中解决。客户发送故障零件的照片并预约回电后，会希望智能体在回电时记得这张照片。如果没有显式的上下文管理，智能体每次都会从零开始，客户也得重复说明。解决这一问题的模式包含两部分。对话结束时，通话后 webhook 会提供转录、分析结果、定义的所有结构化数据收集字段，以及会话中所有文件的 URL。后端根据持久的客户标识符（如电话号码、用户 ID 或账户密钥）存储相关内容。客户再次联系时，应用会在会话开始时通过动态变量注入已存储的上下文，使智能体带着已有信息开始对话。对于文件支持型输入，webhook 负载中的文件 URL 指向 ElevenLabs 存储的副本，也是对话结束后唯一的获取路径。平台副本仅限于当前会话，因此如果未来对话或自身系统需要该文件，必须在该期限结束前从 webhook 负载中下载。需要多快行动取决于保留政策，具体请参阅参考文档。webhook 将状态传出，动态变量将其传回。两者之间均由系统负责，这也是在客户再次联系、升级问题或中途继续处理的用例中，真正需要进行集成工作的地方。

上下文注入取决于渠道

注入机制因渠道而异，但底层模式一致。对于电话，ElevenLabs 会在接通前调用服务器，让你有机会根据号码查找来电者，并在智能体开口前返回姓名、订单 ID 或账户等级等动态变量。在 WhatsApp 上，每条入站消息都会触发消息前 webhook，让你能在智能体处理前，利用系统中的身份和业务上下文来补充消息。否则，会在会话打开时通过 conversation_initiation_client_data传入相同字段。ElevenAgents 不会将跨渠道会话合并为单一线程。即使涉及同一客户，WhatsApp 对话和网页对话也是独立会话。但由于 webhook 输出和动态变量注入在所有渠道中的工作方式相同，单一持久化层即可处理所有渠道。只需构建一次，即可覆盖智能体运行的所有渠道。上下文注入处理文本形式的数据：姓名、订单 ID、摘要和结构化字段。文件属于另一种情况，需要采用不同方法。

延续文件信息

文件仅限于一段对话，不会自动保留。需要延续什么，取决于下一次对话需要文件中的信息，还是文件本身。大多数情况下，只需延续信息即可。智能体会在上传文件到达的轮次中解读它，但不会自动将该解读写入任何持久位置。结构化输出来自通话后数据：转录、转录摘要以及定义的任何数据收集结果字段。如果客户发送了一张开裂门封条的照片，并在一周后回来跟进索赔，智能体无需再次获取照片，只需知道该索赔涉及开裂的门封条。可以从通话后数据中提取这些信息，按客户标识符存储，并在客户再次联系时作为动态变量注入。通常，简短摘要或少量结构化字段就足够了。

如果确实需要原始文件，用于自身记录、合规或下游系统，通话后 webhook 就是获取路径。每个上传文件都会在转录中显示为带有已签名文件 URL 的 file_input 事件。该 URL 有效期为 15 分钟，因此应在收到 webhook 时下载并存储文件，不要延后处理。如果对话仍然存在但错过了这个期限，GET conversation API 会重新签发新的 URL 作为备用方案。应考虑到在某些情况下（如零保留模式），可能没有 file_input，而不要假定每个文件支持型轮次都会带有 URL。

这涵盖了完整生命周期：文件进入会话，模型原生处理文件，结构化输出通过 webhook 传出，持久化层决定智能体下次会掌握哪些信息。

结语

同一套智能体配置可在网页、移动端和 WhatsApp 上接收图片和 PDF，无需为每个渠道单独构建。文件会被标准化、绑定到相应轮次，并作为原生块而非文本摘要传给模型，因此空间布局、视觉结构和文档格式都能完整传达给模型。所有渠道的跨会话上下文都遵循相同模式：通话后 webhook 将状态传出，动态变量将其传回。

如果你正基于 ElevenLabs Agents 构建智能体，并希望它能结合图片和文档以及语音和文本工作，请启用多模态输入，并告诉我们你的想法。