[MCP] Tiny Agents in Python #3098

hanouticelina · 2025-05-21T08:49:45Z

This is an early version of Tiny Agents (https://huggingface.co/blog/tiny-agents) in Python, inspired by @julien-c's work in JS: https://github.com/huggingface/huggingface.js/tree/main/packages/tiny-agents.

What's in the PR?

tiny-agents run command (see src/huggingface_hub/inference/_mcp/cli.py) that mirros the JS CLI and supports: a folder, a single agent.json, or a builtin agent name.
Agent wrapper: src/huggingface_hub/inference/_mcp/tiny_agent.py – very small orchestrator that keeps a history, enforces a max-turn limit, and plugs MCP tools into the LLM.

What's missing?

- Only stdio MCP servers are handled right now, we need to add support for SSE and HTTP MCP servers. implemented in [MCP] add support for SSE + HTTP #3099
- Some possible refactoring: where and how do we want to implement the CLI? ✅

HuggingFaceDocBuilderDev · 2025-05-21T08:53:57Z

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

src/huggingface_hub/inference/_mcp/utils.py

Co-authored-by: Julien Chaumond <[email protected]>

src/huggingface_hub/inference/_mcp/tiny_agent.py

julien-c · 2025-05-21T09:53:47Z

setup.py


 extras["mcp"] = [
    "mcp>=1.8.0",
+    "colorama",


(probably not worth the extra dependency if all you need are a few colors characters sequences)

I would be bullish to switch to Typer instead of argparse to be honest...

It has a much greater UX, easier to maintain, auto-completion out of the box, etc. It adds a dependency but only an optional one (on huggingface_hub[mcp])

Co-authored-by: Julien Chaumond <[email protected]>

julien-c

looks super cool already! 🔥

src/huggingface_hub/inference/_mcp/constants.py

…nto tiny-agent

Wauplin

Very nice! I'm pre-approving with some nits. Once we have SSE/HTTP servers implemented we should be on-par with the JS CLI to make some comms about it :)

(btw, is this a problem that we'll have two tiny-agents CLIs conflicting? Hopefully not but 🤷)

src/huggingface_hub/inference/_mcp/agent.py

src/huggingface_hub/inference/_mcp/cli.py

Wauplin · 2025-05-21T15:48:27Z

src/huggingface_hub/inference/_mcp/cli.py

+        else:
+            raise KeyboardInterrupt


don't know how to solve that but when I launch the CLI + wait for the tools to be loaded, I need to type 4 times on CTRL+C to exit and it exits with a ton of messages. Would be good to improve DX, either here or in a follow-up PR:

> tiny-agents run julien-c/local-coder Fetching 2 files: 100%|███████████████████████████████████████████████████████| 2/2 [00:00<00:00, 64527.75it/s] Agent loaded with 25 tools: • browser_close • browser_resize • browser_console_messages • browser_handle_dialog • browser_file_upload • browser_install • browser_press_key • browser_navigate • browser_navigate_back • browser_navigate_forward • browser_network_requests • browser_pdf_save • browser_take_screenshot • browser_snapshot • browser_click • browser_drag • browser_hover • browser_type • browser_select_option • browser_tab_list • browser_tab_new • browser_tab_select • browser_tab_close • browser_generate_playwright_test • browser_wait_for » ^CInterrupted – press Ctrl+C again to quit ^Cunhandled exception during asyncio.run() shutdown task: <Task finished name='Task-1' coro=<run_agent() done, defined at /home/wauplin/projects/huggingface_hub/src/huggingface_hub/inference/_mcp/cli.py:33> exception=ExceptionGroup('unhandled errors in a TaskGroup', [ProcessLookupError()])> Traceback (most recent call last): File "/home/wauplin/projects/huggingface_hub/src/huggingface_hub/inference/_mcp/cli.py", line 63, in run_agent async with Agent( File "/home/wauplin/projects/huggingface_hub/src/huggingface_hub/inference/_mcp/mcp_client.py", line 65, in __aexit__ await self.cleanup() File "/home/wauplin/projects/huggingface_hub/src/huggingface_hub/inference/_mcp/mcp_client.py", line 241, in cleanup await self.exit_stack.aclose() File "/usr/lib/python3.10/contextlib.py", line 656, in aclose await self.__aexit__(None, None, None) File "/usr/lib/python3.10/contextlib.py", line 714, in __aexit__ raise exc_details[1] File "/usr/lib/python3.10/contextlib.py", line 697, in __aexit__ cb_suppress = await cb(*exc_details) File "/usr/lib/python3.10/contextlib.py", line 206, in __aexit__ await anext(self.gen) File "/home/wauplin/projects/huggingface_hub/.venv310/lib/python3.10/site-packages/mcp/client/stdio/__init__.py", line 170, in stdio_client async with ( File "/home/wauplin/projects/huggingface_hub/.venv310/lib/python3.10/site-packages/anyio/_backends/_asyncio.py", line 772, in __aexit__ raise BaseExceptionGroup( exceptiongroup.ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception) ^C^CException ignored in: <module 'threading' from '/usr/lib/python3.10/threading.py'> Traceback (most recent call last): File "/usr/lib/python3.10/threading.py", line 1537, in _shutdown atexit_call() File "/usr/lib/python3.10/concurrent/futures/thread.py", line 31, in _python_exit t.join() File "/usr/lib/python3.10/threading.py", line 1096, in join self._wait_for_tstate_lock() File "/usr/lib/python3.10/threading.py", line 1116, in _wait_for_tstate_lock if lock.acquire(block, timeout): KeyboardInterrupt:

(I do get similar output no matter when I exit but reporting this one is the most reproducible example)

as discussed in private, it's a bit complicated to "exit" properly an asyncio script in this context 😕 I pushed a better way to exit in f09b70a using os._exit() but still, I believe it's not the best solution..

Thanks for looking into it. Let's do that and leave it for a later PR then...

src/huggingface_hub/inference/_mcp/cli.py

src/huggingface_hub/inference/_mcp/utils.py

…ny-agent

julien-c · 2025-05-21T17:30:53Z

(btw, is this a problem that we'll have two tiny-agents CLIs conflicting? Hopefully not but 🤷)

I thought about it but i don't think so, given i doubt many people will install both globally.

hanouticelina · 2025-05-21T17:45:27Z

let's merge! 🔥

Screen.Recording.2025-05-21.at.19.36.22.mov

hanouticelina · 2025-05-21T17:45:42Z

(failing tests unrelated)

julien-c

❗ 🔥 🚒

As discussed offline, this PR moves the curated collection of tiny-agents to the Hub. Agents must now be contributed to https://huggingface.co/datasets/huggingface/tiny-agents. This will be helpful to maintain the collection independently from the `@huggingface/tiny-agents` releases. It also makes them available for the incoming Python equivalent (huggingface/huggingface_hub#3098). File resolution is still the same: 1. if agent_id is a file => load it as a `agent.json` file 2. if agent_id is a directory => load from it 3. if agent_id is a subdirectory in https://huggingface.co/datasets/huggingface/tiny-agents/tree/main => load from it 4. otherwise raise exception Usage is still: ```bash npx @huggingface/tiny-agents run "julien-c/flux-schnell-generator" ```

hanouticelina added 8 commits May 20, 2025 19:57

first draft of tiny agents in python

e80e8f5

server types

e5ca556

nits

d9fdd1d

better typing

31e61e5

nit

c404313

refactor a bit

8cc4798

revert

d6db822

add constants

7405f98

hanouticelina requested review from LysandreJik, Wauplin and julien-c May 21, 2025 08:49

julien-c reviewed May 21, 2025

View reviewed changes

src/huggingface_hub/inference/_mcp/utils.py Outdated Show resolved Hide resolved

Update src/huggingface_hub/inference/_mcp/utils.py

b57133c

Co-authored-by: Julien Chaumond <[email protected]>

julien-c reviewed May 21, 2025

View reviewed changes

src/huggingface_hub/inference/_mcp/tiny_agent.py Outdated Show resolved Hide resolved

julien-c reviewed May 21, 2025

View reviewed changes

Update src/huggingface_hub/inference/_mcp/tiny_agent.py

36ef6d4

Co-authored-by: Julien Chaumond <[email protected]>

julien-c reviewed May 21, 2025

View reviewed changes

hanouticelina added 2 commits May 21, 2025 12:00

style

1e18a11

rename and use get_token() helper

3a68ac0

hanouticelina changed the title ~~Tiny Agents in Python~~ [MCP] Tiny Agents in Python May 21, 2025

Wauplin mentioned this pull request May 21, 2025

Load tiny-agents from Hub huggingface/huggingface.js#1472

Merged

typer and load agents from the Hub

6a546a2

hanouticelina marked this pull request as ready for review May 21, 2025 13:55

remove local agents

54f2970

hanouticelina commented May 21, 2025

View reviewed changes

src/huggingface_hub/inference/_mcp/constants.py Outdated Show resolved Hide resolved

hanouticelina added 4 commits May 21, 2025 16:01

update default provider

abcbde6

Merge branch 'main' into tiny-agent

122b1c9

remove unnecessary args

e5b6243

Merge branch 'tiny-agent' of github.com:huggingface/huggingface_hub i…

67f8240

…nto tiny-agent

Wauplin approved these changes May 21, 2025

View reviewed changes

hanouticelina added 3 commits May 21, 2025 18:04

fixes

6c0f5bd

better exit?

f09b70a

Merge branch 'main' of github.com:huggingface/huggingface_hub into ti…

2181054

…ny-agent

fix

dc650b5

julien-c approved these changes May 21, 2025

View reviewed changes

hanouticelina merged commit aee73c4 into main May 21, 2025
25 checks passed

hanouticelina deleted the tiny-agent branch May 21, 2025 17:49

julien-c mentioned this pull request May 22, 2025

Python Implementation of TinyAgent #3046

Closed

[MCP] Tiny Agents in Python #3098

[MCP] Tiny Agents in Python #3098

Uh oh!

Conversation

hanouticelina commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What's in the PR?

What's missing?

Uh oh!

HuggingFaceDocBuilderDev commented May 21, 2025

Uh oh!

Uh oh!

Uh oh!

julien-c May 21, 2025

Choose a reason for hiding this comment

Uh oh!

Wauplin May 21, 2025

Choose a reason for hiding this comment

Uh oh!

julien-c left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Wauplin left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Wauplin May 21, 2025

Choose a reason for hiding this comment

Uh oh!

hanouticelina May 21, 2025

Choose a reason for hiding this comment

Uh oh!

Wauplin May 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

julien-c commented May 21, 2025

Uh oh!

hanouticelina commented May 21, 2025

Uh oh!

hanouticelina commented May 21, 2025

Uh oh!

julien-c left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

hanouticelina commented May 21, 2025 •

edited

Loading