ag2-multimodal-input

マルチモーダル入力

使用する場面

ユーザーが、テキスト以外の入力をエージェントに処理させたい場合に使用します。説明する画像、文字起こしする音声、要約する動画、内容を抽出する 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)

1 回の依頼に複数の入力を含めても問題ありません。

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 形式

どれも同じ 4 種類のデータソースを受け付けます。

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 — トークンとコストの調整
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 のリファレンス（アップロード／一覧表示／読み取り／削除）。
• LLM に画像／バイナリを返すツールについては、ag2-add-custom-tool（ImageInput、BinaryInput、ToolResult）を参照してください。

よくある落とし穴

• 入力タイプに対応していないプロバイダーを選ぶ — UnsupportedInputError が発生します。マトリックスを確認してください。最も幅広く対応しているのは Gemini です。
• Gemini で FilesAPI.read() を呼び出す — NotImplementedError が発生します。Gemini ではダウンロードが公開されていません。
• filename= を指定せずに files.upload(data=...) を呼び出す — ValueError が発生します。メモリ内のアップロードにはファイル名が必要です。
• ファクトリーに複数のソースを指定する — エラーにはなりません。ファクトリーは url > file_id > path > data の優先順位で解決するため、余分なソースは黙って無視されます。意図したとおりに処理するには、ソースを 1 つだけ渡してください。ソースをゼロ個指定すると ValueError が発生します。
• Anthropic の ImageInput(file_id=...) に filename= を指定しない — Anthropic はファイル名の拡張子でブロックタイプ（画像またはドキュメント）を判定します。ファイル名を渡してください。
• Gemini の vendor_metadata のキーが入れ子になっている — video_metadata 自体に dict を渡します。形式はドキュメントの表で確認してください。
• Gemini のファイル処理完了を待たない — 大きなアップロードは PROCESSING 状態になります。URI を参照する前に、準備ができるまで client.files.get(name=...) をポーリングしてください。