Agno Multimodal

상위: Agno

요약

Agno 에이전트는 텍스트, 이미지, 오디오, 비디오, 파일을 네이티브로 처리한다. agno.media에서 제공하는 4가지 미디어 클래스(Image, Audio, Video, File)를 통해 입력하고, 모델에 따라 이미지·오디오·비디오 출력도 가능하다. 모든 클래스는 Pydantic BaseModel 기반이며, 정확히 하나의 콘텐츠 소스(url, filepath, content)가 필요하다.

미디어 클래스

모든 클래스는 agno.media에서 임포트한다. 공통 메서드: get_content_bytes(), to_base64(), from_base64(), to_dict().

from agno.media import Image, Audio, Video, File

Image

from agno.media import Image

# URL로 전달
agent.run("Describe this image", images=[Image(url="https://example.com/photo.jpg")])

# 파일 경로로 전달
agent.run("What's in this image?", images=[Image(filepath="./photo.png")])

# 고해상도 분석
agent.run("Analyze in detail", images=[Image(url="https://...", detail="high")])

# 여러 이미지 동시 비교
agent.run("Compare these", images=[
    Image(url="https://example.com/a.jpg"),
    Image(filepath="./b.png"),
])

# base64에서 생성
img = Image.from_base64(b64_string, mime_type="image/png")

Audio

from agno.media import Audio

# URL 오디오
agent.run("Transcribe this", audio=[Audio(url="https://example.com/audio.mp3")])

# 바이트 데이터
audio_bytes = open("recording.wav", "rb").read()
agent.run("What is said?", audio=[Audio(content=audio_bytes, format="wav")])

Video

제한: 비디오 입력은 현재 Gemini 모델만 지원한다.

from agno.media import Video
from agno.models.google import Gemini

agent = Agent(model=Gemini(id="gemini-3-flash-preview"))  # 2.0-flash 계열은 2026-06 셧다운
agent.run("Describe this video", videos=[Video(url="https://example.com/clip.mp4")])

File

지원 MIME 타입: application/pdf, application/json, text/* 등.

from agno.media import File

agent.run("Summarize this PDF", files=[File(filepath="./report.pdf")])

도구에서 파일을 처리하려면 send_media_to_model=False, store_media=True를 설정한다:

agent = Agent(
    tools=[MyFileProcessor()],
    send_media_to_model=False,  # LLM에 직접 전송 안 함
    store_media=True,           # 도구에서 접근 가능하게 저장
)

입력 방식 4가지

모든 미디어 클래스가 동일한 4가지 입력 패턴을 지원한다:

agent.run()에서의 전달 방식

미디어는 run(), arun(), print_response() 메서드의 전용 파라미터로 전달한다:

response = agent.run(
    "Analyze all these inputs",
    images=[Image(...)],       # 이미지 리스트
    audio=[Audio(...)],        # 오디오 리스트
    videos=[Video(...)],       # 비디오 리스트
    files=[File(...)],         # 파일 리스트
)

모델별 지원 현황

오디오 입출력

오디오 생성은 모델 설정에서 modalities와 audio 파라미터를 추가로 지정해야 한다. 음성 옵션: "sage", "alloy" 등. 포맷: "wav", "pcm16" (스트리밍용).

from agno.agent import Agent
from agno.media import Audio
from agno.models.openai import OpenAIChat
from agno.utils.audio import write_audio_to_file

agent = Agent(
    model=OpenAIChat(
        id="gpt-audio-1.5",  # gpt-4o-audio-preview는 2026-05 폐지
        modalities=["text", "audio"],           # 오디오 출력 활성화
        audio={"voice": "sage", "format": "wav"},  # 음성 설정
    ),
)

# 오디오 입력 + 오디오 출력
response = agent.run(
    "What's in this recording?",
    audio=[Audio(content=wav_data, format="wav")],
)

# 응답 오디오 저장
if response.response_audio is not None:
    write_audio_to_file(
        audio=response.response_audio.content,
        filename="tmp/result.wav",
    )

오디오 전사 (Gemini)

from agno.agent import Agent
from agno.media import Audio
from agno.models.google import Gemini

agent = Agent(model=Gemini(id="gemini-3-flash-preview"))

audio_content = open("conversation.mp3", "rb").read()
agent.print_response(
    "Transcribe this audio. Use Speaker A, Speaker B.",
    audio=[Audio(content=audio_content)],
    stream=True,
)

이미지 생성

이미지 생성은 에이전트의 도구로 동작한다. 여러 도구 옵션이 있다:

# OpenAI gpt-image-1
from agno.tools.openai import OpenAITools

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[OpenAITools(image_model="gpt-image-1")],
)

# FalTools (image-to-image 변환)
from agno.tools.fal import FalTools

agent = Agent(
    model=OpenAIResponses(id="gpt-4o"),
    tools=[FalTools()],
)

# 생성된 이미지 접근
images = agent.get_images()

비디오 생성

비디오 생성도 도구 기반이다:

# FalTools로 비디오 생성
from agno.tools.fal import FalTools

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[FalTools(
        model="fal-ai/hunyuan-video",
        enable_generate_media=True,
    )],
)

# Replicate로 비디오 생성
from agno.tools.replicate import ReplicateTools

agent = Agent(tools=[ReplicateTools(model="tencent/hunyuan-video")])

# MoviePyVideoTools로 캡션 추가
from agno.tools.moviepy import MoviePyVideoTools

agent = Agent(
    tools=[MoviePyVideoTools(
        process_video=True,
        generate_captions=True,
        embed_captions=True,
    )],
)

도구에서의 미디어 접근

도구 함수에 images, videos, files 등의 파라미터를 선언하면 자동 주입된다:

from agno.media import File
from typing import Optional, Sequence

def extract_text_from_pdf(files: Optional[Sequence[File]] = None) -> str:
    """Process uploaded files."""
    if not files:
        return "No files uploaded"
    for f in files:
        content = f.get_content_bytes()
        # 파일 처리 로직
    return f"Processed {len(files)} files"

관련 개념

• Agno: Agno 프레임워크 MOC
• Agno Agent: 단일 에이전트 구성
• Agno Tools & Guardrails: 도구 시스템
• Agno AgentOS: 프로덕션 런타임