Hub上的智能体
本文汇总了 Hugging Face 为 agent 工作流提供的全部库与工具 ：
- HF MCP Server：将兼容 MCP 的 AI 助手直接连接到 Hugging Face Hub。
tiny-agents：一个轻量级的 MCP agent 工具包，同时支持 JS（@huggingface/tiny-agents）和 Python（huggingface_hub）。Gradio MCP Server：可以快速从 Gradio 应用和 Spaces 创建 MCP 服务器。smolagents：一个 Python 库，只需几行代码就能运行强大的 agents。
HF MCP Server
官方的 Hugging Face MCP（Model Context Protocol）Server 可以让任意兼容 MCP 的 AI 助手（包括 VSCode、Cursor、Claude Desktop 等）与 Hugging Face Hub 无缝集成。
借助 HF MCP Server，你可以通过直接连接 Hub 生态来增强 AI 助手的能力。它内置了：
- 一组精选的内置工具，例如 Spaces、论文语义搜索、模型和数据集浏览等
- 支持 MCP 的 Gradio 应用：可以连接社区中任何 MCP 兼容的 Gradio 应用
开始使用
访问 huggingface.co/settings/mcp 配置 MCP 客户端并开始使用。你也可以查看专门的一页指南：HF MCP Server。
此功能目前仍处于实验阶段 ⚗️，未来会持续演进。
tiny-agents (JS and Python)
NEW：tiny-agents 现已支持 AGENTS.md 标准。🥳
tiny-agents 是一个轻量级工具包，用于在 Hugging Face Inference Client 与 Model Context Protocol（MCP）之上运行和构建 MCP agents。它同时以 JS 包 @huggingface/tiny-agents 和 huggingface_hub Python 包的形式提供。
@huggingface/tiny-agents (JS)
@huggingface/tiny-agents 提供了一个简单直接的 CLI 和简洁的编程接口，用于在 JS 中运行和构建 MCP agents。
开始使用
首先安装依赖包：
npm install @huggingface/tiny-agents
# or
pnpm add @huggingface/tiny-agents
然后，你可以运行你的 agent：
npx @huggingface/tiny-agents [command] "agent/id"
Usage:
tiny-agents [flags]
tiny-agents run "agent/id"
tiny-agents serve "agent/id"
Available Commands:
run Run the Agent in command-line
serve Run the Agent as an OpenAI-compatible HTTP server
你可以 直接从 tiny-agents 数据集加载 agents，或指定你自己本地 agent 配置的路径。
高级用法
除了 CLI，你还可以使用 Agent 类进行更细粒度的控制。对于低级交互，使用 @huggingface/mcp-client 包中的 MCPClient 直接连接到 MCP 服务器并管理工具调用。
在 huggingface.js 文档 中了解更多关于 tiny-agents 的信息。
huggingface_hub (Python)
huggingface_hub 库是在 Python 中运行 MCP 驱动的 agents 的最简单方法。它包括高级 tiny-agents CLI 以及通过 Agent 和 MCPClient 类进行编程访问 - 所有这些都构建为与 Hugging Face 推理提供商、本地 LLM 或任何与 OpenAI API 规范兼容的推理端点一起工作。
开始使用
安装支持 MCP 的最新版本：
pip install "huggingface_hub[mcp]>=0.32.2"
然后，你可以运行你的 agent：
> tiny-agents run --help
Usage: tiny-agents run [OPTIONS] [PATH] COMMAND [ARGS]...
Run the Agent in the CLI
╭─ Arguments ───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ path [PATH] Path to a local folder containing an agent.json file or a built-in agent stored in the 'tiny-agents/tiny-agents' Hugging Face dataset │
│ (https://huggingface.co/datasets/tiny-agents/tiny-agents) │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
╭─ Options ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ --help Show this message and exit. │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
CLI 会拉取配置，连接到其 MCP 服务器，打印可用工具，然后等待你的提示。
高级用法
要进行更细粒度的控制，请直接使用 MCPClient。此低级接口扩展了 AsyncInferenceClient，允许 LLM 通过模型上下文协议（MCP）调用工具。它支持本地（stdio）和远程（http/sse）MCP 服务器，处理工具注册和执行，并实时将结果流式传输回模型。
在 huggingface_hub MCP 文档 中了解更多信息。
自定义 Agents
要创建你自己的 agent，只需创建一个文件夹（例如 my-agent/）并在 agent.json 文件中定义你的 agent 配置。
以下示例显示了一个配置为通过 Nebius 推理提供商使用 Qwen/Qwen2.5-72B-Instruct 模型的网页浏览 agent，它配备了 playwright MCP 服务器，使其能够使用 Web 浏览器
{
"model": "Qwen/Qwen2.5-72B-Instruct",
"provider": "nebius",
"servers": [
{
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
]
}
要使用本地 LLM（例如 llama.cpp 或 LM Studio），只需提供 endpointUrl：
{
"model": "Qwen/Qwen3-32B",
"endpointUrl": "http://localhost:1234/v1",
"servers": [
{
"type": "stdio",
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
]
}
可选地，添加 PROMPT.md 来自定义系统提示。
不要犹豫，通过在 tiny-agents Hugging Face 数据集中打开 Pull Request 来为社区贡献你的 agent。
Gradio MCP Server / Tools
你可以用 Gradio 仅用几行 Python 代码构建 MCP 服务器。如果你有一个现有的 Gradio 应用或 Space 想要用作 MCP 服务器/工具，只需一行更改。
要使 Gradio 应用成为 MCP 服务器，只需在启动演示时传入 mcp_server=True，如下所示。
# pip install gradio
import gradio as gr
def generate_image(prompt: str):
"""
Generate an image based on a text prompt
Args:
prompt: a text string describing the image to generate
"""
pass
demo = gr.Interface(
fn=generate_image,
inputs="text",
outputs="image",
title="Image Generator"
)
demo.launch(mcp_server=True)
MCP 服务器将在你的应用提供服务的 http://your-space-id.hf.space/gradio_api/mcp/sse 处可用。它将有一个对应于你 Gradio 应用中每个函数的工具，工具描述自动从你的函数的文档字符串生成。
最后，将此添加到你选择的 MCP 客户端（例如 Cursor）的设置中。
{
"mcpServers": {
"gradio": {
"url": "http://your-server:port/gradio_api/mcp/sse"
}
}
}
这非常强大，因为它让 LLM 可以将任何 Gradio 应用用作工具。你可以在 Spaces 上找到数千个这样的应用。了解更多信息请参阅此处。
smolagents
smolagents 是一个轻量级库，只需几行代码即可涵盖所有 agent 用例，从代码编写 agents 到计算机使用。它与模型无关，支持使用 Hugging Face Transformers 提供的本地模型，以及通过推理提供商提供的模型和专有模型提供商。
它提供了一种独特的 agent：CodeAgent，一个用 Python 代码编写其操作的 agent。
它还支持标准 agent，该 agent 像大多数其他 agent 框架一样在 JSON blob 中编写操作，称为 ToolCallingAgent。
要了解更多关于在代码与 JSON 中编写操作的信息，请查看我们在 DeepLearning.AI 上的新短期课程。
如果你想避免自己定义 agents，启动 agent 的最简单方法是通过 CLI，使用 smolagent 命令。
smolagent "Plan a trip to Tokyo, Kyoto and Osaka between Mar 28 and Apr 7." \
--model-type "InferenceClientModel" \
--model-id "Qwen/Qwen2.5-Coder-32B-Instruct" \
--imports "pandas numpy" \
--tools "web_search"
Agents 可以推送到 Hugging Face Hub 作为 Spaces。查看人们构建的所有很酷的 agents 此处。
smolagents 还支持 MCP 服务器作为工具，如下所示：
# pip install --upgrade smolagents mcp
from smolagents import MCPClient, CodeAgent
from mcp import StdioServerParameters
import os
server_parameters = StdioServerParameters(
command="uvx", # 使用 uvx 确保依赖可用
args=["--quiet", "[email protected]"],
env={"UV_PYTHON": "3.12", **os.environ},
)
with MCPClient(server_parameters) as tools:
agent = CodeAgent(tools=tools, model=model, add_base_tools=True)
agent.run("Please find the latest research on COVID-19 treatment.")
在文档中了解更多信息。