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 目录下的三个脚本与主指南步骤的对应关系如下文件领域组合的能力主指南步骤脚本功能music_asset_brief.py音乐音频 图像 搜索 结构化输出2/3/8/10 步分析歌曲与专辑封面调研艺人产出结构化简报film_scene_breakdown.py影视视频 PDF 多 Agent 团队12/13/19 步分析视频片段读取剧本 PDF由团队产出分场分析game_concept_pitch.py游戏图像生成 结构化输出 多 Agent 团队3/9/19 步生成概念图结构化游戏提案团队评审从 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_KEYyour-google-api-key依赖清单见 cookbook/gemini_3/requirements.txt核心为agno[google]此外包含httpx示例中用于下载音频/视频样本、pydantic结构化输出 Schema、Pillowgame_concept_pitch 中保存生成的概念图、duckduckgo-search与chromadb供其他步骤使用。三、音乐行业用例music_asset_brief.pymusic_asset_brief.py 面向 AR艺人与曲库和营销团队把音频理解、封面图像理解、联网调研与结构化输出串成一条流水线。3.1 输出 SchemaTrackBrief脚本用 Pydantic 定义TrackBrief这是整个用例的交付物契约class TrackBrief(BaseModel): track_name: str Field(..., descriptionName of the track) artist: str Field(..., descriptionArtist or band name) genre: str Field(..., descriptionPrimary genre) mood: str Field(..., descriptionOverall mood (e.g., energetic, melancholic)) tempo_estimate: str Field(..., descriptionEstimated tempo (slow, mid, fast)) visual_style: str Field(..., descriptionVisual style of the artwork) target_audience: str Field(..., descriptionSuggested target audience) marketing_angles: List[str] Field(..., description3-5 marketing angles) comparable_artists: List[str] Field(..., description2-3 comparable artists) summary: str Field(..., descriptionOne-paragraph executive summary)字段的description会被注入模型提示词引导 Gemini 产出符合行业口径的输出例如genre要求精确到子流派synth-pop 而非笼统的 popcomparable_artists要求 23 个当前活跃的类比艺人marketing_angles要求 35 条可执行的营销角度。3.2 Agent 指令把角色行为写进 instructionsinstructions \ You are a music industry analyst. You analyze tracks, artwork, and market context to produce comprehensive asset briefs for AR 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( nameMusic Analyst, modelGemini(idgemini-3.5-flash), instructionsinstructions, tools[WebSearchTools()], output_schemaTrackBrief, add_datetime_to_contextTrue, )关键参数说明modelGemini(idgemini-3.5-flash)主指南推荐的快速、低成本、工具调用出色模型add_datetime_to_contextTrue会让 Agent 感知当前时间便于产出当前相关的艺人比较。tools[WebSearchTools()]来自 libs/agno/agno/tools/websearch.py 的搜索工具包让 Agent 能调研艺人背景与市场上下文。output_schemaTrackBrief强制模型按 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(contentaudio_response.content, formatmp3)], images[Image(urlartwork_url)], )注意音频与图像两种媒体类型采用了不同的传入方式音频先用httpx下载为原始字节再以Audio(content..., formatmp3)传入封面图则直接以 URL 形式传给Image(url...)。这得益于 agno 统一的媒体模型详见第六节。运行结果result.content即TrackBrief实例可直接以属性方式访问打印。四、影视行业用例film_scene_breakdown.pyfilm_scene_breakdown.py 面向影视后期与制片流程演示视频理解 PDF 阅读 多 Agent 团队的协同。4.1 三个专职成员脚本用三个角色互补的 Agent 模拟真实制片组Agentrole职责instructions 摘要Video AnalystAnalyze video clips for visual content, pacing, and mood描述景别wide/close-up/tracking、转场与节奏、灯光与色调、角色动作、画面文字要求使用专业影视术语、按时间顺序描述、记录关键时间戳Script ReaderRead film scripts and extract relevant dialogue and directions提取场次标题INT/EXT、地点、时间段、对白、舞台指示与摄影方向保留剧本格式规范、标注页码、标记含糊指示Continuity EditorCheck consistency between script and footage核对成片与剧本动作是否一致、对白是否按剧本呈现、道具服装布景是否连贯、灯光是否符合剧本时间段分歧按 Minor / Notable / Critical 分级并给出解决方案三个成员均使用Gemini(idgemini-3.5-flash)并开启markdownTrue让输出以 Markdown 呈现。值得注意的设计是成员通过role声明分工指令中各自定义提取什么与遵循什么规则形成清晰的单点职责。4.2 团队编排Production Teamproduction_team Team( nameProduction Team, modelGemini(idgemini-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_responsesTrue, markdownTrue, )团队层面的设计要点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_responsesTrue会让团队运行过程中把各成员的原始响应一并展示对应 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(contentvideo_response.content, formatmp4)], files[File(urlscript_url)], streamTrue, )这里再次出现媒体输入的混合模式视频以Video(contentbytes, formatmp4)传入PDF 以File(url...)传入且print_response开启streamTrue实现流式输出。团队对外暴露了与 Agent 一致的调用接口print_response定义于 team.py上层使用体验与单 Agent 无异。五、游戏行业用例game_concept_pitch.pygame_concept_pitch.py 展示一条完整的游戏提案流水线先生成概念图再产出结构化提案最后组建评审委员会。5.1 阶段一概念图生成与落盘art_agent Agent( nameConcept Artist, modelGemini( idgemini-3.5-flash, response_modalities[Text, Image], ), )response_modalities[Text, Image]让 Gemini 在响应中同时返回文本与生成的图像。运行后从RunOutput中取出图片并保存art_result art_agent.run( fCreate 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 / fgame_concept_{i}.png image.save(str(path))这里涉及 libs/agno/agno/run/agent.py 中定义的RunOutput返回类型Agent.run()返回的对象携带content、images、videos、audio、files等字段见第 649652 行其中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(..., descriptionGame title) tagline: str Field(..., descriptionOne-line hook (max 15 words)) genre: str Field(..., descriptionPrimary genre (e.g., action RPG, puzzle platformer)) platform: List[str] Field(..., descriptionTarget platforms) target_audience: str Field(..., descriptionTarget demographic) core_mechanic: str Field(..., descriptionThe one thing that makes the game fun) setting: str Field(..., descriptionWorld and setting description (2-3 sentences)) unique_selling_points: List[str] Field(..., description3-5 unique selling points) comparable_titles: List[str] Field(..., description2-3 comparable games) monetization: str Field(..., descriptionMonetization strategy) elevator_pitch: str Field(..., descriptionFull elevator pitch (one paragraph))GamePitch覆盖一款游戏提案所需的 11 个维度。pitch_writerAgent 使用gemini-3.1-pro-preview模型承载更重的写作任务指令约束包括机制要具体、类比游戏须为近三年作品、变现方式须符合品类、tagline 要让人想继续听同时开启add_datetime_to_contextTrue。运行后pitch_result.content即为GamePitch实例。5.3 阶段三评审委员会评审团队由两名成员组成且角色分化明确Market Analyst评估市场可行性Gemini(idgemini-3.5-flash, searchTrue)开启 Gemini 原生搜索以获取近期市场数据评估需求、竞争拥挤度、变现现实性与风险收益比。Creative Director评估创意质量与玩家体验聚焦核心机制趣味性、世界观与玩法支撑、受众共鸣与 wow factor并要求考虑可访问性。review_team Team( nameReview Board, modelGemini(idgemini-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_responsesTrue, markdownTrue, )评审委员会的最终输出被设计成三段式Market Assessment、Creative Review、Final VerdictGo / Revise / Pass 三档结论并附理由——这是一个可以直接用于决策会议的结构化评审模板。六、源码深挖统一媒体类与运行机制三个用例在输入输出上反复出现的Audio、Image、Video、File都定义在 libs/agno/agno/media/media.py 中它们共享同一套设计哲学url、filepath、content三种内容来源三选一。以 Image 类 为例其模型校验器model_validator(modebefore)会强制恰好一个内容来源三个来源全部为空 → 抛出ValueError(One of url, filepath, or content must be provided)超过一个来源 → 抛出ValueError(Only one of url, filepath, or content should be provided)自动生成idUUID用于追踪引用。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 一节问题处理方式GOOGLE_API_KEY not setexport GOOGLE_API_KEYyour-keyModuleNotFoundErroruv pip install -r cookbook/gemini_3/requirements.txt429 Rate limit exceeded等待一分钟或更换其他模型 IDModel not found检查模型 ID 拼写使用gemini-3.5-flash或gemini-3.1-pro-preview八、将用例适配到你的领域use_cases/README.md 明确指出这些示例是起点而非终点并给出了四步改造法。结合上文源码分析可以进一步落实到具体代码层面替换示例提示词与数据三个脚本的__main__块中都有明确注释标记的替换点如# Replace these with your own audio URL and artwork URL。把样本音频、封面图、视频、PDF 的 URL 换成你自己的素材把game_idea字符串换成你的产品创意描述。媒体来源既可以是 URL也可以是本地filepath或读入内存的content字节参见第六节三选一规则。调整输出 Schema 以匹配数据模型重定义TrackBrief/GamePitch这类 Pydantic 模型增删字段并写好Field(..., description...)描述——这些描述直接参与提示词构建字段粒度越细输出越可控。对于影视用例可以把团队最终输出的四段式结构Visual Summary / Script Notes / Continuity Report / Production Notes也升级为output_schema强约束。按工作流增删团队成员Team(members[...])支持任意增减。例如在影视场景中可增加调色师Agent在音乐场景中可为营销团队增加社交媒体分析师成员也可以是嵌套 Team见 team.py 的成员类型定义。注意每个成员要用明确的role和instructions界定职责边界。接入自有知识库获取领域知识主指南第 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考