improve relationship between tiny agents and gradio use case

burtenshaw · burtenshaw · commit afab9546f971 · 2025-05-13T14:29:47.000+02:00
diff --git a/units/en/unit2/tiny-agents.mdx b/units/en/unit2/tiny-agents.mdx
@@ -1,22 +1,13 @@
 # Tiny Agents: an MCP-powered agent in 50 lines of code
 
-Now that we've built MCP server's in Gradio let's explore MCP clients even further. This section on based on the experimental project [Tiny Agents](https://huggingface.co/blog/tiny-agents). Which is a super simple way of deploying MCP clients and using Hugging Face Inference Providers.
+Now that we've built MCP servers in Gradio let's explore MCP clients even further. This section builds on the experimental project [Tiny Agents](https://huggingface.co/blog/tiny-agents), which demonstrates a super simple way of deploying MCP clients that can connect to services like our Gradio sentiment analysis server.
 
-
-It is fairly simple to extend an Inference Client – at HF, we have two official client SDKs: [`@huggingface/inference`](https://github.com/huggingface/huggingface.js) in JS, and [`huggingface_hub`](https://github.com/huggingface/huggingface_hub/) in Python – to also act as a MCP client and hook the available tools from MCP servers into the LLM inference. 
-
-<Tip>
-
-Once you have an MCP Client, an Agent is literally just a while loop on top of it.
-
-</Tip>
-
-In short exercise, we will walk you through how to implement a Typescript (JS) MCP client, how you can adopt MCP too and how it's going to make Agentic AI way simpler going forward.
+In this short exercise, we will walk you through how to implement a TypeScript (JS) MCP client that can communicate with any MCP server, including the Gradio-based sentiment analysis server we built in the previous section. You'll see how MCP standardizes the way agents interact with tools, making Agentic AI development significantly simpler.
 
 ![meme](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/thumbnail.jpg)
 <figcaption>Image credit https://x.com/adamdotdev</figcaption>
 
-We will also show you how to connect your tiny agent to Gradio based MCP server from the previous section. 
+We will show you how to connect your tiny agent to Gradio-based MCP servers, allowing it to leverage both your custom sentiment analysis tool and other pre-built tools.
 
 ## How to run the complete demo
 
@@ -32,9 +23,9 @@ or if using `pnpm`:
 pnpx @huggingface/mcp-client
 ```
 
-This installs my package into a temporary folder then executes its command.
+This installs the package into a temporary folder then executes its command.
 
-You'll see your simple Agent connect to two distinct MCP servers (running locally), loading their tools, then prompting you for a conversation.
+You'll see your simple Agent connect to multiple MCP servers (running locally), loading their tools (similar to how it would load your Gradio sentiment analysis tool), then prompting you for a conversation.
 
 <video controls autoplay loop>
   <source src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/use-filesystem.mp4" type="video/mp4">
@@ -45,8 +36,10 @@ By default our example Agent connects to the following two MCP servers:
 - the "canonical" [file system server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem), which gets access to your Desktop,
 - and the [Playwright MCP](https://github.com/microsoft/playwright-mcp) server, which knows how to use a sandboxed Chromium browser for you.
 
+You can easily add your Gradio sentiment analysis server to this list, as we'll demonstrate later in this section.
+
 > [!NOTE]
-> Note: this is a bit counter-intuitive but currently, all MCP servers are actually local processes (though remote servers are coming soon).
+> Note: this is a bit counter-intuitive but currently, all MCP servers in tiny agents are actually local processes (though remote servers are coming soon). This doesn't includes our Gradio server running on localhost:7860.
 
 Our input for this first video was:
 
@@ -60,40 +53,56 @@ Now let us try this prompt that involves some Web browsing:
   <source src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/brave-search.mp4" type="video/mp4">
 </video>
 
+With our Gradio sentiment analysis tool connected, we could similarly ask:
+> analyze the sentiment of this review: "I absolutely loved the product, it exceeded all my expectations!"
+
 ### Default model and provider
 
 In terms of model/provider pair, our example Agent uses by default:
 - ["Qwen/Qwen2.5-72B-Instruct"](https://huggingface.co/Qwen/Qwen2.5-72B-Instruct)
 - running on [Nebius](https://huggingface.co/docs/inference-providers/providers/nebius)
 
-This is all configurable through env variables! See:
+This is all configurable through env variables! Here, we'll also show how to add our Gradio MCP server:
 
 ```ts
 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,
+	servers: [
+		// Default servers
+		{
+			command: "npx",
+			args: ["@modelcontextprotocol/servers", "filesystem"]
+		},
+		{
+			command: "npx",
+			args: ["playwright-mcp"]
+		},
+		// Our Gradio sentiment analysis server
+		{
+			command: "npx",
+			args: [
+				"mcp-remote",
+				"http://localhost:7860/gradio_api/mcp/sse"
+			]
+		}
+	],
 });
 ```
 
-## Where does the code live
-
-The Tiny Agent code lives in the `mcp-client` sub-package of the `huggingface.js` mono-repo, which is the GitHub mono-repo in which all our JS libraries reside.
+<Tip>
 
-https://github.com/huggingface/huggingface.js/tree/main/packages/mcp-client
+We connect to our Gradio based MCP server via the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) package.
 
-> [!TIP]
-> The codebase uses modern JS features (notably, async generators) which make things way easier to implement, especially asynchronous events like the LLM responses. 
-> You might need to ask a LLM about those JS features if you're not yet familiar with them.
+</Tip>
 
 
 ## The foundation for this: tool calling native support in LLMs.
 
-What is going to make this whole blogpost very easy is that the recent crop of LLMs (both closed and open) have been trained for function calling, aka. tool use.
+What makes connecting Gradio MCP servers to our Tiny Agent possible is that recent LLMs (both closed and open) have been trained for function calling, aka. tool use. This same capability powers our integration with the sentiment analysis tool we built with Gradio.
 
-A tool is defined by its name, a description, and a JSONSchema representation of its parameters.
-In some sense, it is an opaque representation of any function's interface, as seen from the outside (meaning, the LLM does not care how the function is actually implemented).
+A tool is defined by its name, a description, and a JSONSchema representation of its parameters - exactly how we defined our sentiment analysis function in the Gradio server. Let's look at a simple example:
 
 ```ts
 const weatherTool = {
@@ -114,6 +123,8 @@ const weatherTool = {
 };
 ```
 
+Our Gradio sentiment analysis tool would have a similar structure, with `text` as the input parameter instead of `location`.
+
 The canonical documentation I will link to here is [OpenAI's function calling doc](https://platform.openai.com/docs/guides/function-calling?api-mode=chat). (Yes... OpenAI pretty much defines the LLM standards for the whole community 😅).
 
 Inference engines let you pass a list of tools when calling the LLM, and the LLM is free to call zero, one or more of those tools.
@@ -124,7 +135,7 @@ As a developer, you run the tools and feed their result back into the LLM to con
 
 ## Implementing an MCP client on top of InferenceClient
 
-Now that we know what a tool is in recent LLMs, let us implement the actual MCP client.
+Now that we know what a tool is in recent LLMs, let's implement the actual MCP client that will communicate with our Gradio server and other MCP servers.
 
 The official doc at https://modelcontextprotocol.io/quickstart/client is fairly well-written. You only have to replace any mention of the Anthropic client SDK by any other OpenAI-compatible client SDK. (There is also a [llms.txt](https://modelcontextprotocol.io/llms-full.txt) you can feed into your LLM of choice to help you code along). 
 
@@ -135,7 +146,7 @@ As a reminder, we use HF's `InferenceClient` for our inference client.
 
 Our `McpClient` class has:
 - an Inference Client (works with any Inference Provider, and `huggingface/inference` supports both remote and local endpoints)
-- a set of MCP client sessions, one for each connected MCP server (yes, we want to support multiple servers)
+- a set of MCP client sessions, one for each connected MCP server (this allows us to connect to multiple servers, including our Gradio server)
 - and a list of available tools that is going to be filled from the connected servers and just slightly re-formatted.
 
 ```ts
@@ -156,7 +167,7 @@ export class McpClient {
 }
 ```
 
-To connect to a MCP server, the official `@modelcontextprotocol/sdk/client` TypeScript SDK provides a `Client` class with a `listTools()` method:
+To connect to a MCP server (like our Gradio sentiment analysis server), the official `@modelcontextprotocol/sdk/client` TypeScript SDK provides a `Client` class with a `listTools()` method:
 
 ```ts
 async addMcpServer(server: StdioServerParameters): Promise<void> {
@@ -192,13 +203,13 @@ async addMcpServer(server: StdioServerParameters): Promise<void> {
 }
 ```
 
-`StdioServerParameters` is an interface from the MCP SDK that will let you easily spawn a local process: as we mentioned earlier, currently, all MCP servers are actually local processes.
+`StdioServerParameters` is an interface from the MCP SDK that will let you easily spawn a local process: as we mentioned earlier, currently, all MCP servers are actually local processes, including our Gradio server (though we access it via HTTP).
 
-For each MCP server we connect to, we slightly re-format its list of tools and add them to `this.availableTools`.
+For each MCP server we connect to (including our Gradio sentiment analysis server), we slightly re-format its list of tools and add them to `this.availableTools`.
 
 ### How to use the tools
 
-Easy, you just pass `this.availableTools` to your LLM chat-completion, in addition to your usual array of messages:
+Using our sentiment analysis tool (or any other MCP tool) is straightforward. You just pass `this.availableTools` to your LLM chat-completion, in addition to your usual array of messages:
 
 ```ts
 const stream = this.client.chatCompletionStream({
@@ -235,18 +246,20 @@ if (client) {
 }
 ```
 
+If the LLM chooses to use our sentiment analysis tool, this code will automatically route the call to our Gradio server, execute the analysis, and return the result back to the LLM.
+
 Finally you will add the resulting tool message to your `messages` array and back into the LLM.
 
 ## Our 50-lines-of-code Agent 🤯
 
-Now that we have an MCP client capable of connecting to arbitrary MCP servers to get lists of tools and capable of injecting them and parsing them from the LLM inference, well... what is an Agent?
+Now that we have an MCP client capable of connecting to arbitrary MCP servers (including our Gradio sentiment analysis server) to get lists of tools and capable of injecting them and parsing them from the LLM inference, well... what is an Agent?
 
 > Once you have an inference client with a set of tools, then an Agent is just a while loop on top of it.
 
 In more detail, an Agent is simply a combination of:
 - a system prompt
 - an LLM Inference client
-- an MCP client to hook a set of Tools into it from a bunch of MCP servers
+- an MCP client to hook a set of Tools into it from a bunch of MCP servers (including our Gradio server)
 - some basic control flow (see below for the while loop)
 
 > [!TIP]
@@ -290,7 +303,7 @@ Even though this comes from OpenAI 😈, this sentence in particular applies to
 
 > We encourage developers to exclusively use the tools field to pass tools, rather than manually injecting tool descriptions into your prompt and writing a separate parser for tool calls, as some have reported doing in the past.
 
-Which is to say, we don't need to provide painstakingly formatted lists of tool use examples in the prompt. The `tools: this.availableTools` param is enough.
+Which is to say, we don't need to provide painstakingly formatted lists of tool use examples in the prompt. The `tools: this.availableTools` param is enough, and the LLM will know how to use both the filesystem tools and our Gradio sentiment analysis tool.
 
 Loading the tools on the Agent is literally just connecting to the MCP servers we want (in parallel because it's so easy to do in JS):
 
@@ -377,19 +390,68 @@ while (true) {
 }
 ```
 
-## Next steps
+## Connecting Tiny Agents with Gradio MCP Servers
+
+Now that we understand both Tiny Agents and Gradio MCP servers, let's see how they work together! The beauty of MCP is that it provides a standardized way for agents to interact with any MCP-compatible server, including our Gradio-based sentiment analysis server.
+
+### Using the Gradio Server with Tiny Agents
+
+To connect our Tiny Agent to the Gradio sentiment analysis server we built earlier, we just need to add it to our list of servers. Here's how we can modify our agent configuration:
+
+```ts
+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: [
+        // ... existing servers ...
+        {
+            command: "npx",
+            args: [
+                "mcp-remote",
+                "http://localhost:7860/gradio_api/mcp/sse"  // Your Gradio MCP server
+            ]
+        }
+    ],
+});
+```
+
+Now our agent can use the sentiment analysis tool alongside other tools! For example, it could:
+1. Read text from a file using the filesystem server
+2. Analyze its sentiment using our Gradio server
+3. Write the results back to a file
+
+### Example Interaction
+
+Here's what a conversation with our agent might look like:
+
+```
+User: Read the file "feedback.txt" from my Desktop and analyze its sentiment
+
+Agent: I'll help you analyze the sentiment of the feedback file. Let me break this down into steps:
+
+1. First, I'll read the file using the filesystem tool
+2. Then, I'll analyze its sentiment using the sentiment analysis tool
+3. Finally, I'll write the results to a new file
+
+[Agent proceeds to use the tools and provide the analysis]
+```
+
+### Deployment Considerations
+
+When deploying your Gradio MCP server to Hugging Face Spaces, you'll need to update the server URL in your agent configuration to point to your deployed space:
 
-There are many cool potential next steps once you have a running MCP Client and a simple way to build Agents 🔥
+```ts
+{
+    command: "npx",
+    args: [
+        "mcp-remote",
+        "https://YOUR_USERNAME-mcp-sentiment.hf.space/gradio_api/mcp/sse"
+    ]
+}
+```
 
-- Experiment with **other models**
-  - [mistralai/Mistral-Small-3.1-24B-Instruct-2503](https://huggingface.co/mistralai/Mistral-Small-3.1-24B-Instruct-2503) is optimized for function calling
-  - Gemma 3 27B, the [Gemma 3 QAT](https://huggingface.co/collections/google/gemma-3-qat-67ee61ccacbf2be4195c265b) models are a popular choice for function calling though it would require us to implement tool parsing as it's not using native `tools` (a PR would be welcome!)
-- Experiment with all the **[Inference Providers](https://huggingface.co/docs/inference-providers/index)**:
-  - Cerebras, Cohere, Fal, Fireworks, Hyperbolic, Nebius, Novita, Replicate, SambaNova, Together, etc.
-  - each of them has different optimizations for function calling (also depending on the model) so performance may vary!
-- Hook **local LLMs** using llama.cpp or LM Studio
+This allows your agent to use the sentiment analysis tool from anywhere, not just locally!
 
-Pull requests and contributions are welcome! 
-Again, everything here is [open source](https://github.com/huggingface/huggingface.js)! 💎❤️
 
 
