Load tiny-agents from Hub

packages/tiny-agents/README.md

@@ -85,10 +85,19 @@ npx @huggingface/tiny-agents run ./my-agent
 
 Voilà! 🔥
 
+
+## Tiny Agents collection
+
+Browse our curated collection of Tiny Agents at https://huggingface.co/datasets/huggingface/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`](https://huggingface.co/datasets/huggingface/tiny-agents/tree/main/julien-c/flux-schnell-generator) agent:
+
+```bash
+npx @huggingface/tiny-agents run "julien-c/flux-schnell-generator"
+```
+
 > [!NOTE]
-> Note: you can open a PR in the huggingface.js repo to share your agent with the community, just upload it inside the `src/agents/` directory.
+> Want to share your own agent with the community? Submit a PR to the [Tiny Agents](https://huggingface.co/datasets/huggingface/tiny-agents/discussions) repository on the Hub. Your submission must include an `agent.json` file, and you can optionally add a `PROMPT.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
+## Advanced: Programmatic Usage
 
 ```typescript
 import { Agent } from '@huggingface/tiny-agents';

packages/tiny-agents/package.json

@@ -54,6 +54,7 @@
 		"@huggingface/inference": "workspace:^",
 		"@huggingface/mcp-client": "workspace:^",
 		"@huggingface/tasks": "workspace:^",
+		"@huggingface/hub": "workspace:^",
 		"@modelcontextprotocol/sdk": "^1.11.4",
 		"zod": "^3.25.7"
 	}

packages/tiny-agents/src/cli.ts

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { parseArgs } from "node:util";
 import { lstat, readFile } from "node:fs/promises";
 import { z } from "zod";
+import { downloadFileToCacheDir, type RepoDesignation } from "@huggingface/hub";
 import { PROVIDERS_OR_POLICIES } from "@huggingface/inference";
 import { Agent } from "@huggingface/mcp-client";
 import { version as packageVersion } from "../package.json";
@@ -25,6 +26,11 @@ Flags:
   -v, --version   Show version information
 `.trim();
 
+interface TinyAgentConfig {
+	configJson: string;
+	prompt?: string;
+}
+
 const CLI_COMMANDS = ["run", "serve"] as const;
 function isValidCommand(command: string): command is (typeof CLI_COMMANDS)[number] {
 	return (CLI_COMMANDS as unknown as string[]).includes(command);
@@ -34,51 +40,102 @@ const FILENAME_CONFIG = "agent.json";
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
 const FILENAME_PROMPT = "PROMPT.md";
 
-async function loadConfigFrom(loadFrom: string): Promise<{ configJson: string; prompt?: string }> {
+const TINY_AGENTS_HUB_REPO: RepoDesignation = {
+	name: "huggingface/tiny-agents",
+	type: "dataset",
+};
+
+async function tryLoadFromFile(filePath: string): Promise<TinyAgentConfig | undefined> {
+	try {
+		const configJson = await readFile(filePath, { encoding: "utf8" });
+		return { configJson };
+	} catch {
+		return undefined;
+	}
+}
+
+async function tryLoadFromDirectory(dirPath: string): Promise<TinyAgentConfig | undefined> {
+	const stats = await lstat(dirPath).catch(() => undefined);
+	if (!stats?.isDirectory()) {
+		return undefined;
+	}
+
+	let prompt: string | undefined;
+	try {
+		prompt = await readFile(join(dirPath, FILENAME_PROMPT), { encoding: "utf8" });
+	} catch {
+		debug(`PROMPT.md not found in ${dirPath}, continuing without prompt template`);
+	}
+
 	try {
-		/// First try it as a local file path, then as a local directory, then we will try as a path inside the repo itself
 		return {
-			configJson: await readFile(loadFrom, { encoding: "utf8" }),
+			configJson: await readFile(join(dirPath, FILENAME_CONFIG), { encoding: "utf8" }),
+			prompt,
 		};
 	} catch {
-		if ((await lstat(loadFrom)).isDirectory()) {
-			/// local directory
-			try {
-				let prompt: string | undefined;
-				try {
-					prompt = await readFile(join(loadFrom, FILENAME_PROMPT), { encoding: "utf8" });
-				} catch {
-					debug(`PROMPT.md not found in ${loadFrom}, continuing without prompt template`);
-				}
-				return {
-					configJson: await readFile(join(loadFrom, FILENAME_CONFIG), { encoding: "utf8" }),
-					prompt,
-				};
-			} catch {
-				error(`Config file not found in specified local directory.`);
-				process.exit(1);
-			}
-		}
-		const srcDir = dirname(__filename);
-		const configDir = join(srcDir, "agents", loadFrom);
-		try {
-			let prompt: string | undefined;
-			try {
-				prompt = await readFile(join(configDir, FILENAME_PROMPT), { encoding: "utf8" });
-			} catch {
-				debug(`PROMPT.md not found in ${configDir}, continuing without prompt template`);
-			}
-			return {
-				configJson: await readFile(join(configDir, FILENAME_CONFIG), { encoding: "utf8" }),
-				prompt,
-			};
-		} catch {
-			error(`Config file not found in tiny-agents repo! Loading from the HF Hub is not implemented yet`);
-			process.exit(1);
-		}
+		error(`Config file not found in specified local directory.`);
+		process.exit(1);
 	}
 }
 
+async function tryLoadFromHub(agentId: string): Promise<TinyAgentConfig | undefined> {
+	let configJson: string;
+	try {
+		const configPath = await downloadFileToCacheDir({
+			repo: TINY_AGENTS_HUB_REPO,
+			path: `${agentId}/${FILENAME_CONFIG}`,
+			accessToken: process.env.HF_TOKEN,
+		});
+		configJson = await readFile(configPath, { encoding: "utf8" });
+	} catch {
+		return undefined;
+	}
+
+	let prompt: string | undefined;
+	try {
+		const promptPath = await downloadFileToCacheDir({
+			repo: TINY_AGENTS_HUB_REPO,
+			path: `${agentId}/${FILENAME_PROMPT}`,
+			accessToken: process.env.HF_TOKEN,
+		});
+		prompt = await readFile(promptPath, { encoding: "utf8" });
+	} catch {
+		debug(
+			`PROMPT.md not found in https://huggingface.co/datasets/huggingface/tiny-agents/tree/main/${agentId}, continuing without prompt template`
+		);
+	}
+
+	return {
+		configJson,
+		prompt,
+	};
+}
+
+async function loadConfigFrom(loadFrom: string): Promise<TinyAgentConfig> {
+	// First try as a local file
+	const fileConfig = await tryLoadFromFile(loadFrom);
+	if (fileConfig) {
+		return fileConfig;
+	}
+
+	// Then try as a local directory
+	const dirConfig = await tryLoadFromDirectory(loadFrom);
+	if (dirConfig) {
+		return dirConfig;
+	}
+
+	// Finally try loading from repo
+	const repoConfig = await tryLoadFromHub(loadFrom);
+	if (repoConfig) {
+		return repoConfig;
+	}
+
+	error(
+		`Config file not found in tiny-agents! Please make sure it exists locally or in https://huggingface.co/datasets/huggingface/tiny-agents.`
+	);
+	process.exit(1);
+}
+
 async function main() {
 	const {
 		values: { help, version },