ag2-multimodal-input

多模态输入

适用场景

用户希望 Agent 处理非文本输入：描述图像、转写音频、总结视频，或从 PDF / 文档中提取信息。所有提供商都可使用相同的工厂模式；各提供商的支持情况有所不同。

60 秒快速上手

from ag2 import Agent
from ag2.config import GeminiConfig
from ag2.events import ImageInput

agent = Agent(
    "vision",
    "You describe images.",
    config=GeminiConfig(model="gemini-3-flash-preview"),
)

image = ImageInput("https://example.com/photo.jpg")
reply = await agent.ask("Describe this image in detail.", image)
print(reply.body)

一次请求包含多个输入也没问题：

reply = await agent.ask(
    "Compare these two images.",
    ImageInput("https://example.com/before.jpg"),
    ImageInput("https://example.com/after.jpg"),
)

输入工厂

工厂	格式
ImageInput(...)	JPEG、PNG、GIF、WebP
AudioInput(...)	WAV、MP3、OGG、FLAC、AAC
VideoInput(...)	MP4、WebM、MOV、MKV、MPEG
DocumentInput(...)	PDF、TXT、HTML、Markdown、CSV、JSON、Office 格式

每个工厂都接受相同的四种数据来源：

from ag2.events import ImageInput

ImageInput("https://example.com/photo.jpg")     # URL
ImageInput(path="photo.jpg")                    # local file
ImageInput(data=raw_bytes, media_type="image/png")  # bytes
ImageInput(file_id="file-abc123")               # provider-uploaded

提供商支持矩阵

输入类型	OpenAI	OpenAI Responses	Gemini	Anthropic
文本	✓	✓	✓	✓
图像（URL）	✓	✓	✓	✓
图像（二进制）	✓	✓	✓	✓
音频（URL）	–	–	✓	–
音频（二进制）	✓	–	✓	–
视频（URL）	–	–	✓	–
视频（二进制）	–	–	✓	–
文档（URL）	–	✓	✓	✓
文档（二进制）	✓	✓	✓	✓
文件 ID	✓	✓	✓	✓

不支持的组合会引发 UnsupportedInputError，并显示明确的错误信息。

Gemini 的多模态支持范围最广。 如果不确定多模态任务该选择哪个提供商，可以先从 Gemini 开始。

提供商特有的便利功能

Gemini — 可直接使用 YouTube URL

from ag2.events import VideoInput

video = VideoInput("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
reply = await agent.ask("Summarize this video.", video)

Gemini — 通过 Google Files API 处理大型文件（> 20MB）

from google import genai
from ag2.events import VideoInput
import time

client = genai.Client()
uploaded = client.files.upload(file="large_video.mp4")
while uploaded.state.name == "PROCESSING":
    time.sleep(2)
    uploaded = client.files.get(name=uploaded.name)

video = VideoInput(uploaded.uri)

Gemini — vendor_metadata

键	用途
media_resolution	MEDIA_RESOLUTION_LOW/MEDIUM/HIGH/ULTRA_HIGH — 在 token 用量与成本之间权衡
video_metadata	视频剪辑（start_offset、end_offset）和 fps
display_name	文件的显示名称

ImageInput(data=raw, media_type="image/jpeg", vendor_metadata={"media_resolution": "MEDIA_RESOLUTION_LOW"})

VideoInput(path="lecture.mp4", vendor_metadata={
    "video_metadata": {"start_offset": "60s", "end_offset": "120s", "fps": 0.5},
})

OpenAI — 图像细节级别

ImageInput(data=raw, media_type="image/png", vendor_metadata={"detail": "low"})  # "low" | "high" | "auto"

Anthropic — 文件 ID + 提示词缓存

import anthropic
from ag2.events import ImageInput, DocumentInput

client = anthropic.Anthropic()
uploaded = client.beta.files.upload(file=("photo.jpg", open("photo.jpg", "rb"), "image/jpeg"))

# filename determines block type (image vs document)
image = ImageInput(file_id=uploaded.id, filename="photo.jpg")

# Cache an attachment so subsequent turns skip re-uploading
doc = DocumentInput(path="report.pdf", vendor_metadata={"cache_control": {"type": "ephemeral"}})

FilesAPI — 与提供商无关的上传生命周期管理

对于任何具有文件 API 的提供商（OpenAIConfig、OpenAIResponsesConfig、AnthropicConfig、GeminiConfig）：

from ag2 import FilesAPI
from ag2.config import OpenAIResponsesConfig

files = FilesAPI(OpenAIResponsesConfig(model="gpt-5-mini"))

uploaded = await files.upload(path="report.pdf", purpose="assistants")
print(uploaded.file_id)

# Or from bytes (filename required)
uploaded = await files.upload(data=b"...", filename="hello.txt", purpose="assistants")

# List, read, delete
all_files = await files.list()
data = await files.read(uploaded.file_id)        # NotImplementedError on Gemini
await files.delete(uploaded.file_id)

将 file_id 传递给 DocumentInput、ImageInput 等：

from ag2.events import DocumentInput

doc = DocumentInput(file_id=uploaded.file_id)
reply = await agent.ask("Summarize this report.", doc)

深入了解

• website/docs/user-guide/multimodal/inputs.mdx — 完整的提供商支持矩阵和 vendor_metadata 参考。
• website/docs/user-guide/advanced/files.mdx — FilesAPI 参考（上传 / 列出 / 读取 / 删除）。
• 如需了解向大模型返回图像 / 二进制数据的工具，请参阅 ag2-add-custom-tool（ImageInput、BinaryInput、ToolResult）。

常见问题

• 选择了不支持输入类型的提供商 — 会引发 UnsupportedInputError。请查看支持矩阵；Gemini 的支持范围最广。
• 在 Gemini 上调用 FilesAPI.read() — 会引发 NotImplementedError。Gemini 不提供下载功能。
• 调用 files.upload(data=...) 时未指定 filename= — 会引发 ValueError。上传内存中的文件时必须提供文件名。
• 向工厂提供多个来源 — 不会报错。工厂会按 url > file_id > path > data 的优先级解析，因此额外的来源会被静默忽略。若要确保结果符合预期，请只传入一个来源。零个来源则会引发 ValueError。
• 调用 Anthropic 的 ImageInput(file_id=...) 时未指定 filename= — Anthropic 会根据文件名扩展名判断内容块类型（图像还是文档）。请传入文件名。
• Gemini 的 vendor_metadata 键是嵌套的 — video_metadata 本身需要传入一个字典。请查看文档表格了解其结构。
• 忘记等待 Gemini 文件处理完成 — 大型上传文件会处于 PROCESSING 状态。在引用 URI 前，请轮询 client.files.get(name=...)，直到文件就绪。