Hugging Face 的 LOGO

Hub 文档

Hub 上的智能体

Hugging Face's logo
加入 Hugging Face 社区

并获得增强的文档体验

开始使用

Hub 上的智能体

此页面汇集了 Hugging Face 为智能体工作流程提供的所有库和工具。

  • HF MCP 服务器: 将您的 MCP 兼容 AI 助手直接连接到 Hugging Face Hub。
  • tiny-agents: 一个轻量级的 MCP 驱动智能体工具包，提供 JS (@huggingface/tiny-agents) 和 Python (huggingface_hub) 版本。
  • Gradio MCP 服务器: 轻松地从 Gradio 应用和 Spaces 创建 MCP 服务器。
  • smolagents: 一个 Python 库，使您能够用几行代码运行强大的智能体。

HF MCP 服务器

官方的 Hugging Face MCP (模型上下文协议) 服务器 实现了 Hugging Face Hub 与任何 MCP 兼容 AI 助手（包括 VSCode、Cursor 和 Claude Desktop）之间的无缝集成。

通过 HF MCP 服务器，您可以直接连接到 Hub 的生态系统，从而增强 AI 助手的性能。它包含：

  • 一套精选的内置工具，如 Spaces 和论文语义搜索、模型和数据集探索等。
  • MCP 兼容的 Gradio 应用：连接到 Hugging Face 社区构建的任何MCP 兼容 Gradio 应用。

入门

请访问huggingface.co/settings/mcp来配置您的 MCP 客户端并开始使用。

此功能处于实验阶段 ⚗️ 并将持续发展。

smolagents

smolagents 是一个轻量级库，用于以少量代码行涵盖所有智能体用例，从代码编写智能体到计算机使用。它与模型无关，支持使用 Hugging Face Transformers 提供的本地模型，以及通过推理提供商提供的模型和专有模型提供商。

它提供了一种独特的智能体：CodeAgent，它是一个用 Python 代码编写其动作的智能体。它还支持大多数其他智能体框架那样以 JSON blob 编写动作的标准智能体，称为ToolCallingAgent。要了解有关在代码与 JSON 中编写动作的更多信息，请查看我们在DeepLearning.AI 上的新短期课程。

如果您想避免自己定义智能体，启动智能体最简单的方法是通过 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"

智能体可以作为 Spaces 推送到 Hugging Face Hub。在此处查看人们构建的所有酷炫智能体。

smolagents 还支持 MCP 服务器作为工具，如下所示：

# pip install --upgrade smolagents mcp
from smolagents import MCPClient, CodeAgent
from mcp import StdioServerParameters
import os

server_parameters = StdioServerParameters(
    command="uvx",  # Using uvx ensures dependencies are available
    args=["--quiet", "pubmedmcp@0.1.3"],
    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.")

在文档中了解更多信息。

tiny-agents (JS 和 Python)

tiny-agents 是一个轻量级工具包，用于在 Hugging Face Inference Client + 模型上下文协议 (MCP) 的基础上运行和构建 MCP 驱动的智能体。它以 JS 包 @huggingface/tiny-agents 和 huggingface_hub Python 包的形式提供。

@huggingface/tiny-agents (JS)

@huggingface/tiny-agents 包提供了一个简单直接的 CLI 和一个简单的编程 API，用于在 JS 中运行和构建 MCP 驱动的智能体。

入门指南

首先，您需要安装该软件包

npm install @huggingface/tiny-agents
# or
pnpm add @huggingface/tiny-agents

然后，您可以运行您的智能体

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数据集加载智能体，或者指定您自己的本地智能体配置的路径。

高级用法 除了 CLI，您还可以使用 Agent 类进行更精细的控制。对于更低级别的交互，请使用 @huggingface/mcp-client 包中的 MCPClient 直接连接到 MCP 服务器并管理工具调用。

在huggingface.js 文档中了解有关 tiny-agents 的更多信息。

huggingface_hub (Python)

huggingface_hub 库是在 Python 中运行 MCP 驱动智能体最简单的方法。它包括一个高级 tiny-agents CLI 以及通过 Agent 和 MCPClient 类进行编程访问——所有这些都旨在与 Hugging Face Inference Providers、本地 LLM 或任何与 OpenAI API 规范兼容的推理端点一起使用。

快速入门

安装支持 MCP 的最新版本

pip install "huggingface_hub[mcp]>=0.32.2"

然后，您可以运行您的智能体

> 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 文档中了解更多信息：huggingface_hub MCP 文档。

自定义智能体

要创建您自己的智能体，只需创建一个文件夹（例如，my-agent/），并在 agent.json 文件中定义您的智能体的配置。以下示例展示了一个网络浏览智能体，该智能体配置为通过 Nebius 推理提供商使用 Qwen/Qwen2.5-72B-Instruct 模型，并且它配备了一个 playwright MCP 服务器，使其可以使用网络浏览器。

{
	"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": "https://:1234/v1",
	"servers": [
		{
			"type": "stdio",
			"command": "npx",
			"args": ["@playwright/mcp@latest"]
		}
	]
}

（可选）添加 PROMPT.md 以自定义系统提示。

不要犹豫，通过在tiny-agents Hugging Face 数据集中打开拉取请求，将您的智能体贡献给社区。

Gradio MCP 服务器/工具

您只需几行 Python 代码即可使用 Gradio 构建 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上找到数千个这样的应用程序。在此处了解更多信息。

< > 在 GitHub 上更新

←JFrog 内容审核→