ADK YouTube Analyst 可视化与报告发布 Skill 实战从指标数据到可分享 HTML 报告的完整工作流【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本篇文章围绕 visualization-reporting Skill 展开它是基于 Agent Development KitADK构建的 YouTube Analyst 多 Agent 示例中最具代表性的交付链路把检索与分析得到的指标数据先交给可视化子 Agent 生成图表再通过 Google Cloud StorageGCS发布为带公网链接的可分享 HTML 报告。读完本文你将掌握该 Skill 的六步执行协议、内部 Artifact 与外部发布文件的本质区别、publish_file/render_html/load_artifacts等底层工具的调用细节与源码实现并能直接在自己的 ADK Agent 中复刻这套分析 → 出图 → 成稿 → 发布的完整方案。Skill 概览visualization-reporting 的定位与注册方式该 Skill 的 frontmatter 定义了它的元信息name: visualization-reporting description: Transforms raw metrics and analysis into visual charts and published, shareable HTML reports using Google Cloud Storage.从描述可以看出它承担两类职责的衔接一是可视化把原始指标变成图表二是发布把图表与文字分析组装成可通过 GCS 分享的 HTML 报告。在仓库中该 Skill 以目录形式存放在python/agents/youtube-analyst/youtube_analyst/skills/visualization-reporting/下与其并列的还有abcd-framework-audit、sentiment-analysis、kol-discovery等十余个 Skill共同构成 YouTube Analyst 的模块化工作流体系。在 agent.py 中可以看到它被加载的具体方式根 Agentyoutube_analyst通过load_skill_from_dir逐个加载skills目录下的 Skill再以SkillToolset(skillsskills)的形式挂载为工具集skills_root pathlib.Path(__file__).parent / skills skills [ load_skill_from_dir(skills_root / name) for name in [ abcd-framework-audit, ... visualization-reporting, ] ]因此当用户提出帮我做一份可视化的对比报告这类请求时根 Agent 会通过list_skills()/load_skill()找到该 Skill 并按其中的步骤执行这一调用约定同样写在根 Agent 的系统提示词 youtube_agent.txt 中。核心目标严格区分内部 Artifact与外部发布文件Skill 的 Objective 开宗明义地强调了一组关键概念Objective: Transform raw numerical data and insights into beautiful, shareable assets. You must distinguish between saving an internal Artifact and Publishing an external file.内部 ArtifactArtifact保存在 ADK 会话内存中的文件对象可以被 Agent 后续通过工具读取、也可以供用户在会话内下载但没有公网访问能力。外部发布文件Published file通过 GCS 上传后获得的https://storage.googleapis.com/...公网 URL任何拥有链接的人都能在浏览器中打开。这两者的区别贯穿整个工作流图表先以 Artifact 形式暂存在会话中再以字节流形式搬运到 GCS 变成公网资源最终 HTML 报告内部只引用公网 URL 而非本地路径。理解这条先内部、后外部的搬运链是掌握本 Skill 的关键。六步执行协议详解Step 1确认数据Confirm Data在执行任何可视化动作之前Agent 必须先确认手头已有足够的数据例如频道及其互动率的字典a dictionary of channels and their engagement rates或已经合成好的最终分析文本。这一步对应 YouTube Analyst 的数据获取工具链例如 tools.py 中的search_youtube、get_video_details、calculate_engagement_metrics等根 Agent 先拉取原始指标再进入可视化阶段。数据不足时不应强行出图这是保证图表有意义的先决条件。Step 2可视化VisualizeSkill 要求将原始数据委托Delegate给visualization_agent子 Agent而不是根 Agent 自己写绘图代码。在 visualization_agent.py 中可以看到这个子 Agent 的完整定义visualization_agent Agent( modelGeminiWithLocation(modelconfig.agent_settings.model, ...), namevisualization_agent, descriptionAgent specialized in creating interactive and static visualizations., instructionload_prompt(os.path.dirname(__file__), visualization_agent.txt), tools[execute_visualization_code, load_artifacts], generate_content_configgenai.types.GenerateContentConfig( max_output_tokensconfig.VISUALIZATION_AGENT_MAX_OUTPUT_TOKENS, ), )它只挂载两个工具execute_visualization_code执行绘图代码和load_artifacts读取 Artifact并通过sub_agents[visualization_agent]挂到根 Agent 之下。其专属提示词 visualization_agent.txt 定义了它的两条铁律必须把图表对象赋值给名为fig的变量否则工具会直接返回ERROR: The code did not assign a chart object to the fig variable.不要在代码里自行调用fig.write_html/fig.savefig保存文件保存与 Artifact 注入由工具自动完成。该子 Agent 支持两种出图方式对应execute_visualization_code的chart_type参数在 visualization_tools.py 中有明确分支Plotlychart_typeplotly生成交互式 HTML 图表fig.to_html(include_plotlyjscdn, full_htmlFalse)后以text/htmlMIME 类型保存。注意提示词中特别警告Gemini Enterprise 环境不接受原始 HTML Artifact此时不应使用该方式。Matplotlibchart_typematplotlib生成静态 PNG 图片通过plt.savefig(buf, formatpng)写入内存缓冲区以image/pngMIME 类型保存。提示词要求在 Gemini Enterprise 交互或用户明确要图片/PNG 时始终优先使用 Matplotlib。SKILL.md 之所以在后续步骤中强调image/png正是因为最终 HTML 报告需要把图表作为img内嵌资源静态 PNG 是最稳妥的载体。无论哪种类型工具都会同时做两件事visualization_tools.py把文件写入本地output/目录便于预览并以tool_context.save_artifact(...)注册为 ADK ArtifactArtifact ID 由文件名中的.替换为_得到如chart.png→chart_png。图表生成后子 Agent 会返回内部 Artifact 的名称/ID交给根 Agent。Step 3取回 ArtifactRetrieve Artifact图表作为内部 Artifact 存入会话内存后根 Agent 需要使用load_artifacts工具按 Artifact ID 取回原始字节。load_artifacts是 ADK 自带工具from google.adk.tools import load_artifacts它从会话的 Artifact 服务中读取文件内容——该服务可以是内存实现InMemoryArtifactService也可以是生产环境的持久化实现。这一步的产出是图表的原始字节流为下一步发布到 GCS 做准备。提示在 tests/integration/test_agent.py 中可以看到测试环境正是用InMemoryArtifactServiceInMemorySessionService组装 Runner 来验证 Agent 的完整运行链Artifact 与 Session 的关系由此可窥一斑。Step 4先发布图表依赖到 GCSPublish Dependencies to GCS这是整个工作流中最容易出错的一步SKILL.md 用MUST强调如果最终 HTML 报告要展示图片必须先把图片字节发布出去调用形式为publish_file(content, filename, image/png)调用成功后返回一个公网 URLhttps://storage.googleapis.com/...。其底层实现位于 tools.py 的publish_file关键逻辑如下从config.PUBLIC_ARTIFACT_BUCKET读取目标 GCS Bucket 名若未配置则返回ERROR: PUBLIC_ARTIFACT_BUCKET is not configured...对应配置项定义在 config.py构造对象路径结构为exports/youtube-analyst/YYYYMMDD/session_id/随机6位/filename用日期与会话 ID 分组、用随机串避免冲突通过google.cloud.storage客户端上传blob.upload_from_string同时支持str与bytes返回https://storage.googleapis.com/{bucket}/{path_suffix}形式的公开访问地址。该路径结构意味着同一会话产生的多张图表与最终报告会被归拢到同一目录下方便管理。需要说明的是Bucket 需配置为可公开读取才能保证 URL 直接可访问。Step 5构造 HTMLConstruct HTML拿到图表的公网 URL 后Agent 需要拼装一份干净、排版良好的 HTML 字符串把分析结论与图表整合在一起例如img srchttps://storage.googleapis.com/.../chart.png /SKILL.md 明确警告必须使用 Step 4 获得的公网 URL 嵌入图表绝不使用本地路径Do NOT use local paths。原因很直观本地路径如output/chart.png只在 Agent 运行机器上存在而报告最终要发布为公网 HTML任何本地引用都会导致图片 404。Step 6最终交付二选一Final Delivery Options根据用户诉求Agent 在两种交付方式中选择其一用户诉求调用结果只想保存报告稍后下载render_html(html_content, report.html)保存为内部 Artifact想要一个可分享的链接publish_file(html_content, report.html, text/html)上传到 GCS直接把公网 URL 交给用户两种方式的源码差异体现了内部 / 外部的分界线render_html把 HTML 字符串写入本地output/目录并尝试以text/htmlMIME 注册为会话 ArtifactArtifact 名同样把.替换为_如report_html。它返回的是本地保存路径而非公网链接。publish_file同上文 Step 4以text/html上传到 GCS返回公网 URL。底层调用链Skill 指令如何驱动真实工具把上述六步串起来一次完整的可视化报告会话在源码层面的调用链是用户请求 └─ youtube_analyst (根 Agent, agent.py) ├─ search_youtube / get_video_details / calculate_engagement_metrics # Step 1 取数 ├─ visualization_agent (子 Agent) # Step 2 出图 │ └─ execute_visualization_code(code, chart_type, filename) # 生成 fig → 保存 Artifact ├─ load_artifacts(artifact_id) # Step 3 取回字节 ├─ publish_file(bytes, chart.png, image/png) # Step 4 发布图片 → 公网 URL ├─ 组装 HTML 字符串内嵌公网图 URL # Step 5 成稿 └─ render_html(html, report.html) 或 # Step 6 交付 publish_file(html, report.html, text/html) → 公网 URL其中根 Agent 的工具注册见 agent.pypublish_file、render_html、load_artifacts等均作为根 Agent 的工具直接暴露而execute_visualization_code只暴露给可视化子 Agent职责分离清晰。配置要求与运行前提要让这条发布链路真正跑通需要满足以下前提均以仓库当前实现为准GCS 公开 Bucket在.env中设置PUBLIC_ARTIFACT_BUCKET见 config.py并保证该 Bucket 允许公开读取否则publish_file会直接返回错误提示。Google Cloud 认证publish_file使用storage.Client()默认凭据需要配置好 GCP 应用默认凭据ADC或服务账号config.py 中还涉及GOOGLE_CLOUD_PROJECT、GOOGLE_GENAI_LOCATION等 Vertex AI 相关配置。Gemini 模型与 YouTube API Key根 Agent 与可视化子 Agent 均使用 Gemini 模型默认gemini-3-flash-previewYouTube 数据工具则依赖 YouTube Data API v3 key详见 README.md 的 Onboarding 流程。运行环境安装与启动可参考 README.md 中的make install/make web/make cli通过本地 Web 界面或 CLI 与 Agent 交互。与其它 Skill 的协作发布链路是通用出口visualization-reporting 不是孤立存在的它本质上是整个 YouTube Analyst 各分析类 Skill 的统一交付出口。例如在 abcd-framework-audit Skill 的最后一步明确写着Next Actions: Ask the user if they want to publish this ABCD Audit Report as a shareable HTML asset usingpublish_file.这意味着ABCD 创意审计、竞品洞察、KOL 发现等任何产出结构化结论的 Skill最终都可以把结论交给 visualization-reporting 链路包装成带图表的可分享 HTML 报告。这种分析 Skill 产出内容、发布 Skill 统一交付的设计让整个 Agent 的输出始终收敛为两类资产会话内可下载的 Artifact或带公网链接的发布文件。最佳实践小结先内后外、先图后文图表必须先在会话内生成 Artifact再发布为公网 URL最后才能被 HTML 引用顺序颠倒会导致报告出现死链。图片一律用公网 URL 内嵌HTML 报告中永远不要出现output/之类的本地路径。按交付场景选工具只要可分享链接就用publish_file只要会话内保存就用render_html不要混用。出图方式与环境匹配Gemini Enterprise 等不支持 HTML Artifact 的环境下可视化子 Agent 应回退到 Matplotlib 生成 PNG。代码生成保持最小化让子 Agent 只负责构造fig对象保存与上传交给工具层避免在生成代码中自行处理文件 I/O 引入不稳定因素。这套模式的价值在于它以一份不足 20 行的 Skill 指令撬动了多 Agent 委托 → 代码执行 → Artifact 管理 → 对象存储发布的完整链路是 ADK 中Skill 编排 工具组合 云发布三者结合的典型范例。开发者可以直接参考 visualization-reporting/SKILL.md 的写法为自有 Agent 定制同样可发布、可分享的报告输出能力。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考