Hive 生产级 AI 智能体中的 YouTube 数据工具：YouTube Data API v3 MCP 工具集实战指南

Hive 生产级 AI 智能体中的 YouTube 数据工具：YouTube Data API v3 MCP 工具集实战指南

【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址: https://gitcode.com/gh_mirrors/hive48/hive

本指南围绕 Hive 仓库中 Aden Tools 的 youtube_tool 展开，完整讲解如何在生产级 AI 智能体（Agent）中通过 MCP（Model Context Protocol）工具搜索 YouTube 视频、获取视频/频道统计信息、浏览播放列表等公开数据。读完本文，你将掌握该工具集的 8 个工具的注册方式、全部参数语义、凭证配置链路、配额成本模型与错误处理机制，并能在自己的 Agent 流程中直接组合使用。

工具集概述

youtube_tool提供对 YouTube 公开数据的全面访问能力，覆盖视频搜索、频道统计、播放列表与详细元数据。当 Agent 需要检索 YouTube 内容、分析视频数据、获取频道信息或舆情评论时，即可调用本工具集。

其底层封装的是 YouTube Data API v3（官方 REST 接口），所有工具统一通过 API Key 认证，返回遵循官方 v3 Schema 的 JSON 数据。核心实现位于 youtube_tool.py，对外暴露统一的register_tools(mcp, credentials)注册函数，包入口见init.py。

工具清单

官方 README 中登记的 6 个核心工具如下：

工具	说明
youtube_search_videos	按关键词搜索视频，支持多种排序方式
youtube_get_video_details	获取单个（或多个）视频的详细信息
youtube_get_channel_info	获取频道统计信息与资料
youtube_list_channel_videos	列出某频道的视频列表
youtube_get_playlist_items	获取播放列表中的视频
youtube_search_channels	按关键词搜索频道

需要说明的是，从当前仓库源码（youtube_tool.py）看，该模块实际注册的工具为 8 个，其中 README 中的三个工具在源码中的正式名称略有调整，并额外提供了两个评论/分类工具：

源码中的实际工具名	与 README 名称的对应关系
youtube_get_channel	对应 README 的youtube_get_channel_info，且支持 channel_id / username / handle 三种定位方式
youtube_get_playlist	对应 README 的youtube_get_playlist_items，同时返回播放列表元数据与条目
youtube_get_video_details	参数为video_ids，支持逗号分隔最多 50 个视频 ID
youtube_get_video_comments	额外提供，获取视频顶层评论
youtube_get_video_categories	额外提供，获取指定地区的视频分类列表

凭证声明文件 credentials/youtube.py 中登记的 8 个工具名与源码完全一致，印证了上述清单。

环境准备与 API Key 配置

本工具集必须使用 YouTube Data API v3 的 Key。在调用任何工具前，需要完成以下步骤：

1. 在 Google Cloud Console 创建一个项目；
2. 启用 YouTube Data API v3 服务；
3. 创建 API Key（建议将 Key 的使用限制绑定到 YouTube Data API v3 单一服务，降低泄露风险）；
4. 将 Key 写入环境变量YOUTUBE_API_KEY。

在 Hive / Aden Tools 的凭证体系中，YouTube 凭证的定义位于 credentials/youtube.py，其关键属性包括：

• env_var="YOUTUBE_API_KEY"：凭证对应的环境变量名；
• required=True：该凭证为必需项，缺失时工具不可用；
• startup_required=False：启动阶段不强制要求，允许工具注册后按需报错；
• direct_api_key_supported=True：支持直接使用 API Key；
• credential_key="api_key"：存储时以api_key为键；
• health_check_endpoint：指向videoCategories接口，用于健康检查。

从源码的密钥解析逻辑（youtube_tool.py）可以确认凭证读取的优先级：

def _get_api_key(credentials: CredentialStoreAdapter | None) -> str | None: if credentials is not None: return credentials.get("youtube") return os.getenv("YOUTUBE_API_KEY")

即：当工具通过register_tools(mcp, credentials=...)传入凭证适配器时，优先从凭证库读取youtube项；否则回退到环境变量YOUTUBE_API_KEY。若两者均缺失，所有工具会返回如下错误提示（源码 youtube_tool.py）：

{"error": "YOUTUBE_API_KEY not set", "help": "Get an API key at https://console.cloud.google.com/apis/credentials"}

健康检查机制

仓库还提供了凭证健康检查器YouTubeHealthChecker（credentials/health_check.py），它向videoCategories?part=snippet&regionCode=US发送带key参数的请求，用于验证youtube凭证是否有效。在 Aden Tools 的凭证测试流程中，这可以提前发现 Key 失效或配额耗尽的问题。

工具注册链路

youtube_tool通过 FastMCP 的装饰器注册工具。整体注册链路如下：

1. tools/init.py 中导入register_youtube；
2. 在_register_unverified()阶段执行register_youtube(mcp, credentials=credentials)（tools/init.py），即该工具集属于"未验证/社区工具"批次，随 MCP Server 启动时统一注册；
3. MCP Server 入口 tools/mcp_server.py 调用register_all_tools(mcp, credentials=credentials, include_unverified=include_unverified)完成装配。

这意味着只需在mcp_server.py的启动配置中提供可用的 YouTube 凭证，8 个工具便会自动出现在 MCP 目录中，供上层 Agent（如 Queen）通过工具调用直接使用。

工具参数详解

以下参数表完整继承自官方 README，并结合源码（youtube_tool.py）补充了默认值与取值约束。

youtube_search_videos

参数	类型	默认值	说明
query	str	-（必填）	搜索关键词
max_results	int	10	返回结果数，自动钳制在 1–50
order	str	"relevance"	排序方式：date、rating、relevance、title、viewCount
published_after	str	""	按发布时间过滤，RFC 3339 格式，如2024-01-01T00:00:00Z（源码新增参数）
region_code	str	""	地区过滤，ISO 3166-1 alpha-2 国家码，如US、GB、JP（源码新增参数）
video_duration	str	""	时长过滤：short(<4 分钟)、medium(4–20 分钟)、long(>20 分钟)（源码新增参数）
video_type	str	""	类型过滤：episode、movie，留空为不限（源码新增参数）

返回结构为{"query": ..., "results": [...], "total_results": ...}，每条结果包含videoId、title、channelTitle、channelId、publishedAt、description、thumbnail（medium 分辨率）。

youtube_get_video_details

参数	类型	默认值	说明
video_ids	str	-（必填）	视频 ID，可逗号分隔多个（最多 50 个），如"dQw4w9WgXcQ,jNQXAC9IVRw"

内部请求videos接口，part=snippet,contentDetails,statistics。返回的每条视频包含：videoId、title、description、channelTitle、channelId、publishedAt、tags、categoryId、duration（人类可读，如1h2m3s）、duration_raw（ISO 8601 原始值）、viewCount、likeCount、commentCount、thumbnail（high 分辨率）。

youtube_get_channel（对应 README 的 youtube_get_channel_info）

参数	类型	默认值	说明
channel_id	str	""	频道 ID，如UCxxxxxx前缀
username	str	""	旧式 YouTube 用户名（forUsername参数）
handle	str	""	频道句柄（不带 @），如"GoogleDevelopers"（forHandle参数）

三者至少提供一个，否则返回{"error": "Provide one of: channel_id, username, or handle"}。返回字段：channelId、title、description、customUrl、publishedAt、subscriberCount、videoCount、viewCount、thumbnail、uploadsPlaylistId（上传视频的播放列表 ID，便于与youtube_get_playlist联动）。

youtube_list_channel_videos

参数	类型	默认值	说明
channel_id	str	-（必填）	频道 ID
max_results	int	20（README 记为 10，源码默认 20）	结果数，1–50
order	str	"date"	排序：date、viewCount、rating、relevance

底层复用search接口（channelId+type=video），返回{"channel_id": ..., "videos": [...]}，每条含videoId、title、publishedAt、description、thumbnail。

youtube_get_playlist（对应 README 的 youtube_get_playlist_items）

参数	类型	默认值	说明
playlist_id	str	-（必填）	播放列表 ID，如PLxxxxxx前缀
max_results	int	20（README 记为 10，源码默认 20）	条目数，1–50

实现上先请求playlists接口获取元数据，再请求playlistItems获取条目，返回{"playlistId", "title", "description", "channelTitle", "itemCount", "items": [...]}，每条目含videoId、title、position、channelTitle、thumbnail。

youtube_search_channels

参数	类型	默认值	说明
query	str	-（必填）	频道搜索关键词
max_results	int	10	结果数，1–50
order	str	"relevance"	排序：date、viewCount、rating、relevance

底层为search接口（type=channel），返回{"query": ..., "results": [...]}，每条含channelId、title、description、thumbnail。

扩展工具：youtube_get_video_comments

参数	类型	默认值	说明
video_id	str	-（必填）	视频 ID
max_results	int	20	评论数，1–100
order	str	"relevance"	relevance或time

请求commentThreads接口（textFormat=plainText），返回{"video_id": ..., "comments": [...]}，每条含author、text、likeCount、publishedAt、replyCount。

扩展工具：youtube_get_video_categories

参数	类型	默认值	说明
region_code	str	"US"	ISO 3166-1 alpha-2 国家码

请求videoCategories接口，返回{"region_code": ..., "categories": [...]}，每条含id、title。

示例用法

以下示例完整继承自官方 README，并结合源码参数做了增强：

# 搜索视频（按观看量排序） youtube_search_videos( query="Python tutorial", max_results=5, order="viewCount" ) # 按地区与时长过滤搜索（源码新增参数） youtube_search_videos( query="AI agents", max_results=10, region_code="US", video_duration="medium", published_after="2024-01-01T00:00:00Z" ) # 获取视频详情（支持多个 ID） youtube_get_video_details(video_ids="dQw4w9WgXcQ") # 工具链组合：先搜索频道，再列出其视频 channels = youtube_search_channels(query="Fireship", max_results=1) channel_id = channels["items"][0]["id"]["channelId"] videos = youtube_list_channel_videos( channel_id=channel_id, max_results=20, order="date" ) # 获取频道统计信息 youtube_get_channel(channel_id="UCsBjURrPoezykLs9EqgamOA") # 通过句柄定位频道（源码扩展） youtube_get_channel(handle="GoogleDevelopers") # 获取播放列表视频 youtube_get_playlist( playlist_id="PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf", max_results=25 ) # 分析视频评论 youtube_get_video_comments(video_id="dQw4w9WgXcQ", max_results=50)

需要注意：README 示例中youtube_search_channels的返回值写法对应原始 API 的items[0].id.channelId结构；在当前仓库源码实现中，该工具已做了归一化，返回字段为results[0].channelId，实际使用时以results数组取值即可（见 youtube_tool.py）。

响应格式与错误处理

所有工具均返回符合 YouTube Data API v3 Schema 的 JSON：

• 搜索结果：包含items数组，内含视频/频道数据；
• 视频详情：包含snippet（片段）、statistics（统计）、contentDetails（内容详情，含 ISO 8601 时长）；
• 频道信息：同样包含snippet、statistics、contentDetails；
• 错误：统一返回{"error": "message", "help": "..."}结构。

底层错误处理逻辑

所有请求统一经过_request()辅助函数（youtube_tool.py），其行为如下：

• 使用httpx发起 GET 请求，超时时间 30 秒；
• 响应码 403 时解析错误体，若reason == "quotaExceeded"返回中文友好提示：YouTube API quota exceeded. Try again tomorrow or request a quota increase.；其他 403 返回Forbidden: <reason>；
• 非 200 响应截取前 500 字符返回YouTube API error <code>: <body>；
• 请求超时返回Request to YouTube API timed out；
• 其他异常统一包装为YouTube API request failed: <detail>。

由于_request返回的错误始终包含"error"键，各工具在拿到结果后会先做if "error" in data: return data的短路判断，因此 Agent 只需检查返回值中是否存在error字段即可判断调用是否成功。

ISO 8601 时长解析

youtube_get_video_details返回的duration由_parse_duration()将 ISO 8601 时长（如PT1H2M3S）转换为人类可读格式（1h2m3s）。相关测试见 tests/tools/test_youtube_tool.py，覆盖了PT1H2M3S、PT5M、PT30S、空字符串等边界情形。

API 配额成本模型

YouTube Data API v3 默认每日配额为 10,000 单位。每次操作消耗不同单位：

操作	配额成本（单位）
搜索（search）	100
视频详情（videos）	1
频道信息（channels）	1
播放列表条目（playlistItems）	1

在 Agent 设计中这是最需要关注的成本因素：搜索类调用是详情类调用的 100 倍，因此youtube_search_videos、youtube_search_channels、youtube_list_channel_videos三者（均走 search 接口）应谨慎规划调用频率。一个务实的做法是：先用低频的搜索定位目标 ID，再用 1 单位成本的详情/频道接口批量获取元数据。配额使用情况可在 Google Cloud Console 的 YouTube Data API v3 配额页面监控。

另外值得注意的是，配额耗尽时 API 会返回 403 +quotaExceeded，本工具集已将其转换为明确的可读错误，Agent 收到后应停止重试并切换策略（如降级到youtube_transcript_tool的转录能力或等待次日额度恢复）。

测试与验证

仓库为youtube_tool提供了完整的单元测试 tools/tests/tools/test_youtube_tool.py，覆盖以下关键行为：

• 缺失 API Key：清空环境变量后调用返回YOUTUBE_API_KEY相关错误（L22-L26）；
• 空查询校验：query=""返回query is required（L28-L32）；
• 成功搜索：mockhttpx.get返回 200 后，校验结果字段映射正确（L34-L62）；
• max_results 钳制：传入 100 时实际请求参数被钳制为 50（L64-L73）；
• 视频详情：校验统计字段与时长解析（PT1H2M3S→1h2m3s）（L84-L120）；
• 频道查询：无标识符、频道不存在、按 handle 查询成功等分支（L123-L174）；
• 播放列表：缺失 ID 与列表不存在分支（L177-L193）；
• 评论工具：顶层评论字段映射（L196-L233）；
• 时长解析：多组边界用例（L236-L257）。

这些测试既验证了工具对外契约，也可作为二次开发时的行为基准。若要在本地验证，可参考 tools/mcp_server.py 的装配方式，将register_all_tools与凭证适配器一起初始化后直接调用工具函数。

适用前提与限制

• 必须联网：所有工具实时调用 Google 的 YouTube Data API v3，离线环境不可用；
• 必须配置凭证：YOUTUBE_API_KEY环境变量或 Aden Tools 凭证库中的youtube项二选一，且 Key 需已启用 YouTube Data API v3 服务；
• 配额约束：默认 10,000 单位/日，搜索类调用消耗高，需在 Agent 编排中做好成本控制；
• 公开数据边界：本工具集仅能访问公开数据，无法获取受限/私有视频、频道或需要 OAuth 授权的上传、修改等写操作；
• 命名差异提醒：README 中的youtube_get_channel_info、youtube_get_playlist_items在源码中分别对应youtube_get_channel、youtube_get_playlist，集成时以源码实际注册名为准。

参考文档

• 官方工具说明：tools/src/aden_tools/tools/youtube_tool/README.md
• 核心实现：tools/src/aden_tools/tools/youtube_tool/youtube_tool.py
• 凭证声明：tools/src/aden_tools/credentials/youtube.py
• 健康检查器：tools/src/aden_tools/credentials/health_check.py
• 单元测试：tools/tests/tools/test_youtube_tool.py
• 工具装配入口：tools/src/aden_tools/tools/init.py、tools/mcp_server.py
• 配套的免 Key 转录工具：youtube_transcript_tool README

相关接口的官方行为定义可对照 YouTube Data API v3 文档与配额计算说明进行核实。

【免费下载链接】hiveMulti-Agent Harness for Production AI项目地址: https://gitcode.com/gh_mirrors/hive48/hive