{"slug": "getting-started-with-hugging-face-ml-intern-your-first-ml-agent", "title": "Getting Started with Hugging Face ML Intern: Your First ML Agent", "summary": "Hugging Face released ML Intern, an open-source CLI agent that automates machine learning tasks such as fine-tuning models, exploring research papers, and launching GPU training jobs. The tool uses the Hugging Face stack and an iterative workflow to reduce repetitive setup work, with published results showing improved performance on scientific reasoning benchmarks.", "body_md": "# Getting Started with Hugging Face ML Intern: Your First ML Agent\n\nYou describe the model. It writes the code, runs the training, and ships the checkpoint. Welcome to ML Intern.\n\n## # Getting Started With ML Intern\n\nHave you ever gotten stuck in that familiar situation where you have a model idea, but the gap between “I read the paper” and “I have a trained checkpoint on the Hub” still eats up an entire weekend? ML Intern is ** Hugging Face**'s attempt to shrink that gap. It is an open-source command-line interface (CLI) agent from Hugging Face that lets you describe machine learning tasks in plain English.\n\nInstead of manually piecing everything together, you can ask it to fine-tune a model, explore a research paper, or start a training run. It handles the kind of work a junior machine learning engineer would usually do: reading docs, searching GitHub, writing scripts, kicking off jobs, checking results, and iterating.\n\nIt is built on the Hugging Face stack end to end. It can search papers on the Hub and ** arXiv**, work with datasets, launch graphics processing unit (GPU) training jobs using HF Jobs, log experiments with\n\n**, and publish trained models back to the Hub when everything is done. Under the hood, it uses the**\n\n[Trackio](https://huggingface.co/docs/trackio/index)**framework and routes model calls through Hugging Face Inference Providers or local endpoints if you would rather not burn API credits.**\n\n[smolagents](https://github.com/huggingface/smolagents)It is less like “ChatGPT for code” and more like a research intern who actually has shell access and a Hugging Face account. The repository is ** huggingface/ml-intern**. You can experiment with it, adapt it to your needs, or even make it part of your continuous integration (CI) workflow.\n\n## # Understanding Why ML Intern Helps\n\nReal machine learning research is not linear. You read something, chase a citation, find a dataset that almost fits, rewrite the data loader twice, train, realize your evaluation was wrong, fix it, and train again. ML Intern is designed to automate much of this repetitive work so you can focus on research decisions instead of repeatedly writing setup code.\n\nUnlike traditional chatbots, it does not stop after generating one answer. Instead, it follows an iterative workflow.\n\nThe ML Intern workflow loop\n\nHugging Face published results showing the agent improving from about 10% to about 32% on GPQA, a benchmark for scientific reasoning, in under 10 hours on a small Qwen model. Whether or not you care about that specific benchmark, it still gives you a good sense that this is not a toy that writes one script and stops. It is built to keep going.\n\nThat is enough background to understand why the project exists. Now it is time to use it, but first, make sure you have the required setup in place.\n\n## # Checking the Prerequisites\n\nYou will need a Hugging Face account, Python, ** uv**, and a few tokens.\n\n| Token | Why Is It Needed? | Recommended Permission |\n|---|---|---|\n`HF_TOKEN` |\nAccess the Hugging Face Hub, Inference Providers, GPU sandboxes, and training jobs. | Write (recommended) or Read if you only plan to explore and will not upload anything |\n`GITHUB_TOKEN` |\nSearch public repositories when the agent looks for reference implementations.\n|\nFine-grained token with read-only access to public repositories |\n\nIf you skip `HF_TOKEN`\n\n, the CLI will ask for one on first launch unless you are running a fully local model. If you are unsure how to create either token, check the official guides for ** Hugging Face Access Tokens** and\n\n**.**\n\n[GitHub Personal Access Tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)\n\n## # Installing ML Intern\n\nCopy and run the following commands.\n\n```\ngit clone git@github.com:huggingface/ml-intern.git\ncd ml-intern\nuv sync\nuv tool install -e .\n```\n\nOnce that is done, `ml-intern`\n\nworks from any directory. A quick sanity check:\n\n```\nml-intern --help\n```\n\nAdd the following to your `.env`\n\nfile, or export equivalent variables in your shell.\n\n```\nHF_TOKEN=hf_your_token_here\nGITHUB_TOKEN=ghp_your_token_here\n```\n\n## # Comparing Interactive and Headless Modes\n\nBefore starting your first run, it helps to understand the two modes the agent supports.\n\n#### // Using Interactive Mode\n\nRun the following command to launch your machine learning agent.\n\n```\nml-intern\n```\n\nThis opens a chat session. You can describe what you want, the agent plans the steps, asks for approval before risky operations, and keeps you updated as it works. You can even swap models mid-conversation with:\n\n```\n/model\n```\n\nSome good prompts for a beginner are:\n\n- \"Find a small classification dataset on the Hub and show me how to load it with the\nlibrary.\"[datasets](https://huggingface.co/docs/datasets/index) - \"Summarize this paper and list what datasets it uses: [arXiv link].\"\n- \"Write a minimal low-rank adaptation (LoRA) fine-tuning script for\n`Qwen2.5-0.5B`\n\non a tiny public dataset. Do not launch training yet, just write the script.\"\n\n#### // Using Headless Mode\n\n```\nml-intern \"fine-tune llama on my dataset\"\n```\n\nThis mode uses a single prompt and auto-approves actions. The agent runs until it finishes or hits the iteration limit. This is the mode you would drop into a GitHub Action for nightly experiments.\n\nSome useful flags once you are comfortable:\n\n```\nml-intern --max-iterations 100 \"your prompt\"   # cap the budget\nml-intern --no-stream \"your prompt\"            # cleaner output for CI logs\nml-intern --sandbox-tools \"test this in a GPU sandbox\"\nml-intern --model moonshotai/Kimi-K2.7-Code:novita \"your prompt\"\n```\n\nIf you are just getting started, try interactive mode first. Once you are comfortable, switch to headless mode for automation.\n\n## # Starting Your First Run\n\nUse the same prompt in both modes so you can see how they differ. We will start with a small task that does not involve training. The goal is simply to find a dataset on the Hugging Face Hub and write a loader script.\n\nThe prompt:\n\n```\nFind the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to load_dataset.py. Do not run training.\n```\n\nMake sure your `.env`\n\nfile includes both `HF_TOKEN`\n\nand `GITHUB_TOKEN`\n\nbefore you begin.\n\n#### // Running in Interactive Mode\n\nYou open a chat session, type the prompt, watch it work, and follow up if needed.\n\nRun this command:\n\n```\nml-intern\n```\n\nThen type your prompt at the `>`\n\nprompt:\n\n```\nFind the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to /tmp/load_dataset_interactive.py. Do not run training.\n```\n\nOutput:\n\n```\nInitializing agent runtime...\n User: kanwal8008\n Model: zai-org/GLM-5.2:novita\n Tool runtime: local filesystem\n Tools: 25 loaded\n/help for commands · /model to switch · /quit to exit\nReady. Let's build something impressive.\n> Find the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to /tmp/load_dataset_interactive.py. Do not run training.\nThe dataset is cornell-movie-review-data/rotten_tomatoes. It has a single default config with train/validation/test splits, columns are text and label. Writing the script now.\n▸ write {\"content\": \"\\\"\\\"\\\"Load the rotten_tomatoes dataset from the HF Hub and print th...\"}\nDone. The script is saved to /tmp/load_dataset_interactive.py.\nWhat it does:\n - Loads cornell-movie-review-data/rotten_tomatoes via datasets.load_dataset\n - Prints the list of splits (train, validation, test)\n - Prints the first training example (a {\"text\": ..., \"label\": ...} dict)\nDataset details:\n - Columns: text (movie review sentence), label (0 = negative, 1 = positive)\n - ~10.6k examples total (5,331 positive / 5,331 negative)\nYou can run it locally with:\n python /tmp/load_dataset_interactive.py\n> /quit\nBye.\n```\n\nFile it created (`/tmp/load_dataset_interactive.py`\n\n):\n\n```\n\"\"\"Load the rotten_tomatoes dataset from the HF Hub and print the first example.\"\"\"\nfrom datasets import load_dataset\n\n# Load the full dataset (all splits) from the Hub\nds = load_dataset(\"cornell-movie-review-data/rotten_tomatoes\")\n\nprint(\"Dataset splits:\", list(ds.keys()))\nfirst_train = ds[\"train\"][0]\nprint(\"First training example:\")\nprint(first_train)\nprint(\"\\nLabel meaning: 0 = negative, 1 = positive\")\n```\n\nInteractive mode gives you more context as it works, including dataset details, what the script does, and how to run it. You can also ask follow-up questions before typing `/quit`\n\n.\n\n#### // Running in Headless Mode\n\nOne command, the agent runs from start to finish, then exits.\n\nRun this command:\n\n```\nml-intern --max-iterations 15 --no-stream \\\n\"Find the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to /tmp/load_dataset.py. Do not run training.\"\n```\n\nOutput:\n\n```\nHF token loaded\nModel: zai-org/GLM-5.2:novita\nTool runtime: local filesystem\nMax iterations: 15\nPrompt: Find the rotten_tomatoes dataset on the Hub and write a short Python script that loads it with datasets and prints the first example. Save it to /tmp/load_dataset.py. Do not run training.\n---\n▸ hf_inspect_dataset {\"dataset\": \"cornell-movie-review-data/rotten_tomatoes\", \"sample_rows\": 1}\n▸ write {\"content\": \"from datasets import load_dataset\\n\\ndataset = load_dataset(\\\"rotte...\"}\n▸ bash {\"command\": \"cd /tmp && python load_dataset.py\", \"description\": \"Run the dataset...\"}\nDone. The script is saved at /tmp/load_dataset.py and verified working. It loads the rotten_tomatoes dataset (dataset ID: cornell-movie-review-data/rotten_tomatoes) via datasets.load_dataset and prints the first training example:\n {'text': 'the rock is destined to be the 21st century\\'s new \" conan \" ...',\n 'label': 1}\nThe dataset has two columns -- text (the review) and label (0 = negative, 1 = positive) -- across train (8,530 rows), validation (1,066), and test (1,066) splits.\n--- Agent turn_complete (history_size=9) ---\n```\n\nFile it created (`/tmp/load_dataset.py`\n\n):\n\n``` python\nfrom datasets import load_dataset\ndataset = load_dataset(\"rotten_tomatoes\", split=\"train\")\nprint(dataset[0])\n```\n\nHeadless mode auto-approves everything. This is useful when you know what you want and do not need to steer the run in the middle.\n\n## # Running ML Intern With Local Models\n\nIf you would rather not use Hugging Face Inference Providers or pay for API usage, ML Intern can also work with locally hosted models. Instead of downloading and loading model weights itself, ML Intern connects to an OpenAI-compatible server that is already running on your machine.\n\nThat means you can use popular local inference frameworks such as:\n\nFor example, if you are using Ollama, you can run:\n\n```\nml-intern --model ollama/llama3.1:8b \"Summarize the README in this repository.\"\n```\n\nOr, if you are running a model with vLLM:\n\n```\nml-intern --model vllm/meta-llama/Llama-3.1-8B-Instruct \"Your prompt\"\n```\n\nIf your local model server is running on a custom endpoint, you can configure it with environment variables:\n\n```\nLOCAL_LLM_BASE_URL=http://localhost:8000\nLOCAL_LLM_API_KEY=optional-if-your-server-requires-it\n```\n\nSome providers also support their own environment variables. For example, if you are using Ollama, you can set `OLLAMA_BASE_URL`\n\n, which takes precedence over the generic `LOCAL_LLM_BASE_URL`\n\n. One important thing to keep in mind is that a tiny local model will struggle with multi-step training pipelines. It is fine for exploration and script drafting, but for serious agent loops, you will want something with more reasoning headroom.\n\n## # Understanding How ML Intern Works\n\nYou do not need to memorize the architecture, but it helps to know why the agent sometimes pauses and asks you to approve something. The agent runs an iterative loop of up to 300 turns by default. The flowchart below gives a rough idea of what happens on each call.\n\nHow ML Intern processes each call\n\nOne of ML Intern's biggest strengths is the number of tools it can use out of the box. Built-in tools cover the HF ecosystem, including docs, datasets, repositories, papers, and jobs, plus GitHub search, local file operations, planning helpers, and anything you attach through ** Model Context Protocol (MCP)**. There is even a doom loop detector that catches repeated tool calls with the same arguments, which is a familiar problem if you have used coding agents before.\n\nEvery session can auto-upload to a private dataset on your Hub account (`{username}/ml-intern-sessions`\n\n) in a format the ** Agent Trace Viewer** understands. These traces are especially useful for debugging because they let you inspect every reasoning step the agent took. If something goes wrong, you can open the session in the Agent Trace Viewer and see exactly where the agent made a poor decision.\n\nYou can also control how traces are shared during a session:\n\n```\n/share-traces private\n/share-traces public\n```\n\nOr you can disable trace uploads entirely through the configuration file if you do not want to save session history.\n\n## # Avoiding Common Mistakes\n\n**Be specific with your prompts.**“Fine-tune llama” is vague. “Fine-tune`meta-llama/Llama-3.2-1B`\n\non`imdb`\n\nwith LoRA, max 1 epoch, do not push to Hub” is better.**Watch the approvals.** Training jobs cost money. Sandboxes cost money. The agent will ask, so do not blindly approve everything on your first run.**Set** The default limit of 300 iterations is great for complex tasks but can waste compute during testing.`--max-iterations`\n\nif you are experimenting.**Check your traces.** When something strange happens, your private session dataset on the Hub is the black box recorder.\n\n## # Taking the Next Steps\n\nML Intern will not replace your judgment. You still need to read the training logs, sanity-check the evaluation, and decide whether 32% on GPQA is actually what you wanted. But if you have ever stared at a blank `train.py`\n\nwondering where to start, having an intern who already knows the Hub is a strong first step.\n\nRun `ml-intern`\n\n, give it something small, and see what it does. That is the game at the beginning. A few practical next steps:\n\n**Explore the GitHub repository.** Browse the source code, check out examples, and stay current with new features and improvements.**Create your own custom tools.** ML Intern is built to be extensible. You can add your own tools by modifying the`agent/core/tools.py`\n\nfile and reinstalling the package:\n\n```\nuv tool install -e . --force\n```\n\n**Connect MCP servers.** If you are using MCP, you can attach external tools and services by updating the`configs/cli_agent_config.json`\n\nfile. Environment variables such as`${YOUR_TOKEN}`\n\nare automatically loaded from your`.env`\n\nfile.**Enable Slack notifications.** Set`SLACK_BOT_TOKEN`\n\nand`SLACK_CHANNEL_ID`\n\nif you want ping-when-done alerts.\n\nis a machine learning engineer and a technical writer with a profound passion for data science and the intersection of AI with medicine. She co-authored the ebook \"Maximizing Productivity with ChatGPT\". As a Google Generation Scholar 2022 for APAC, she champions diversity and academic excellence. She's also recognized as a Teradata Diversity in Tech Scholar, Mitacs Globalink Research Scholar, and Harvard WeCode Scholar. Kanwal is an ardent advocate for change, having founded FEMCodes to empower women in STEM fields.\n\n**Kanwal Mehreen**", "url": "https://wpnews.pro/news/getting-started-with-hugging-face-ml-intern-your-first-ml-agent", "canonical_source": "https://www.kdnuggets.com/getting-started-with-hugging-face-ml-intern-your-first-ml-agent", "published_at": "2026-07-06 14:00:31+00:00", "updated_at": "2026-07-07 01:36:57.526758+00:00", "lang": "en", "topics": ["machine-learning", "ai-agents", "developer-tools", "ai-tools"], "entities": ["Hugging Face", "ML Intern", "HF Jobs", "Trackio", "smolagents", "Qwen", "arXiv", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/getting-started-with-hugging-face-ml-intern-your-first-ml-agent", "markdown": "https://wpnews.pro/news/getting-started-with-hugging-face-ml-intern-your-first-ml-agent.md", "text": "https://wpnews.pro/news/getting-started-with-hugging-face-ml-intern-your-first-ml-agent.txt", "jsonld": "https://wpnews.pro/news/getting-started-with-hugging-face-ml-intern-your-first-ml-agent.jsonld"}}