Python Implementation of TinyAgent

[njbrake]

I was a fan of the HuggingFace Blog post about TinyAgent: I think it's a cool proof-of-concept that shows the power of a simple prompt + MCP servers.

I took the JS implementation and ported it to python for Mozilla.ai's any-agent library via mozilla-ai/any-agent#166, and @julien-c mentioned that this code might be useful in the huggingface hub.

Try it

pip install -e ".[dev,tests,mcp]"
python tiny_agent.py

This is not ready to merge: I have some cleanup to do on this code and would like to better organize it, but figured I would get this PR up so that we can start the discussion. A few questions:

1. What folder would you want this agent in?
2. Can I split this across multiple files?
3. What do you use for typing? any-agent uses pydantic but its not clear to me if that's able to be used in this library. I stripped out the pydantic typing and turned them into dicts just to get it running, but that's not a good final solution imo.
4. Would you like there to be a run_interactive function so that you can ask it a question/chat with it?

There's an issue

Relates to:

#2986
mozilla-ai/any-agent#168
mozilla-ai/any-agent#166

Bonus

If you want to run a MCP Server externally so that you can try out the SSE connection, open a python interpreter and run this script

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Echo Server", host="127.0.0.1", port=8000)

@mcp.tool()
def write_file(text: str) -> str:
    """Say hi back with the input text"""
    return f"Hi: {text}"

@mcp.tool()
def read_file(text: str) -> str:
    """Say bye back the input text"""
    return f"Bye: {text}"

@mcp.tool()
def other_tool(text: str) -> str:
    """Say boo back the input text"""
    return f"Boo: {text}"

mcp.run("sse")

then change my previous agent config to this:

await agent.load_agent(
            [
                {
                    "type": "stdio",
                    "command": "uvx",
                    "args": ["mcp-server-time", "--local-timezone=America/New_York"],
                    "tools": [
                        "get_current_time",
                    ],
                    "env_vars": {},
                },
                {
                    "type": "sse",
                    "url": "http://127.0.0.1:8000/sse",
                    "tools": [
                        "other_tool",
                    ],
                    "env_vars": {},
                }
            ]
        )

[julien-c]

hey @njbrake sorry i've been super slow to reply here.

We've finally merged our long-standing MCP Client PR (#2986) a few days ago, and then we also added HTTP and SSE support to it (#3099) thanks to @evalstate

There's some early documentation for the MCP Client here: https://huggingface.co/docs/huggingface_hub/main/en/package_reference/mcp

Finally, @hanouticelina and @Wauplin improved my Tiny Agent JS implementation a lot and we pushed a lightweight implementation on top of MCPClient in #3098 which was merged today.

I'd love to get your feedback on that PR! Some of the main differences with your implem from this PR are:

• it's async-generator only (agent.run() returns a AsyncGenerator[Union[ChatCompletionStreamOutput, ChatCompletionInputMessage]])
• all the tool handling is delegated to MCPClient
• it can load agents from a simple agent.json file format (either remotely on the HF Hub or from a local file)

[njbrake]

hey @njbrake sorry i've been super slow to reply here.

We've finally merged our long-standing MCP Client PR (#2986) a few days ago, and then we also added HTTP and SSE support to it (#3099) thanks to @evalstate

There's some early documentation for the MCP Client here: https://huggingface.co/docs/huggingface_hub/main/en/package_reference/mcp

Finally, @hanouticelina and @Wauplin improved my Tiny Agent JS implementation a lot and we pushed a lightweight implementation on top of MCPClient in #3098 which was merged today.

I'd love to get your feedback on that PR! Some of the main differences with your implem from this PR are:

* it's async-generator only (`agent.run()` returns a `AsyncGenerator[Union[ChatCompletionStreamOutput, ChatCompletionInputMessage]]`)

* all the tool handling is delegated to `MCPClient`

* it can load agents from a simple `agent.json` file format (either remotely on the HF Hub or from a local file)

Hi @julien-c , totally no worries. I pulled this draft together as a starting point for conversation, but certainly it's not any refined code that I expected to be ready for merging without some design discussions. I'm excited to hear that there's been a TinyAgent implementation merged into huggingface_hub, and look forward to trying it out! 🙏 I'll close out this PR.