agent-usage

该数据集追踪通过HuggingFace Hub官方Python库（包括huggingface_hub库和hf CLI）访问Hub的各类AI智能体工具的使用情况。当智能体工具（例如Claude Code、Codex、Cursor等）在User-Agent中通过注册机制声明agent/<name>标识后，其向Hub发起的请求会被统计并汇总。数据集以月度（monthly）和日度（daily）两种粒度发布，记录了每个已注册智能体在对应时间段内的请求份额（pct_requests）和用户份额（pct_users），其中unknown类别表示检测到agent令牌但未注册名称的请求。数据可用于分析智能体生态的发展趋势、比较不同工具的使用强度（通过请求份额与用户份额的差异）、观察日度波动模式（如工作日与周末的差异、新工具发布后的增长曲线）等。需要注意的是，该数据仅反映通过Python库访问Hub的流量，不包含直接HTTP API调用；份额计算为零和游戏，且建议从2026年5月开始进行有意义的月度比较，以避免早期检测机制逐步推广带来的偏差。This dataset tracks the usage of various AI Agent tools accessing the HuggingFace Hub via its official Python libraries, including the `huggingface_hub` library and the `hf` CLI. When AI Agent tools (e.g., Claude Code, Codex, Cursor, etc.) declare the `agent/<name>` identifier via the registration mechanism in their User-Agent strings, their requests sent to the Hub will be counted and aggregated. The dataset is released at two granularities: monthly and daily. It records the request share (`pct_requests`) and user share (`pct_users`) of each registered AI Agent during the corresponding time period. The `unknown` category refers to requests where an agent token is detected but no registered name is found. This data can be used to analyze the development trends of the AI Agent ecosystem, compare the usage intensity of different tools via the discrepancy between request share and user share, and observe daily fluctuation patterns such as differences between weekdays and weekends, growth curves following the release of new tools, among other analytical scenarios. It should be noted that this data only reflects traffic accessing the Hub via Python libraries, and does not include direct HTTP API calls; share calculations follow a zero-sum framework. It is recommended to conduct meaningful monthly comparisons starting from May 2026 to avoid biases introduced by the gradual rollout of early detection mechanisms.

原始信息汇总

数据集概述：Hugging Face Hub 上 Agent 使用情况

该数据集记录了通过 huggingface_hub 库（包括 hf CLI）发起的、带有 agent/<名称> 用户代理标识的请求在各个工具（harness）之间的流量分布情况。数据按月（monthly）和按日（daily）更新，由定期的 HF Job 生成。

数据内容与结构

• 主要关注点：展示了不同编码代理（如 Claude Code、Codex、Cursor 等）在 Hugging Face Hub 上的请求份额和用户份额。
• 数据配置：
  • monthly：默认配置，提供每月的数据汇总（Parquet 文件位于 data/monthly/*.parquet）。
  • daily：按日计的数据配置，可捕捉月度数据平滑掉的细节，如发布峰值、增长曲线和周末模式（Parquet 文件位于 data/daily/*.parquet）。
• 数据列：
  • month / day：指标计算的时间周期。
  • agent：工具名称（从 agent/<名称> 令牌中提取）；unknown 表示令牌存在但未注册。
  • pct_requests：该工具在周期内发起的、带有代理标识的 huggingface_hub 请求的百分比（0-100，每周期总和为 100）。
  • pct_users：同上，但针对不同的已验证用户。同一用户使用两个不同工具时，会被分别计数。

如何使用

• 浏览与过滤：通过页面顶部的“数据集查看器”可直接浏览、排序和过滤表格。
• 程序加载：
  • Python: from datasets import load_dataset，使用 load_dataset("huggingface/agent-usage", "monthly", split="train")。
  • DuckDB: SELECT ... FROM hf://datasets/huggingface/agent-usage/data/monthly/*.parquet ...
  • Polars: pl.scan_parquet("hf://datasets/huggingface/agent-usage/data/daily/*.parquet")
• 数据更新：新月份的数据会以新的 Parquet 文件追加，因此查询始终返回完整的未更改历史记录。

关键注意事项

• 衡量范围：该数据集衡量的是 Hugging Face Hub 的使用情况，而非 Agent 的整体流行度。一款很少与 Hub 交互的工具其排名会较低。
• 份额变化解读：份额是零和的。份额下降不代表使用量下降，总流量在增长时，某工具请求量翻倍但份额仍可能缩小。
• 有效分析起点：建议从 2026 年 5 月开始进行月度比较，因为 agent/ 令牌于 2026 年 4 月 3 日推出，4 月数据反映了推出过程而非相对使用情况。
• 日数据平滑：建议对每日份额进行 7 日滚动平均处理，以消除周末和小样本量带来的噪音。
• 数据来源：归属是自行声明的（由客户端库设置的用户代理令牌），且仅涵盖 Python 库的流量。直接向 Hub API 发起的 HTTP 调用不被统计。
• 工具注册：如果构建的工具未在 agent-harnesses.ts 中注册，其请求将被归类为 unknown。可通过提交 Pull Request 完成注册。

搜集汇总

数据集介绍

构建方式

该数据集由Hugging Face平台通过自动化流水线构建而成，其核心数据源自用户通过`huggingface_hub`库（包括`hf`命令行工具）发起的API请求。每次请求携带的`agent/<name>`用户代理标识符被捕获并解析，以识别具体所使用的智能体工具。数据按照月度与日度两种频率进行聚合，以Parquet格式存储于相应目录，并通过定期的Hugging Face Job任务自动更新，确保信息时效性。仅有通过Python库发出的请求才被纳入统计，直接调用Hub API的流量不予记录。新数据以追加文件形式发布，保障历史序列的完整性。

使用方法

用户可通过Hugging Face Datasets库便捷加载数据，例如指定`monthly`或`daily`配置获取相应训练集切片。数据分析场景下，推荐结合DuckDB或Polars等工具直接查询远程Parquet文件，实现高效交互。对于日度数据，建议采用7日滚动均值进行平滑处理，以消除单日噪音。由于`agent/`标识于2026年4月3日才正式部署，跨月比较宜从同年5月开始，从而规避早期数据包含的部署过渡效应。注册新工具需通过向`agent-harnesses.ts`文件提交拉取请求完成，无需发布新版本即可在次日生效并出现在下一轮快照中。

背景与挑战

背景概述

随着大语言模型与代码代理技术的深度融合，以Claude Code、Codex、Cursor为代表的编程代理系统迅速崛起，它们通过Hugging Face Hub获取模型、构建数据集、训练模型并部署应用空间，形成了海量自动化交互流量。agent-usage数据集由Hugging Face团队于2026年发布，旨在通过追踪`huggingface_hub`库中携带的`agent/<name>`标识符，系统性记录不同代理框架对Hub的调用份额。该数据集聚焦的核心研究问题是：如何量化并可视化多代理生态中各类工具的真实使用模式，为代理开发者、平台运营者及研究者提供公开、透明的流量分布数据。作为首个聚焦代理流量的公开数据集，它填补了LLM代理行为可观测性的空白，对理解代理系统的实际生态格局和演进趋势具有重要参考价值。

当前挑战

该数据集所解决的领域挑战在于：代理系统的流量分布长期处于黑箱状态，缺乏标准化、可复现的度量方法以评估不同代理框架的真实影响力与用户行为特征。传统API监控手段难以区分人工与自动化请求，且代理间使用模式差异巨大——有的代理占用少量用户却产生大量请求，有的则相反，亟需细粒度的份额与用户双重指标。构建过程中面临多重技术挑战：首先，代理标识依赖开发者主动注册，未注册工具被归为`unknown`，导致部分流量归属模糊；其次，仅追踪Python `huggingface_hub`库流量，无法覆盖直接HTTP调用或非Python生态的代理；再者，份额为零和博弈——总流量快速增长时，单项份额下降未必反映真实使用减少，需结合绝对请求量综合解读。此外，早期数据受标识上线时间差异干扰，需谨慎处理滚雪球式的数据分布变化。

常用场景

经典使用场景

在人工智能与开源生态深度融合的背景下，智能代理（Agent）作为连接用户与模型仓库的桥梁，其行为模式正逐步成为理解开发者协作生态的关键窗口。agent-usage数据集通过对Hugging Face Hub上经由huggingface_hub库发起的请求进行细粒度追踪，按月度与日度两个时间尺度，系统性地发布了各命名代理框架的请求份额与独立用户占比。研究者可借此揭示不同代理框架在市场中的分布格局，追踪新兴工具的冷启动扩散曲线，并探测工作日与周末的流量周期性波动。该数据集为量化分析代理工具的采纳率、持久性及用户行为异质性提供了标准化的数据底座。

解决学术问题

该数据集直面学术界与工业界在高动态开源平台中代理流量监测上的数据匮乏困境。传统研究多依赖间接的软件仓库提交记录或社区调查问卷，难以实时、无偏地反映代理工具的真实使用强度。agent-usage通过官方管道自动采集并聚合代理标识符，解决了代理使用强度与用户分布难以精确量化的问题，使得研究者能够实证检验代理工具的活跃度变化趋势、用户集中度与工具替代效应等学术假说。其影响在于，它填补了智能化编程工具生态实证研究的空白，为软件工程、人机交互及开源经济学领域提供了全新的可复现分析路径。

实际应用

在实际工业界与开源社区治理中，agent-usage数据集具有鲜明的应用价值。模型与平台运营者可依据代理份额的月度变迁，识别主流与冷门交互工具，从而调整API设计与服务优化优先级；代理框架的开发者可对比自身工具的用户活跃度与请求密度，定位功能瓶颈或用户采纳障碍。此外，该数据还可用于构建代理工具的市场表现仪表盘，辅助投资机构与技术社区研判生态演化方向。Hugging Face自身亦借助此数据对代理注册机制进行动态调整，实现对未登记流量的追溯与召回，提升数据治理的透明度与完整性。

数据集最近研究

最新研究方向

在人工智能代理（AI agent）生态蓬勃发展的当下，Hugging Face Hub作为模型与数据集的枢纽，正成为编码代理（coding agent）大规模交互的前沿阵地。该数据集首次系统性地量化了Claude Code、Codex、Cursor等主流代理框架对Hub的调用行为，揭示了不同代理在请求量与用户规模上的差异化使用模式。这一研究方向不仅为代理系统的负载均衡与资源调度提供了实证依据，更通过公开的月度与日度份额数据，为代理生态的竞争格局与演化动态——如新工具发布引发的流量剧变、工作日内的高频交互节律——绘制了精细的时间图谱。其深远意义在于，它将分散的代理行为沉淀为可复现的社区标准，推动代理基础设施从经验驱动迈向数据驱动的新阶段。