Create a tiny-agents package (#1451)

<img width="1944" alt="image"
src="https://github.com/user-attachments/assets/e9c2597e-1a3c-42fc-bfbd-08fbb1ee458a"
/>

Author: julien-c

.github/workflows/tiny-agents-publish.yml

@@ -0,0 +1,77 @@
+name: Tiny Agents - Version and Release
+
+on:
+  workflow_dispatch:
+    inputs:
+      newversion:
+        type: choice
+        description: "Semantic Version Bump Type"
+        default: patch
+        options:
+          - patch
+          - minor
+          - major
+      bypass_deps_check:
+        type: boolean
+        description: "Bypass dependency checking"
+        default: false
+
+concurrency:
+  group: "push-to-main" # Consider changing this if tiny-agents has its own release concurrency group
+
+defaults:
+  run:
+    working-directory: packages/tiny-agents
+
+jobs:
+  version_and_release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          token: ${{ secrets.BOT_ACCESS_TOKEN }}
+      - run: npm install -g corepack@latest && corepack enable
+      - uses: actions/setup-node@v3
+        with:
+          node-version: "20"
+          cache: "pnpm"
+          cache-dependency-path: |
+            packages/tiny-agents/pnpm-lock.yaml
+            packages/doc-internal/pnpm-lock.yaml
+          registry-url: "https://registry.npmjs.org"
+      - run: pnpm install
+      - run: git config --global user.name machineuser
+      - run: git config --global user.email infra+machineuser@huggingface.co
+      - run: |
+          PACKAGE_VERSION=$(node -p "require('./package.json').version")
+          BUMPED_VERSION=$(node -p "require('semver').inc('$PACKAGE_VERSION', '${{ github.event.inputs.newversion }}')")
+          # Update package.json with the new version
+          node -e "const fs = require('fs'); const package = JSON.parse(fs.readFileSync('./package.json')); package.version = '$BUMPED_VERSION'; fs.writeFileSync('./package.json', JSON.stringify(package, null, '\t') + '\n');"
+          pnpm --filter doc-internal run fix-cdn-versions
+          git add ../..
+          git commit -m "🔖 @huggingface/tiny-agents $BUMPED_VERSION"
+          git tag "tiny-agents-v$BUMPED_VERSION"
+
+      # Add checks for dependencies if needed, similar to hub-publish.yml
+      - if: ${{ !github.event.inputs.bypass_deps_check }}
+        name: "Check Deps are published before publishing this package"
+        run: pnpm -w check-deps inference && pnpm -w check-deps tasks # Review if these specific deps apply to tiny-agents
+
+      - run: pnpm publish --no-git-checks .
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+      - run: (git pull --rebase && git push --follow-tags) || (git pull --rebase && git push --follow-tags)
+      # hack - reuse actions/setup-node@v3 just to set a new registry
+      - uses: actions/setup-node@v3
+        with:
+          node-version: "20"
+          registry-url: "https://npm.pkg.github.com"
+      # Disable for now, until github supports PATs for writing github packages (https://github.com/github/roadmap/issues/558)
+      # - run: pnpm publish --no-git-checks .
+      #   env:
+      #     NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: "Update Doc"
+        uses: peter-evans/repository-dispatch@v2
+        with:
+          event-type: doc-build
+          token: ${{ secrets.BOT_ACCESS_TOKEN }}

README.md

@@ -241,8 +241,8 @@ const agent = new Agent({
   ],
 });
 
-
 await agent.loadTools();
+
 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;

packages/mcp-client/src/index.ts

@@ -1,3 +1,4 @@
 export * from "./McpClient";
 export * from "./Agent";
 export type { ChatCompletionInputMessageTool } from "./McpClient";
+export type { ServerConfig } from "./types";

packages/tiny-agents/.eslintignore

@@ -0,0 +1 @@
+dist

packages/tiny-agents/.prettierignore

@@ -0,0 +1,4 @@
+pnpm-lock.yaml
+# In order to avoid code samples to have tabs, they don't display well on npm
+README.md
+dist

packages/tiny-agents/README.md

@@ -0,0 +1,110 @@
+# @huggingface/tiny-agents
+
+![meme](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/blog/tiny-agents/legos.png)
+
+A squad of lightweight composable AI applications built on Hugging Face's Inference Client and MCP stack.
+
+## Installation
+
+```bash
+npm install @huggingface/tiny-agents
+# or
+pnpm add @huggingface/tiny-agents
+```
+
+## CLI Usage
+
+```bash
+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
+```
+
+## Define your own agent
+
+The simplest way to create your own agent is to create a folder containing an `agent.json` file:
+
+```bash
+mkdir my-agent
+touch my-agent/agent.json
+```
+
+```json
+{
+	"model": "Qwen/Qwen2.5-72B-Instruct", // model id
+	"provider": "nebius", // or you can also use a local endpoint base url with `endpointUrl`
+	"servers": [
+		{
+			"type": "stdio",
+			"config": {
+				"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 a `PROMPT.md` file to override the default Agent prompt.
+
+Then just point tiny-agents to your local folder:
+
+```bash
+npx @huggingface/tiny-agents run ./my-agent
+```
+
+Voilà! 🔥
+
+> [!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.
+
+### Advanced: Programmatic Usage
+
+```typescript
+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

packages/tiny-agents/package.json

@@ -0,0 +1,60 @@
+{
+	"name": "@huggingface/tiny-agents",
+	"packageManager": "pnpm@10.10.0",
+	"version": "0.1.0",
+	"description": "Lightweight, composable agents for AI applications",
+	"repository": "https://github.com/huggingface/huggingface.js.git",
+	"publishConfig": {
+		"access": "public"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.mjs",
+	"types": "./dist/index.d.ts",
+	"bin": {
+		"tiny-agents": "./dist/cli.js"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"require": "./dist/index.js",
+			"import": "./dist/index.mjs"
+		}
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"source": "index.ts",
+	"scripts": {
+		"lint": "eslint --quiet --fix --ext .cjs,.ts .",
+		"lint:check": "eslint --ext .cjs,.ts .",
+		"format": "prettier --write .",
+		"format:check": "prettier --check .",
+		"prepublishOnly": "pnpm run build",
+		"build": "tsup src/index.ts --format cjs,esm --clean && tsc --emitDeclarationOnly --declaration",
+		"prepare": "pnpm run build",
+		"test": "vitest run",
+		"check": "tsc",
+		"cli": "tsx src/cli.ts"
+	},
+	"files": [
+		"src",
+		"dist",
+		"tsconfig.json"
+	],
+	"keywords": [
+		"huggingface",
+		"agent",
+		"ai",
+		"llm",
+		"tiny-agent"
+	],
+	"author": "Hugging Face",
+	"license": "MIT",
+	"dependencies": {
+		"@huggingface/inference": "workspace:^",
+		"@huggingface/mcp-client": "workspace:^",
+		"@huggingface/tasks": "workspace:^",
+		"@modelcontextprotocol/sdk": "^1.11.4",
+		"zod": "^3.25.7"
+	}
+}