Getting Started with Face Hugging ML Intern: Your First ML Agent

# Getting Started With ML Intern

Have you ever been stuck in that familiar situation where you have a model idea, but the gap between “I read the paper” and “I have a qualified test site on the Hub” is still eating up the weekend? ML Intern A Hugging Facean attempt to reduce that gap. An open source command line agent (CLI) from Hugging Face that lets you describe machine learning tasks in plain English.

Instead of putting everything together manually, you can ask them to fine-tune a model, check a research paper, or start training. It handles the kind of work that a small machine learning developer used to do: read documentation, search GitHub, write scripts, fire functions, test results, and iterate.

It is built at the end of the Hugging Face stack. Can search for papers on the Hub as well arXivwork with datasets, run graphics processing unit (GPU) training jobs using HF Jobs, log tests with Trackioand publish the trained models back to the Hub when everything is done. Under the hood, it uses a smolagents outline and route model calls with Hugging Face Inference Providers or repositories if you'd rather not burn API credits.

It's as little as “ChatGPT code” and it's like a research intern with shell access and a Hugging Face account. The repository is huggingface/ml-intern. You can test it, adapt it to your needs, or make it part of your continuous integration (CI) workflow.

# Understanding Why an ML Intern Helps

Real machine learning research is not straightforward. You learn something, rush to quote, find a dataset that is roughly equivalent, rewrite the data loader twice, train, realize your test 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.

Unlike traditional chatbots, they don't stop after generating one response. Instead, it follows a repetitive workflow.

ML Intern workflow loop

Hugging Face has published results showing that the agent improves from about 10% to about 32% in GPQA, a benchmark for scientific reasoning, in less than 10 hours on a small Qwen model. Whether you care about that particular benchmark or not, it still gives you a good idea that this isn't a toy that writes one text and stops. It's built to last.

That's enough background to understand why the project exists. Now it's time to use it, but first, make sure you have the necessary setup in place.

# Required Assessments

You will need a Hugging Face account, Python, uvand a few tokens.

If you skip HF_TOKENthe CLI will ask for one on first launch unless you are using the full local model. If you are not sure how to create any token, check the official guides Face Hugging Access Tokens again GitHub Personal Access Tokens.

# Features ML Intern

Copy and run the following commands.

git clone [email protected]:huggingface/ml-intern.git
cd ml-intern
uv sync
uv tool install -e .

Once that is done, ml-intern works in any directory. A quick psychological test:

Add the following to yours .env file, or pass the equivalent variable to your shell.

HF_TOKEN=hf_your_token_here
GITHUB_TOKEN=ghp_your_token_here

# Comparing Interactive and Headless Methods

Before starting your first use, it is useful to understand the two modes supported by the agent.

// Using Interactive Mode

Run the following command to start the learning agent for your machine.

This opens a chat session. You can define what you want, the agent plans the steps, asks for permission before the dangerous operation, and keeps you updated as it works. You can even switch models during a conversation by:

Some good tips for a beginner are:

• “Get a small classification dataset from the Hub and show me how to load it with data sets library.”
• “Summary this paper and write which data sets are used: [arXiv link].”
• “Write a low-level tuning script (LoRA). Qwen2.5-0.5B in a small public dataset. Don't start training yet, just write the script.”

// Using Headless Mode

ml-intern "fine-tune llama on my dataset"

This mode uses a single prompt and allows actions automatically. The agent runs until it finishes or reaches the iteration limit. This is a mod you can add to GitHub Action for nightly testing.

Some useful flags once you are free:

ml-intern --max-iterations 100 "your prompt"   # cap the budget
ml-intern --no-stream "your prompt"            # cleaner output for CI logs
ml-intern --sandbox-tools "test this in a GPU sandbox"
ml-intern --model moonshotai/Kimi-K2.7-Code:novita "your prompt"

If you're just starting out, try interactive mode first. Once you're comfortable, switch to headless mode to do it yourself.

# Starting Your First Run

Use the same information in both methods to see how they differ. We will start with a small task that does not involve training. The goal is to simply get the dataset from Hugging Face Hub and write a loader script.

Information:

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 load_dataset.py. Do not run training.

Be sure of yours .env file includes both HF_TOKEN again GITHUB_TOKEN before you start.

// It works in interactive mode

You open a chat session, type in information, watch it in action, and follow up if needed.

Run this command:

Then type your command in > immediately:

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.

Output:

Initializing agent runtime...
 User: kanwal8008
 Model: zai-org/GLM-5.2:novita
 Tool runtime: local filesystem
 Tools: 25 loaded
/help for commands · /model to switch · /quit to exit
Ready. Let's build something impressive.
> 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.
The 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.
▸ write {"content": """"Load the rotten_tomatoes dataset from the HF Hub and print th..."}
Done. The script is saved to /tmp/load_dataset_interactive.py.
What it does:
 - Loads cornell-movie-review-data/rotten_tomatoes via datasets.load_dataset
 - Prints the list of splits (train, validation, test)
 - Prints the first training example (a {"text": ..., "label": ...} dict)
Dataset details:
 - Columns: text (movie review sentence), label (0 = negative, 1 = positive)
 - ~10.6k examples total (5,331 positive / 5,331 negative)
You can run it locally with:
 python /tmp/load_dataset_interactive.py
> /quit
Bye.

The generated file (/tmp/load_dataset_interactive.py):

"""Load the rotten_tomatoes dataset from the HF Hub and print the first example."""
from datasets import load_dataset

# Load the full dataset (all splits) from the Hub
ds = load_dataset("cornell-movie-review-data/rotten_tomatoes")

print("Dataset splits:", list(ds.keys()))
first_train = ds["train"][0]
print("First training example:")
print(first_train)
print("nLabel meaning: 0 = negative, 1 = positive")

Interactive mode gives you more context as it runs, including details of the data set, what the script does, and how it is used. You can also ask follow-up questions before typing /quit.

// It works in headless mode

One command, the agent starts from the beginning to the end, and then exits.

Run this command:

ml-intern --max-iterations 15 --no-stream 
"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."

Output:

HF token loaded
Model: zai-org/GLM-5.2:novita
Tool runtime: local filesystem
Max iterations: 15
Prompt: 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.
---
▸ hf_inspect_dataset {"dataset": "cornell-movie-review-data/rotten_tomatoes", "sample_rows": 1}
▸ write {"content": "from datasets import load_datasetnndataset = load_dataset("rotte..."}
▸ bash {"command": "cd /tmp && python load_dataset.py", "description": "Run the dataset..."}
Done. 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:
 {'text': 'the rock is destined to be the 21st century's new " conan " ...',
 'label': 1}
The 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.
--- Agent turn_complete (history_size=9) ---

The generated file (/tmp/load_dataset.py):

from datasets import load_dataset
dataset = load_dataset("rotten_tomatoes", split="train")
print(dataset[0])

Headless mode enables everything automatically. This is useful if you know what you want and you don't need to direct the run in between.

# Using ML Intern with Local Models

If you prefer not to use Hugging Face Inference Providers or pay for API usage, ML Intern can also work with locally hosted models. Instead of downloading and uploading the model weights itself, ML Intern connects to an OpenAI compatible server already running on your machine.

That means you can use popular local parameters such as:

For example, if you use Ollama, you can run:

ml-intern --model ollama/llama3.1:8b "Summarize the README in this repository."

Or, if you're running the model with vLLM:

ml-intern --model vllm/meta-llama/Llama-3.1-8B-Instruct "Your prompt"

If your local model server is running on a custom repository, you can configure it with the environment variable:

LOCAL_LLM_BASE_URL=
LOCAL_LLM_API_KEY=optional-if-your-server-requires-it

Some providers also support their own environment variables. For example, if you use Ollama, you can set OLLAMA_BASE_URLwhich takes precedence over generic LOCAL_LLM_BASE_URL. One important thing to remember is that a small local model will struggle with multi-step training pipelines. It's fine for testing and scripting, but for critical agent loops, you'll want something with a little more conceptual headroom.

# Understanding How an ML Intern Works

You don't need to memorize the architecture, but it helps to know why the agent sometimes pauses and asks you to allow something. The agent runs an iterative loop of up to 300 turns automatically. The flowchart below gives a rough idea of ​​what happens in each call.

How ML Intern processes each call

One 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 documents, datasets, repositories, papers, and functions, as well as GitHub search, local file operations, editing assistants, and whatever you attach. Model Context Protocol (MCP). There's even a doom loop detector that catches repeated tool calls with the same arguments, which is a common problem if you've used coding agents before.

Each time we can automatically upload them to a private dataset in your Hub account ({username}/ml-intern-sessions) in the format Agent Trace Viewer you understand. These traces are especially useful for debugging because they allow you to examine every logical step taken by the agent. If something goes wrong, you can open a session in the Agent Trace viewer and see where the agent made a bad decision.

You can also control how tracking is distributed during a session:

/share-traces private
/share-traces public

Or you can disable load tracking entirely via a configuration file if you don't want to save session history.

# Avoiding Common Mistakes

• Be specific with your instructions. “Fine-tune llama” is vague. “All right meta-llama/Llama-3.2-1B to imdb with LoRA, max 1 epoch, don't push to Hub” is better.
• View permissions. Training jobs cost money. Sandboxes cost money. The agent will ask, so don't give everything out of hand at your first appointment.
• Set up --max-iterations if you try. The default limit of 300 iterations is good for complex tasks but can waste computations during testing.
• Check your following. If something unusual happens, the data set of your private session on the Hub is a black box recorder.

# Taking Next Steps

ML Intern will not replace your judgment. You still need to read the training logs, test your mind, and decide if 32% in GPQA is what you really wanted. But if you've ever stared at anything train.py wondering where to start, having an intern who already knows the Hub is a solid first step.

Run ml-interngive him a little something, see what he does. This is the game at the beginning. A few practical steps follow:

• Check out the GitHub repository. Browse source code, check examples, and stay informed about new features and improvements.
• Create your own custom tools. ML Intern is designed to be scalable. You can add your tools by changing the file agent/core/tools.py file and reinstall the package:

uv tool install -e . --force

• Connect MCP servers. If you use MCP, you can attach external tools and services by updating the file configs/cli_agent_config.json file. Environmental variables such as ${YOUR_TOKEN} are loaded automatically from your .env file.
• Enable Slack notifications. Set up SLACK_BOT_TOKEN again SLACK_CHANNEL_ID if you want ping-if notifications.

Kanwal Mehreen is a machine learning engineer and technical writer with a deep passion for data science and the intersection of AI and medicine. He co-authored the ebook “Increasing Productivity with ChatGPT”. As a Google Generation Scholar 2022 for APAC, he strives for diversity and academic excellence. He has also been recognized as a Teradata Diversity in Tech Scholar, a Mitacs Globalink Research Scholar, and a Harvard WeCode Scholar. Kanwal is a passionate advocate for change, having founded FEMCodes to empower women in STEM fields.