Agents on the Hub

This page compiles all the libraries and tools Hugging Face offers for agentic workflows:

tiny-agents: A lightweight toolkit for MCP-powered agents, available in both JS (@huggingface/tiny-agents) and Python (huggingface_hub).
Gradio MCP Server: Easily create MCP servers from Gradio apps and Spaces.
smolagents: a Python library that enables you to run powerful agents in a few lines of code.

smolagents

smolagents is a lightweight library to cover all agentic use cases, from code-writing agents to computer use, in few lines of code. It is model agnostic, supporting local models served with Hugging Face Transformers, as well as models offered with Inference Providers, and proprietary model providers.

It offers a unique kind of agent :CodeAgent, an agent that writes its actions in Python code. It also supports the standard agent that writes actions in JSON blobs as most other agentic frameworks do, called ToolCallingAgent. To learn more about write actions in code vs JSON, check out our new short course on DeepLearning.AI.

If you want to avoid defining agents yourself, the easiest way to start an agent is through the CLI, using the smolagent command.

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 can be pushed to Hugging Face Hub as Spaces. Check out all the cool agents people have built here.

smolagents also supports MCP servers as tools, as follows:

# 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", "[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.")

Learn more in the documentation.

tiny-agents (JS and Python)

tiny-agents is a lightweight toolkit for running and building MCP-powered agents on top of the Hugging Face Inference Client + Model Context Protocol (MCP). It is available as a JS package @huggingface/tiny-agents and in the huggingface_hub Python package.

@huggingface/tiny-agents (JS)

The @huggingface/tiny-agents package offers a simple and straightforward CLI and a simple programmatic API for running and building MCP-powered agents in JS.

Getting Started

First, you need to install the package:

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

Then, you can your 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

You can load agents directly from the tiny-agents Dataset, or specify a path to your own local agent configuration.

Advanced Usage In addition to the CLI, you can use the Agent class for more fine-grained control. For lower-level interactions, use the MCPClient from the @huggingface/mcp-client package to connect directly to MCP servers and manage tool calls.

Learn more about tiny-agents in the huggingface.js documentation.

huggingface_hub (Python)

The huggingface_hub library is the easiest way to run MCP-powered agents in Python. It includes a high-level tiny-agents CLI as well as programmatic access via the Agent and MCPClient classes — all built to work with Hugging Face Inference Providers, local LLMs, or any inference endpoint compatible with OpenAI’s API specs.

Getting started

Install the latest version with MCP support:

pip install "huggingface_hub[mcp]>=0.32.2"

Then, you can run your 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.                                                                                                                                       │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

The CLI pulls the config, connects to its MCP servers, prints the available tools, and waits for your prompt.

Advanced Usage

For more fine-grained control, use the MCPClient directly. This low-level interface extends AsyncInferenceClient and allows LLMs to call tools via the Model Context Protocol (MCP). It supports both local (stdio) and remote (http/sse) MCP servers, handles tool registration and execution, and streams results back to the model in real-time.

Learn more in the huggingface_hub MCP documentation.

Custom Agents

To create your own agent, simply create a folder (e.g., my-agent/) and define your agent’s configuration in an agent.json file. The following example shows a web-browsing agent configured to use the Qwen/Qwen2.5-72B-Instruct model via Nebius inference provider, and it comes equipped with a playwright MCP server, which lets it use a web browser

{
	"model": "Qwen/Qwen2.5-72B-Instruct",
	"provider": "nebius",
	"servers": [
		{
			"type": "stdio",
			"config": {
				"command": "npx",
				"args": ["@playwright/mcp@latest"]
			}
		}
	]
}

To use a local LLM (such as llama.cpp, or LM Studio), just provide an endpointUrl:

{
	"model": "Qwen/Qwen3-32B",
	"endpointUrl": "http://localhost:1234/v1",
	"servers": [
		{
			"type": "stdio",
			"config": {
				"command": "npx",
				"args": ["@playwright/mcp@latest"]
			}
		}
	]
}

Optionally, add a PROMPT.md to customize the system prompt.

Don’t hesitate to contribute your agent to the community by opening a Pull Request in the tiny-agents Hugging Face dataset.

Gradio MCP Server / Tools

You can build an MCP server in just a few lines of Python with Gradio. If you have an existing Gradio app or Space you’d like to use as an MCP server / tool, it’s just a single-line change.

To make a Gradio application an MCP server, simply pass in mcp_server=True when launching your demo like follows.

# 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)

The MCP server will be available at http://your-space-id.hf.space/gradio_api/mcp/sse where your application is served. It will have a tool corresponding to each function in your Gradio app, with the tool description automatically generated from the docstrings of your functions.

Lastly, add this to the settings of the MCP Client of your choice (e.g. Cursor).

{
  "mcpServers": {
    "gradio": {
      "url": "http://your-server:port/gradio_api/mcp/sse"
    }
  }
}

This is very powerful because it lets the LLM use any Gradio application as a tool. You can find thousands of them on Spaces. Learn more here.

< > Update on GitHub