Hub documentation

智能体

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

智能体

Hugging Face 提供了将 AI 智能体直接连接到 Hub 的工具和协议。无论您是在与 Claude 聊天、使用 Codex 进行开发，还是在构建自定义智能体，都可以访问模型、数据集、Spaces 以及社区工具。本页介绍如何将您的聊天智能体和编码智能体连接到 Hub。

页面	描述
命令行界面	为您的智能体配备内置 Skill 的 `hf` CLI
MCP 服务器	将任何兼容 MCP 的客户端连接到 Hub
技能	面向 AI/ML 工作流的特定任务指南
SDK	使用 Python 或 JavaScript 以编程方式构建智能体
本地智能体	使用 llama.cpp 和 Pi 运行完全本地化的智能体
Agent 轨迹	在 Hub 上查看 Claude Code、Codex 和 Pi 会话

与 Hugging Face 对话

使用模型上下文协议（MCP）将您的 AI 助手直接连接到 Hugging Face Hub。连接后，您可以在聊天界面中搜索模型、探索数据集、生成图像并使用社区工具。

支持的助手

HF MCP Server 可与任何兼容 MCP 的客户端配合使用：

ChatGPT（通过插件）
Claude Desktop
自定义 MCP 客户端

设置

1. 打开 MCP 设置

MCP Settings Example

在登录状态下访问 huggingface.co/settings/mcp。

2. 选择您的客户端

从列表中选择您的 MCP 兼容客户端。页面会显示针对该客户端的具体说明以及可直接复制的配置代码片段。

3. 配置并重启

将配置片段复制到客户端的 MCP 设置中，保存并重启客户端。

设置页面会生成客户端所需的精确配置。请使用该页面，而不是手动编写配置。

你可以做什么

连接成功后，请让您的助手使用您在配置中选择的 Hugging Face 工具：

任务	示例提示
搜索模型	“在 Hugging Face 上查找 Qwen 3 量化模型”
探索数据集	“显示有关天气时间序列的数据集”
查找 Spaces	“查找一个可以转录音频文件的 Space”
生成图像	“创建一张 1024x1024 的吉卜力风格猫咪图像”
搜索论文	“查找有关视觉-语言模型的近期论文”

您的助手会调用 Hugging Face 服务器暴露的 MCP 工具，并返回包含元数据、链接和上下文的结果。

添加社区工具

使用兼容 MCP 的 Gradio Spaces 扩展您的配置：

浏览支持 MCP 的 Spaces
在您的 MCP 设置中添加它们
重启客户端以获取新工具

Gradio MCP 应用会将其函数暴露为带有参数和描述的工具，因此您的助手可以直接调用它们。

了解更多

MCP 服务器指南 - 详细的设置和配置
HF MCP 设置 - 配置您的客户端
兼容 MCP 的 Spaces - 社区工具

编码智能体

通过 MCP Server 和 Skills 将 Hugging Face 集成到您的编码工作流中。您可以直接从 IDE 或编码代理访问模型、数据集和机器学习工具。例如，我们介绍了以下编码代理以及其他更多支持 MCP 和/或 Skills 的代理：

编码智能体	集成方法
Claude Code	MCP 服务器 + 技能
OpenAI Codex	MCP 服务器 + 技能
Open Code	MCP 服务器 + 技能
Cursor	MCP 服务器 + 技能
VS Code	MCP 服务器
Gemini CLI	MCP 服务器
Zed	MCP 服务器

快速设置

MCP 服务器

MCP Server 让您的编码代理能够访问 Hub 搜索、Spaces 以及社区工具。

Cursor / VS Code / Zed：

访问 huggingface.co/settings/mcp
从列表中选择您的 IDE
复制配置代码片段
将其添加到您的 IDE 的 MCP 设置中
重启 IDE

Claude Code：

claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"

技能

Skills 为 AI/ML 工作流提供任务特定的指导。它们可以与 MCP 配合使用，也可以独立运行。

# start claude 
claude

# install the skills marketplace plugin
/plugin marketplace add huggingface/skills

然后，要安装 Skill 规范：

/plugin install hf-cli@huggingface-skills

请参阅技能指南了解可用技能及其用法。

你可以做什么

配置完成后，您的编码代理可以：

功能	示例
搜索 Hub	“查找一个参数量小于 7B 的代码生成模型”
生成图像	“创建一个 Transformer 架构的示意图”
探索数据集	“有哪些可用于情感分析的数据集？”
运行 Spaces	“使用 Whisper Space 转录此音频文件”
获取文档	“如何使用 transformers 微调模型？”

环境配置

身份验证

将您的 Hugging Face 令牌设置为环境变量：

export HF_TOKEN="hf_..."

或通过 CLI 进行身份验证：

hf auth login

添加社区工具

使用兼容 MCP 的 Gradio Spaces 扩展您的配置：

浏览支持 MCP 的 Spaces
在您的 MCP 设置中添加它们
重启您的 IDE

示例工作流

You: Find a text classification model that works well on short texts

Agent: [Searches Hugging Face Hub]
       Found several options:
       - distilbert-base-uncased-finetuned-sst-2-english (sentiment)
       - facebook/bart-large-mnli (zero-shot)
       ...

You: Show me how to use the first one

Agent: [Fetches documentation]
       Here's how to use it with transformers:
       
       from transformers import pipeline
       classifier = pipeline("sentiment-analysis", 
                            model="distilbert-base-uncased-finetuned-sst-2-english")
       result = classifier("I love this product!")

注册您的智能体框架

Hugging Face 维护着一个公开的 agent harness 注册表，其中收录了与 Hub 交互的编码 agent 和工具（如 Claude Code、Codex、Cursor 等）。当 huggingface_hub 检测到自身运行在已注册的 harness 中时，会通过 Hub 请求中的 user agent 上报该信息。注册您的 harness 意味着这些活动将以您的工具名称进行归属，并为您的项目提供友好的显示标签、指向您的文档和仓库的链接，以及在公开的 agent 使用数据集中占有一席之地——未注册的工具仅会被计入其汇总的 unknown 份额中。

要注册一个 harness，请提交一个 Pull Request，在 @huggingface/tasks 包中向 agent-harnesses.ts 添加一个条目：

harness id（条目键）应使用小写字母并以连字符分隔（示例："claude-code"）。
将 prettyLabel 设置为用户友好的大小写格式（例如：Claude Code）。
（可选）将 repoUrl 设置为指向测试框架源代码的链接（通常是 GitHub 仓库）。
（可选）将 docsUrl 设置为指向 harness 文档或网站的链接。
（可选）使用description设置对测试框架的简短单行说明。
定义如何从环境中检测您的 harness：
- 如果您的测试框架设置了标准环境变量之一（AI_AGENT 或 AGENT），其值将直接用作标识符，无需额外配置。
- 否则，将 envVars 设置为将环境变量名称映射到值模式。使用 "*" 匹配任意非空值，使用精确字符串进行精确匹配，或使用 "<prefix>*" 进行前缀匹配。

就是这样！一旦 PR 被合并，来自您的 agent harness 的 huggingface_hub 流量（包括 hf CLI）将以名称形式归因于它，并在下个月的更新中出现在 agent 使用数据集中。

后续步骤

CLI - 用于 Hub 操作的命令行界面
MCP 服务器 - 将任何兼容 MCP 的 AI 助手连接到 Hub
技能 - 为编码智能体预构建的能力
SDK - 用于构建智能体的 Python 和 JavaScript 库

Update on GitHub

←智能体 Hugging Face AI 智能体 CLI→