Hugging Face Tiny Agents in Python

Hugging Face has ported its "Tiny Agents" concept to Python, extending the huggingface_hub client SDK to function as a Model Context Protocol (MCP) client. This allows developers to create functional AI agents in approximately 70 lines of code by standardizing how Large Language Models (LLMs) discover and execute external tools.

The Model Context Protocol (MCP)

MCP is an open protocol designed to standardize the interaction between LLMs and external tools or APIs. By providing a universal interface, MCP eliminates the need for developers to write custom integrations for every individual tool, simplifying the process of adding new capabilities to an LLM.

Running and Configuring Tiny Agents

Tiny Agents can be deployed via the CLI after installing the huggingface_hub library with the mcp extra:

pip install "huggingface_hub[mcp]>=0.32.0"

Agent Configuration

An agent's behavior is defined by an agent.json file and an optional PROMPT.md for detailed system instructions. The agent.json file specifies:

  • Model: The LLM to be used (e.g., Qwen/Qwen2.5-72B-Instruct).
  • Provider: The inference provider (e.g., Nebius).
  • Servers: An array of MCP servers the agent should connect to. These can be stdio servers (running as local processes via commands and arguments) or http servers (remote tools).

Deployment Examples

Agents can be loaded from local configurations or directly from the tiny-agents/tiny-agents dataset on the Hugging Face Hub. Examples include:

  • Web-Browsing Agent: Uses a Playwright MCP server to operate a sandboxed Chromium browser.
  • Image Generation Agent: Connects to a FLUX.1 [schnell] image generation HF Space acting as an MCP server.

Technical Architecture: The MCPClient

The MCPClient within huggingface_hub is the core component managing tool-use functionality. Its primary responsibilities include managing asynchronous connections to MCP servers, discovering available tools, formatting those tools for the LLM, and executing tool calls.

Connection and Tool Discovery

The add_mcp_server method establishes connections based on the server type (stdio, sse, or http). Once connected, the client initializes a ClientSession and calls list_tools() to retrieve the server's available tools. These tools are then formatted into a schema compatible with the OpenAI Chat Completions API, which is the standard interface used by InferenceClient.

Tool Execution Loop

The process_single_turn_with_tools method handles the LLM interaction cycle:

  1. Preparation: It aggregates tools from MCP servers and any "exit loop" control tools.
  2. Streaming: It makes a streaming call to the LLM using AsyncInferenceClient.chat.completions.create.
  3. Processing: As chunks arrive, the client reconstructs the text response and any requested tool calls.
  4. Execution: If a tool is called, the client identifies the corresponding MCP session and executes the tool via session.call_tool(). The result is then formatted and added to the conversation history.

The Agent Implementation

The Agent class inherits from MCPClient and adds a conversational management layer. It is designed as a simple loop that maintains state and determines when a task is complete.

Initialization

Upon creation, the Agent initializes conversation history with a system prompt and calls load_tools() to connect to all configured MCP servers, populating the agent's available toolbox.

The Core Execution Loop

The Agent.run() method is an asynchronous generator that processes user input through a while True loop. In each iteration, it delegates the LLM and tool interaction to process_single_turn_with_tools and yields the results in real-time.

The loop terminates based on three conditions:

  • An "exit loop" tool is explicitly called.
  • The maximum number of turns (MAX_NUM_TURNS) is reached.
  • The LLM provides a final text response that does not require further tool calls.

Sources