Agno + Gemini 3 多模态实战指南：用 use_cases 构建音乐、影视与游戏领域的 Agent 应用

Agno + Gemini 3 多模态实战指南：用 use_cases 构建音乐、影视与游戏领域的 Agent 应用

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno

本篇技术指南以 agno 仓库中 cookbook/gemini_3/use_cases 目录下的三个领域示例为骨架，完整拆解如何组合 Gemini 3 的多模态能力（音频、图像、视频、PDF）、结构化输出、Web 搜索与多 Agent 团队（Team），为音乐、影视、游戏三个真实行业场景搭建可落地的 Agent 应用。读完本文，你将掌握 use_cases 三个脚本的完整代码逻辑、底层媒体输入类与 RunOutput 的运行机制，并能按照"换数据、换 Schema、换团队、换知识库"四步法将示例改造为自己的业务方案。

一、use_cases 是什么：主指南的领域化收尾

在 cookbook/gemini_3/README.md 中，主指南按 21 个步骤循序渐进地演示了用 Google Gemini 构建 Agno Agent：从基础对话、工具调用、结构化输出，到 Gemini 原生搜索与思考、多模态输入（图像、音频、视频、PDF、CSV）、文件搜索与提示缓存，再到知识库、记忆、团队与工作流。而use_cases子目录正是这套能力的"实战验收场"——把主指南中分散的多个步骤组合进单一脚本，模拟真实业务流水线。

use_cases 目录下的三个脚本与主指南步骤的对应关系如下：

从 cookbook/gemini_3/use_cases/README.md 的定义看，这三个示例的核心设计意图是：每个脚本都展示了如何把多个单点能力编排成一个端到端的领域工作流。下文逐一拆解。

二、环境准备：主指南 Fast Path

运行三个用例前，需先完成主指南的环境配置（详见 cookbook/gemini_3/README.md 的 Fast Path）：

# 1. 克隆仓库 git clone https://github.com/agno-agi/agno.git && cd agno # 2. 创建虚拟环境（Python 3.12） uv venv .venvs/gemini --python 3.12 && source .venvs/gemini/bin/activate # 3. 安装依赖 uv pip install -r cookbook/gemini_3/requirements.txt # 4. 设置 Google API Key export GOOGLE_API_KEY=your-google-api-key

依赖清单见 cookbook/gemini_3/requirements.txt，核心为agno[google]，此外包含httpx（示例中用于下载音频/视频样本）、pydantic（结构化输出 Schema）、Pillow（game_concept_pitch 中保存生成的概念图）、duckduckgo-search与chromadb（供其他步骤使用）。

三、音乐行业用例：music_asset_brief.py

music_asset_brief.py 面向 A&R（艺人与曲库）和营销团队，把音频理解、封面图像理解、联网调研与结构化输出串成一条流水线。

3.1 输出 Schema：TrackBrief

脚本用 Pydantic 定义TrackBrief，这是整个用例的"交付物契约"：

class TrackBrief(BaseModel): track_name: str = Field(..., description="Name of the track") artist: str = Field(..., description="Artist or band name") genre: str = Field(..., description="Primary genre") mood: str = Field(..., description="Overall mood (e.g., energetic, melancholic)") tempo_estimate: str = Field(..., description="Estimated tempo (slow, mid, fast)") visual_style: str = Field(..., description="Visual style of the artwork") target_audience: str = Field(..., description="Suggested target audience") marketing_angles: List[str] = Field(..., description="3-5 marketing angles") comparable_artists: List[str] = Field(..., description="2-3 comparable artists") summary: str = Field(..., description="One-paragraph executive summary")

字段的description会被注入模型提示词，引导 Gemini 产出符合行业口径的输出：例如genre要求精确到子流派（"synth-pop" 而非笼统的 "pop"），comparable_artists要求 2～3 个当前活跃的类比艺人，marketing_angles要求 3～5 条可执行的营销角度。

3.2 Agent 指令：把角色行为写进 instructions

instructions = """\ You are a music industry analyst. You analyze tracks, artwork, and market context to produce comprehensive asset briefs for A&R and marketing teams. ## Workflow 1. If audio is provided, analyze the track: genre, mood, tempo, production style 2. If an image is provided, analyze the artwork: visual style, themes, color palette 3. Search the web for the agent and current market context 4. Produce a structured brief combining all insights ## Rules - Be specific about genre (not just "pop", say "synth-pop" or "indie pop") - Name comparable artists that are currently relevant - Marketing angles should be actionable - No emojis\ """

这里的指令同时承担"流程编排"与"质量标准"双重职责——前 4 步定义分析顺序，Rules 部分则约束输出质量。

3.3 Agent 组装与运行

music_analyst = Agent( name="Music Analyst", model=Gemini(id="gemini-3.5-flash"), instructions=instructions, tools=[WebSearchTools()], output_schema=TrackBrief, add_datetime_to_context=True, )

关键参数说明：

• model=Gemini(id="gemini-3.5-flash")：主指南推荐的"快速、低成本、工具调用出色"模型；add_datetime_to_context=True会让 Agent 感知当前时间，便于产出"当前相关"的艺人比较。
• tools=[WebSearchTools()]：来自 libs/agno/agno/tools/websearch.py 的搜索工具包，让 Agent 能调研艺人背景与市场上下文。
• output_schema=TrackBrief：强制模型按 Pydantic 模型返回，实现类型安全的强结构化输出。

运行入口（__main__块）演示了多模态输入的典型写法：

audio_url = "https://agno-public.s3.amazonaws.com/demo/sample-audio.mp3" artwork_url = "https://agno-public.s3.amazonaws.com/images/krakow_mariacki.jpg" audio_response = httpx.get(audio_url) result = music_analyst.run( "Analyze this music track and album artwork. " "Research the artist and produce a comprehensive asset brief.", audio=[Audio(content=audio_response.content, format="mp3")], images=[Image(url=artwork_url)], )

注意音频与图像两种媒体类型采用了不同的传入方式：音频先用httpx下载为原始字节再以Audio(content=..., format="mp3")传入；封面图则直接以 URL 形式传给Image(url=...)。这得益于 agno 统一的媒体模型（详见第六节）。运行结果result.content即TrackBrief实例，可直接以属性方式访问打印。

四、影视行业用例：film_scene_breakdown.py

film_scene_breakdown.py 面向影视后期与制片流程，演示"视频理解 + PDF 阅读 + 多 Agent 团队"的协同。

4.1 三个专职成员

脚本用三个角色互补的 Agent 模拟真实制片组：

三个成员均使用Gemini(id="gemini-3.5-flash")并开启markdown=True，让输出以 Markdown 呈现。值得注意的设计是：成员通过role声明分工，指令中各自定义"提取什么"与"遵循什么规则"，形成清晰的单点职责。

4.2 团队编排：Production Team

production_team = Team( name="Production Team", model=Gemini(id="gemini-3.1-pro-preview"), members=[video_analyst, script_reader, continuity_editor], instructions="""\ You lead a film production team with a Video Analyst, Script Reader, and Continuity Editor. ## Process 1. Send the video clip to the Video Analyst for visual breakdown 2. Send the script PDF to the Script Reader for dialogue and direction extraction 3. Send both analyses to the Continuity Editor for consistency check 4. Synthesize into a final scene breakdown ## Output Format Provide a scene breakdown with: - **Visual Summary**: Key shots and visual elements - **Script Notes**: Relevant dialogue and directions - **Continuity Report**: Any discrepancies found - **Production Notes**: Recommendations for the edit\ """, show_members_responses=True, markdown=True, )

团队层面的设计要点：

• Team由领导模型（这里是更强的gemini-3.1-pro-preview）与members成员列表构成，members的类型定义见 libs/agno/agno/team/team.py，即Union[List[Union[Agent, "Team"]], Callable[..., List]]——成员既可以是 Agent，也可以是嵌套的 Team。
• 领导者的instructions里明确了任务分发顺序（视频给 Video Analyst → 剧本给 Script Reader → 合并给 Continuity Editor → 综合产出）和最终输出格式（Visual Summary / Script Notes / Continuity Report / Production Notes 四段式）。
• show_members_responses=True会让团队运行过程中把各成员的原始响应一并展示（对应 team.py 中的show_members_responses: bool = False默认值），方便观察每个成员的产出。

4.3 运行：视频字节 + PDF URL 的混合输入

video_url = "https://agno-public.s3.amazonaws.com/demo/sample_seaview.mp4" script_url = "https://agno-public.s3.amazonaws.com/recipes/ThaiRecipes.pdf" video_response = httpx.get(video_url) production_team.print_response( "Analyze this video clip and compare it against the provided document. ...", videos=[Video(content=video_response.content, format="mp4")], files=[File(url=script_url)], stream=True, )

这里再次出现媒体输入的混合模式：视频以Video(content=bytes, format="mp4")传入，PDF 以File(url=...)传入，且print_response开启stream=True实现流式输出。团队对外暴露了与 Agent 一致的调用接口（print_response定义于 team.py），上层使用体验与单 Agent 无异。

五、游戏行业用例：game_concept_pitch.py

game_concept_pitch.py 展示一条完整的游戏提案流水线：先生成概念图，再产出结构化提案，最后组建评审委员会。

5.1 阶段一：概念图生成与落盘

art_agent = Agent( name="Concept Artist", model=Gemini( id="gemini-3.5-flash", response_modalities=["Text", "Image"], ), )

response_modalities=["Text", "Image"]让 Gemini 在响应中同时返回文本与生成的图像。运行后从RunOutput中取出图片并保存：

art_result = art_agent.run( f"Create concept art for this game: {game_idea}. " "Show a diver exploring a bioluminescent underwater cave with glowing creatures." ) if art_result and isinstance(art_result, RunOutput) and art_result.images: from PIL import Image as PILImage for i, img in enumerate(art_result.images): if img.content: image = PILImage.open(BytesIO(img.content)) path = WORKSPACE / f"game_concept_{i}.png" image.save(str(path))

这里涉及 libs/agno/agno/run/agent.py 中定义的RunOutput返回类型：Agent.run()返回的对象携带content、images、videos、audio、files等字段（见第 649～652 行），其中images是 agno 统一媒体类Image的列表。脚本先用isinstance校验返回类型，再遍历art_result.images，把每张图的img.content（字节）通过 Pillow 保存到WORKSPACE目录（Path(__file__).parent.parent.joinpath("workspace")，即cookbook/gemini_3/workspace/），未安装 Pillow 时会给出pip install Pillow的提示。

5.2 阶段二：结构化游戏提案

class GamePitch(BaseModel): title: str = Field(..., description="Game title") tagline: str = Field(..., description="One-line hook (max 15 words)") genre: str = Field(..., description="Primary genre (e.g., action RPG, puzzle platformer)") platform: List[str] = Field(..., description="Target platforms") target_audience: str = Field(..., description="Target demographic") core_mechanic: str = Field(..., description="The one thing that makes the game fun") setting: str = Field(..., description="World and setting description (2-3 sentences)") unique_selling_points: List[str] = Field(..., description="3-5 unique selling points") comparable_titles: List[str] = Field(..., description="2-3 comparable games") monetization: str = Field(..., description="Monetization strategy") elevator_pitch: str = Field(..., description="Full elevator pitch (one paragraph)")

GamePitch覆盖一款游戏提案所需的 11 个维度。pitch_writerAgent 使用gemini-3.1-pro-preview模型承载更重的写作任务，指令约束包括"机制要具体、类比游戏须为近三年作品、变现方式须符合品类、tagline 要让人想继续听"，同时开启add_datetime_to_context=True。运行后pitch_result.content即为GamePitch实例。

5.3 阶段三：评审委员会

评审团队由两名成员组成，且角色分化明确：

• Market Analyst：评估市场可行性，Gemini(id="gemini-3.5-flash", search=True)开启 Gemini 原生搜索以获取近期市场数据；评估需求、竞争拥挤度、变现现实性与风险收益比。
• Creative Director：评估创意质量与玩家体验，聚焦核心机制趣味性、世界观与玩法支撑、受众共鸣与 "wow factor"，并要求考虑可访问性。

review_team = Team( name="Review Board", model=Gemini(id="gemini-3.1-pro-preview"), members=[market_analyst, creative_director], instructions="""\ You chair a game pitch review board with a Market Analyst and Creative Director. ## Process 1. Send the pitch to the Market Analyst for viability assessment 2. Send the pitch to the Creative Director for creative evaluation 3. Synthesize into a final review with: - **Market Assessment**: Viability and competitive analysis - **Creative Review**: Strengths and areas for improvement - **Final Verdict**: Go / Revise / Pass with reasoning\ """, show_members_responses=True, markdown=True, )

评审委员会的最终输出被设计成三段式：Market Assessment、Creative Review、Final Verdict（Go / Revise / Pass 三档结论并附理由）——这是一个可以直接用于决策会议的结构化评审模板。

六、源码深挖：统一媒体类与运行机制

三个用例在输入输出上反复出现的Audio、Image、Video、File都定义在 libs/agno/agno/media/media.py 中，它们共享同一套设计哲学：url、filepath、content三种内容来源三选一。

以 Image 类 为例，其模型校验器（@model_validator(mode="before")）会强制"恰好一个内容来源"：

• 三个来源全部为空 → 抛出ValueError("One of 'url', 'filepath', or 'content' must be provided")；
• 超过一个来源 → 抛出ValueError("Only one of 'url', 'filepath', or 'content' should be provided")；
• 自动生成id（UUID）用于追踪引用。

Audio类（media.py）在三个来源之外还带format（如 mp3/wav/ogg）、duration（秒）、sample_rate（默认 24000 Hz）等音频元数据。此外，这些媒体类还提供get_content_bytes()/get_url()/to_base64()等方法，支持从 URL 或本地文件惰性加载字节、生成可访问 URL 及 base64 编码传输——这也是 game_concept_pitch 中能从RunOutput.images取出img.content字节并保存为 PNG 的底层保证。

这种统一抽象意味着：用例中的任何媒体输入（URL、本地路径、远程下载的字节）都可以灵活替换为你的真实数据，而调用代码无需改变。

七、运行三个用例

在完成 Fast Path 环境配置后，按 use_cases/README.md 提供的命令逐个运行：

python cookbook/gemini_3/use_cases/music_asset_brief.py python cookbook/gemini_3/use_cases/film_scene_breakdown.py python cookbook/gemini_3/use_cases/game_concept_pitch.py

常见问题的处理参考主指南 Troubleshooting 一节：

八、将用例适配到你的领域

use_cases/README.md 明确指出这些示例是"起点"而非终点，并给出了四步改造法。结合上文源码分析，可以进一步落实到具体代码层面：

1. 替换示例提示词与数据：三个脚本的__main__块中都有明确注释标记的替换点（如# Replace these with your own audio URL and artwork URL）。把样本音频、封面图、视频、PDF 的 URL 换成你自己的素材；把game_idea字符串换成你的产品创意描述。媒体来源既可以是 URL，也可以是本地filepath或读入内存的content字节（参见第六节三选一规则）。
2. 调整输出 Schema 以匹配数据模型：重定义TrackBrief/GamePitch这类 Pydantic 模型，增删字段并写好Field(..., description=...)描述——这些描述直接参与提示词构建，字段粒度越细，输出越可控。对于影视用例，可以把团队最终输出的四段式结构（Visual Summary / Script Notes / Continuity Report / Production Notes）也升级为output_schema强约束。
3. 按工作流增删团队成员：Team(members=[...])支持任意增减。例如在影视场景中可增加"调色师"Agent，在音乐场景中可为营销团队增加"社交媒体分析师"；成员也可以是嵌套 Team（见 team.py 的成员类型定义）。注意每个成员要用明确的role和instructions界定职责边界。
4. 接入自有知识库获取领域知识：主指南第 17 步展示了 ChromaDb 知识库与 SqliteDb 存储的组合（见 cookbook/gemini_3/17_knowledge.py），可以把公司内部的曲库规则、剧本格式规范、游戏设计文档注入知识库，让 Agent 在生成简报、分场分析或提案时获得领域约束。

九、小结

use_cases 三个示例的价值在于示范了"能力组合"的编排思想：music_asset_brief.py展示单 Agent 如何同时消费音频与图像两类多模态输入并产出强结构化结果；film_scene_breakdown.py展示 Team 如何通过角色分工（视频分析 / 剧本提取 / 连续性校对）处理异构输入；game_concept_pitch.py则把图像生成、结构化写作与团队评审串成三段式流水线。三者共享 agno 的统一媒体抽象与RunOutput返回模型，意味着你可以把任意一段能力自由嫁接到自己的业务管道中——这正是从示例走向生产应用的关键路径。

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno