Huggingface.js

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

@huggingface/tiny-agents

meme

A squad of lightweight composable AI applications built on Hugging Face’s Inference Client and MCP stack.

Installation

npm install @huggingface/tiny-agents
# or
pnpm add @huggingface/tiny-agents

CLI Usage

npx @huggingface/tiny-agents [command] "agent/id"

Usage:
  tiny-agents [flags]
  tiny-agents run   "agent/id"
  tiny-agents serve "agent/id"

Available Commands:
  run         Run the Agent in command-line
  serve       Run the Agent as an OpenAI-compatible HTTP server

You can load agents directly from the Hugging Face Hub tiny-agents Dataset, or specify a path to your own local agent configuration.

Define your own agent

The simplest way to create your own agent is to create a folder containing an agent.json file:

mkdir my-agent
touch my-agent/agent.json

{
	"model": "Qwen/Qwen2.5-72B-Instruct",
	"provider": "nebius",
	"servers": [
		{
			"type": "stdio",
			"command": "npx",
			"args": ["@playwright/mcp@latest"]
		}
	]
}

Or using a local or remote endpoint URL:

{
	"model": "Qwen/Qwen3-32B",
	"endpointUrl": "http://localhost:1234/v1",
	"servers": [
		{
			"type": "stdio",
			"command": "npx",
			"args": ["@playwright/mcp@latest"]
		}
	]
}

Where servers is a list of MCP servers (we support Stdio, SSE, and HTTP servers).

Optionally, you can add an AGENTS.md (or PROMPT.md) file to override the default Agent prompt.

Then just point tiny-agents to your local folder:

npx @huggingface/tiny-agents run ./my-agent

Voilà! 🔥

Tiny Agents collection

Browse our curated collection of Tiny Agents at https://huggingface.co/datasets/tiny-agents/tiny-agents. Each agent is stored in its own subdirectory, following the structure outlined above. Running an agent from the Hub is as simple as using its agent_id. For example, to run the julien-c/flux-schnell-generator agent:

npx @huggingface/tiny-agents run "julien-c/flux-schnell-generator"

Want to share your own agent with the community? Submit a PR to the Tiny Agents repository on the Hub. Your submission must include an agent.json file, and you can optionally add a PROMPT.md or AGENTS.md file. To help others understand your agent’s capabilities, consider including an EXAMPLES.md file with sample prompts and use cases.

Advanced: Programmatic Usage

import { Agent } from '@huggingface/tiny-agents';

const HF_TOKEN = "hf_...";

// Create an Agent
const agent = new Agent({
  provider: "auto",
  model: "Qwen/Qwen2.5-72B-Instruct",
  apiKey: HF_TOKEN,
  servers: [
    {
      // Playwright MCP
      command: "npx",
      args: ["@playwright/mcp@latest"],
    },
  ],
});

await agent.loadTools();

// Use the Agent
for await (const chunk of agent.run("What are the top 5 trending models on Hugging Face?")) {
    if ("choices" in chunk) {
        const delta = chunk.choices[0]?.delta;
        if (delta.content) {
            console.log(delta.content);
        }
    }
}

License

MIT

Update on GitHub

←Simple MCP Client built on top of Inference Client Use Space mini_header in your app→