多模态输入与输出 (Multimodality)

当模型支持多模态输入与工具执行结果时，在 Deep Agents 中使用图像、音频、视频与文档

当使用接受多模态输入、支持多模态工具结果或返回多模态输出的大语言模型时，Deep Agents 原生支持多模态工作流。你可以将图像和其他多媒体附加到用户消息中，使用内置的 read_file 工具读取非文本文件，并从自定义工具中返回富媒体内容。

内置的上下文压缩主要面向文本。请相应规划多模态工作负载：将大型多媒体文件保存在后端存储中，并在消息中尽可能传递引用路径。

多模态用户输入

在发送给智能体的 messages 中传递多模态内容，采用与 LangChain 聊天模型相同的标准内容块：

const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: [
        { type: "text", text: "这张截图中展示了什么内容？" },
        { type: "image", url: "https://example.com/screenshot.png" },
      ],
    },
  ],
});

关于内容块类型、提供商专属要求以及更多示例（PDF、音频、视频），请参阅多模态消息。

内置 read_file 工具

对于受支持的多模态文件，运行框架的 read_file 工具会返回标准内容块而非纯文本。当所选模型支持相应模态时，智能体可以直接查看保存在文件系统中的图像、文档和音视频媒体。具体支持的 MIME 类型请参考对应模型提供商的官方说明。

支持的多模态文件扩展名

媒体类型	文件扩展名
图像	.png, .jpg, .jpeg, .gif, .webp, .heic, .heif
视频	.mp4, .mpeg, .mov, .avi, .flv, .mpg, .webm, .wmv, .3gpp
音频	.wav, .mp3, .aiff, .aac, .ogg, .flac
文档	.pdf, .ppt, .pptx

自定义工具的多模态输出

自定义工具可以返回包含多模态文件（例如截图）的数据块：

import { tool } from "langchain";
import { z } from "zod";

const captureScreenshot = tool(
  async () => [
    { type: "text", text: "当前页面的实时截图如下：" },
    { type: "image", url: "https://example.com/page.png" },
  ],
  {
    name: "capture_screenshot",
    description: "截取当前网页的屏幕截图。",
    schema: z.object({}),
  },
);

返回值会被自动转换为模型在下一轮对话中读取的 ToolMessage。可以通过生成消息上的 content_blocks 访问其规范化表示。

TIP

当工具生成图像或其他大型二进制数据时，建议将生成产物保存到后端存储中，并在工具中返回简明文本描述加上文件路径或 URL。这能显著缩减消息历史的体积，并更好地与上下文压缩协同工作。

上下文压缩与多模态内容

内置的上下文卸载与摘要机制针对文本和消息历史进行了深度优化：

• 卸载 (Offloading)：仅对文本 Token 进行计算。非文本块（包括图像）在替换消息中予以原样保留而非压缩。仅包含图像的消息不会单纯因为图像占用体积而被触发卸载。
• 摘要 (Summarization)：将较早的消息历史压缩为纯文本摘要。该时间范围内的图像、音频、视频和文档内容块不会原样向下传递——模型只能看到摘要器对其做出的文本描述。处于保留阈值之内的最新消息保持不变。

当摘要机制触发时，较早轮次中的富媒体内容块将从活跃上下文中脱落：

// 摘要前 —— 模型在历史轮次中接收完整的图像内容块
void {
  role: "user",
  content: [
    { type: "text", text: "你从这个图表中看到了什么趋势？" },
    { type: "image", url: "https://example.com/chart.png" },
  ],
};
void {
  role: "tool",
  content: [
    { type: "text", text: "更新后的图表：" },
    { type: "image", url: "https://example.com/chart-v2.png" },
  ],
};

// 摘要后 —— 那些轮次被压缩折叠为纯文本；图像内容块不再占用上下文
void {
  content:
    "用户询问了图表截图中的发展趋势。" +
    "工具返回了最新图表。智能体指出第三季度营收呈上升趋势。",
};

原始对话仍将作为文本记录写入文件系统。有关触发条件、保留阈值和完整执行流，请参阅摘要机制。

针对重度依赖多模态的业务场景：

• 将图像、截图和图表保存在文件系统后端或外部对象存储中，然后在消息中传递文件路径或轻量 URL。
• 在长时间运行的对话中，优先传递引用链接而非庞大的 Base64 编码图像块。
• 使用子智能体执行图像密集的检验和比对工作，以便主智能体仅接收精简的文本总结报告。
• 当你的模型提供商对图像输入收取大量 Token 费用时，适当调整摘要阈值或配置自定义 Token 计数器。

有关卸载阈值、摘要触发器和自定义选项，请参阅上下文工程。