Want to build an AI agent without drowning in complexity? Tiny Agents might be exactly what you’re looking for. This minimalist, MCP-powered AI framework, created by the co-founder of HuggingFace, lets you build powerful AI agents with just 50 lines of JavaScript code.
Table of Contents
Introducing Tiny Agents
The magic behind Tiny Agents is surprisingly simple. While exploring the Model Context Protocol (MCP), the HuggingFace co-founder discovered something mind-blowing: once you have an MCP client, creating an agent is just a while loop on top of it.
“Once you have a MCP Client, an Agent is literally just a while loop on top of it,” explains the Hugging Face co-founder behind the project.
This insight led to the creation of Tiny Agents – a lightweight, powerful AI framework that makes building AI agents accessible to more developers.
Understanding MCP
MCP isn’t complicated, but it’s incredibly useful. At its core, MCP is a standard API that lets you connect tools to Large Language Models (LLMs).
Think of it as a universal adapter that helps your LLM talk to various tools and services. The beauty of MCP is that once you understand this standard, you can plug in different tools without changing your core agent code.
Modern LLMs have native support for tool calling (also known as function calling). This means they can understand when to use external tools and how to format the calls correctly. Your LLM can decide to call zero, one, or multiple tools during a conversation.
How Tiny Agents Work
The Tiny Agents framework builds on top of an MCP client, which handles all the complex parts of connecting to MCP servers and managing tools. Here’s what makes it work:
- It connects to MCP servers to discover available tools
- It formats these tools so the LLM can understand them
- It handles the back-and-forth between the LLM and the tools
- It manages the conversation flow with a simple while loop
The whole agent is built around alternating between tool calling and feeding results back to the LLM. This continues until certain exit conditions are met, like completing a task or needing user input.
The Technical Magic Behind Tiny Agents
Let’s peek under the hood at what makes Tiny Agents work:
1. The McpClient Class
This class is the foundation. It maintains an Inference Client for talking to LLMs, manages connections to MCP servers and keeps track of all available tools. When connecting to an MCP server, it gets a list of tools and formats them for the LLM.
2. The Agent Class
The Agent class extends McpClient and adds a system prompt to guide the LLM, a message history for the conversation, control flow tools like task_complete and ask_question and the all-important while loop that drives the agent.
3. The “50 Line” While Loop
The heart of Tiny Agents is its while loop. This surprisingly simple bit of code processes a single turn with the LLM, checks if any tools were called exits the loop if needed (task completed, question asked, etc.) and continues the conversation by alternating between tool results and LLM responses.
Getting Started with Tiny Agents
Want to try it out? It’s super easy to get going:
npx @huggingface/mcp-client
Or if you’re using pnpm:
pnpx @huggingface/mcp-client
This installs the package temporarily and runs it. You’ll see your agent connect to two MCP servers running locally:
- A file system server that can access your Desktop
- A Playwright MCP server that controls a sandboxed browser
Experiment With Tiny Agents
Now, you can ask it to do different tasks. I used it to perform the following task:
File System Operations
Web Browsing & Research
Using Different Models and Providers with Tiny Agents
By default, Tiny Agents uses “Qwen/Qwen2.5-72B-Instruct” as the model and Nebius as the inference provider.
But you can easily configure it to use different models and providers through environment variables:
javascript
const agent = new Agent({
provider: process.env.PROVIDER ?? “nebius”,
model: process.env.MODEL_ID ?? “Qwen/Qwen2.5-72B-Instruct”,
apiKey: process.env.HF_TOKEN,
servers: SERVERS,
});
Why Tiny Agents Matters
This represents a significant step forward in making AI agents more accessible. By reducing the complexity to just 50 lines of code, it opens the door for many more developers to experiment with and build AI agents.
The framework shows that you don’t need complex architectures to create useful AI agents. With modern LLMs that have native tool-calling abilities, a simple approach can be surprisingly effective.
Build Your Own Tiny Agents Today
The entire Tiny Agents codebase is open source and available in the huggingface.js mono-repo. Whether you’re new to AI agents or an experienced developer, this minimal framework offers a great way to start experimenting with MCP-powered AI agents.
With just 50 lines of code, you can have a working AI agent that connects to tools, maintains context, and solves real problems. It’s a perfect example of how sometimes the simplest solutions are the most elegant.
So why not give Tiny Agents a try? Your first MCP-powered agent is just a few lines of code away.
| Latest From Us
- Forget Towers: Verizon and AST SpaceMobile Are Launching Cellular Service From Space
- This $1,600 Graphics Card Can Now Run $30,000 AI Models, Thanks to Huawei
- The Global AI Safety Train Leaves the Station: Is the U.S. Already Too Late?
- The AI Breakthrough That Solves Sparse Data: Meet the Interpolating Neural Network
- The AI Advantage: Why Defenders Must Adopt Claude to Secure Digital Infrastructure
