AI Agents Course by Hugging Face is the open source, certified path into agent engineering. It is free, it ends with a benchmarked final project on a GAIA subset, and it ships two distinct certificates, Fundamentals for passing the Unit 1 quiz and Completion for scoring thirty percent or higher on the GAIA benchmark with your own agent. If you have already done the Kaggle Gen AI Intensive on this site, this is the natural next step.
AI Agents Course: What You’ll Learn
The course teaches agents in theory, in design, and in practice across four units plus three bonus units. You study what agents are, build one with the smolagents framework in Unit 1, side step into LlamaIndex and LangGraph in Unit 2, apply all three frameworks to agentic RAG in Unit 3, and ship a benchmarked final agent in Unit 4. By the end you have a working agent on the Hugging Face Hub and a public score on the Student Leaderboard.
The course is maintained by Ben Burtenshaw and Sergio Paniego, with the original content authored by Joffrey Thomas and Thomas Simonini. The repository on GitHub at huggingface/agents-course has more than thirty thousand stars as of mid 2026 and accepts community pull requests. New content lands on the main branch regularly, with the most recent merge as of this writing dated late June 2026.
This is the second course in the Iqraa AI Agents series. We assume you have either completed the Kaggle Gen AI Intensive or you already know what an LLM is, what prompt engineering looks like, and what an embedding is. If you do not, start with Post 01 in this series before this one.
The Two Certificates Explained
The Hugging Face Agents Course is unusual among free agent courses because it ships two distinct certificates, not one. Knowing the difference matters because most learners stop at the first and never attempt the second.
The Certificate of Fundamentals is earned at the end of Unit 1. You take a quiz on agent fundamentals, the LLM family tree, special tokens, chat templates, the basics of tools and thoughts and actions and observations. Passing the quiz triggers the certificate. The bar is comprehension of the reading material, not engineering ability. Most learners can earn this certificate within a weekend of focused study.
The Certificate of Completion is earned at the end of Unit 4. You build an agent, submit it against a held out subset of the GAIA benchmark, and your agent must score thirty percent or higher. GAIA is a general assistant benchmark with hundreds of real world multi step questions, designed to be hard for current LLMs without tool access. Thirty percent is the bar Hugging Face picked as the threshold for a credible completion signal. Your result is published on the public Student Leaderboard alongside everyone else who has attempted it.
The two certificates test different things. Fundamentals tests reading comprehension. Completion tests engineering. A hiring manager who sees the Completion certificate knows you shipped a working agent against a real benchmark. A hiring manager who sees only the Fundamentals certificate knows you read the material. They are not interchangeable.
The Unit by Unit Syllabus
Verbatim unit titles from the official syllabus on huggingface.co/learn/agents-course:
- Unit 0, Onboarding. Set up your Hugging Face account, sign up to the Discord, choose your path between audit and certification. No code.
- Unit 1, Introduction to Agents. What agents are. LLMs recap, the model family tree, special tokens, chat templates. Tools, thoughts, actions, observations. Build your first agent named Alfred using smolagents and publish it to a Hugging Face Space.
- Bonus Unit 1, Fine tuning an LLM for Function Calling. Train a LoRA adapter on a custom LLM with special tokens separating chain of thought from tool calls. Optional but useful for anyone shipping a specialized agent in production.
- Unit 2, Frameworks for AI Agents. Three frameworks side by side. Unit 2.1 covers smolagents, the Hugging Face house framework. Unit 2.2 covers LlamaIndex for data augmented agents. Unit 2.3 covers LangGraph for stateful graph based agents. Each sub unit ends with a small build.
- Bonus Unit 2, Observability and Evaluation. OpenTelemetry tracing on smolagents. Evaluation on GSM8K. Useful when your agent starts failing and you need to find why.
- Unit 3, Use Case for Agentic RAG. Apply all three Unit 2 frameworks to the same problem, an Alfred agent that answers questions about gala guests. Sports and culture knowledge, no politics or religion, live weather for fireworks timing.
- Unit 4, Final Project. Build your own agent, submit it against the GAIA benchmark subset, earn the Completion certificate if it scores thirty percent or higher.
- Bonus Unit 3, Agents in Games with Pokemon. A playful deep dive into reinforcement flavored agent design. Optional.
The bonus units are skippable and unordered. The numbering in the README places Bonus 3 after Unit 4, which can confuse readers. Treat them as enrichment, not requirements.
The Three Frameworks Side by Side
Unit 2 is where the course becomes uniquely valuable. Most agent courses pick one framework and teach only that. This course teaches three in parallel, with the same depth per framework, which means you leave with a real basis for choosing among them rather than a vendor biased preference.
smolagents is Hugging Face’s own framework. The selling point is lightweight. There are not many abstractions. You write Python functions, you wrap them in a Tool class, you hand them to a CodeAgent, the agent runs. The framework fits in your head. The trade off is that you build more of the orchestration yourself when you need state machines or complex routing. smolagents is the right choice for a first agent, for a prototype, or for a small production workload that does not need a graph executor.
LlamaIndex started as a retrieval framework and grew into a full agent framework. Its strength is data. If your agent’s main job is reading documents, indexing them, retrieving them, and answering questions grounded in them, LlamaIndex has the most batteries included. The trade off is that the abstraction stack is deep. You will spend time understanding the framework before you understand your agent. LlamaIndex is the right choice when retrieval is the core of your application.
LangGraph is the most opinionated of the three. You model your agent as a state graph, with nodes for actions and edges for transitions, and the framework handles the execution. The strength is correctness. State machines are easier to test, easier to debug, easier to reason about than free form agent loops. The trade off is verbosity. A simple LangGraph agent is more lines of code than the same agent in smolagents. LangGraph is the right choice when your agent has multiple stages, conditional branches, or human in the loop checkpoints.
The course does not pick a winner. The Unit 2 capstone asks you to implement the same use case in all three. By the end of Unit 2 you know which one fits your next project.
How GAIA Works and Why Thirty Percent Matters
Unit 4 is where the Completion certificate lives. The structure is intentionally sparse compared to earlier units. You get less guidance. The unit introduction states this directly, that success in Unit 4 will require more advanced coding knowledge and relies on you navigating tasks with less explicit guidance than Units 1 through 3.
The benchmark itself is a subset of GAIA, the General AI Assistants benchmark published in late 2023 by a team including researchers from Meta, Hugging Face, and NYU. GAIA was designed to flip the usual assumption of LLM benchmarks. Most benchmarks test narrow capabilities with questions that are hard for humans to answer because they require specialized knowledge. GAIA tests general capabilities with questions that are easy for humans but hard for LLMs because they require multi step reasoning, tool use, and interaction with the real world.
A representative GAIA question asks the agent to find the title of a specific academic paper given partial information about its author and topic, then to extract the abstract, then to summarize the abstract in three sentences. A human with web search can do this in two minutes. An LLM without tools cannot do it at all. An LLM with tools and a working agent loop can do it most of the time. The question is structured to require chaining multiple tool calls and to penalize agents that stop early or hallucinate.
The held out subset Hugging Face uses for the course is a sample of the broader GAIA benchmark, calibrated so that a competent agent with good tooling can land around thirty to fifty percent. The thirty percent threshold for the Completion certificate is the lower bound of that range. It is not a high bar. It is a credibility bar. An agent that scores thirty on GAIA has at minimum working tool use, working reasoning, and working output formatting. Below that, something is broken.
Your result is published on the Student Leaderboard at huggingface.co/spaces/agents-course/Students_leaderboard. The leaderboard is sorted by score. Hiring managers and recruiters can verify your score there. The leaderboard is the credible signal of completion, not the certificate itself, because the certificate is a PDF anyone could forge and the leaderboard entry is tied to your Hugging Face account.
Worth noting: the GAIA benchmark itself has a public leaderboard at huggingface.co/spaces/gaia-benchmark/leaderboard where research teams submit industrial scale agents against the full benchmark. Top scores on the public GAIA benchmark are above ninety percent as of mid 2026, held by agents from major labs. The course’s thirty percent threshold is for individual learners building their first agent, not for production systems.
The smolagents Framework in Detail
smolagents is Hugging Face’s house framework and the default in Units 1 and 2.1. It deserves a closer look because it shapes how the course teaches agent fundamentals.
The framework has two main agent classes, CodeAgent and ToolCallingAgent. CodeAgent is the default. It works by having the LLM write Python code that calls tools, then executing that code in a sandboxed environment. The advantage is flexibility. The LLM can compose tools in arbitrary ways, loop over them, store intermediate results in variables. The disadvantage is the LLM has to write valid Python, which means small syntax errors break the agent until the LLM fixes them on the next iteration.
ToolCallingAgent is the alternative. It works by having the LLM emit structured tool call requests in JSON, then executing those calls and returning results. The advantage is robustness. JSON tool calls do not have syntax errors the way Python code does. The disadvantage is rigidity. The LLM cannot easily compose tools, loop, or store intermediate state in the same call.
The course uses CodeAgent throughout Units 1 and 2.1 because the framework’s flexibility is more pedagogically useful. You see the LLM’s reasoning as code, which is easier to debug than structured tool calls. Once you understand CodeAgent, switching to ToolCallingAgent is a single class change.
Tools in smolagents are Python functions wrapped in a Tool class or annotated with @tool. The framework extracts the docstring and type hints to generate the tool’s description for the LLM. This is the same pattern as the function calling codelab in the Kaggle Gen AI Intensive on this site, just generalized.
Models in smolagents are pluggable. The default is HfApiModel, which uses Hugging Face Inference endpoints. You can swap in OpenAIServerModel for OpenAI, AnthropicModel for Claude, LiteLLMModel for any of dozens of providers, or TransformersModel for local models. The course uses HfApiModel because it is free and works out of the box. Production users often swap in a stronger paid model for better agent behavior.
The framework is small enough to read in an afternoon. The main module is a few thousand lines of Python. For learners who want to understand agents at the implementation level rather than just the API level, reading the smolagents source is the single highest leverage exercise after the course.
The Hugging Face Ecosystem Around the Course
The course is not standalone. It plugs into a broader Hugging Face ecosystem that you should know about, because the ecosystem is part of why the course is free and part of what you get out of completing it.
The Hugging Face Hub is the platform layer. It hosts models, datasets, and Spaces. Every model the course uses is on the Hub. Every Space you publish is on the Hub. Your Student Leaderboard entry is tied to your Hub account. The Hub is free for individuals and small projects, with paid tiers for enterprise use.
Hugging Face Spaces is the hosting layer. A Space is a Docker container that runs an app. The course uses Spaces to host your Unit 1 Alfred agent, your Unit 2 framework demos, and your Unit 4 final project. Spaces has a free tier with limited CPU and paid tiers for GPU. The free tier is enough to run the course.
Hugging Face Inference is the model serving layer. The course uses Inference endpoints to call the LLM in code examples. Free tier Inference works for the course, though rate limits can slow you down on the most popular models. Paid Inference endpoints remove the rate limits.
Discord is the community layer. The course has a dedicated Discord channel where students ask questions, share agents, and discuss Unit 4 strategies. The course maintainers, including Ben Burtenshaw and Sergio Paniego, are active on Discord. Most learners get stuck somewhere in Unit 2 or Unit 4 and the Discord is the fastest way to unstick.
The ecosystem matters because it is part of the value of the certificate. A hiring manager who sees the Completion certificate and your leaderboard entry can click through to your Hub profile and see every Space you published. The certificate is a signal, the Hub is the portfolio.
Prerequisites and What You Need Installed
The course lists two prerequisites. Basic knowledge of Python, and basic knowledge of LLMs. In practice, basic Python means you can read a class definition, write a function with type hints, and install a package from pip. Basic LLM knowledge means you know what a token is, what a chat template is, and what a prompt looks like. The course recaps LLM fundamentals in Unit 1, so the LLM prerequisite is soft. The Python prerequisite is hard.
You need a free Hugging Face account to push agents to Spaces, submit to the leaderboard, and earn certificates. You need a working Python environment, ideally 3.10 or later. You need an API key for an LLM provider. The course examples use Hugging Face Inference endpoints, but you can swap in OpenAI or Anthropic or a local model with small code changes. smolagents is provider neutral.
You do not need a paid cloud account. Hugging Face Spaces has a free tier that runs your agent. The course is fully runnable on free infrastructure. The only real cost is time.
Run Unit 1 Locally in Five Minutes
The fastest way to see what the course is like is to clone the repo and run Unit 1’s first notebook. The repo doubles as the source of truth for the course text, so a single clone gets you both.
git clone https://github.com/huggingface/agents-course.git
cd agents-course
pip install -r requirements.txt
jupyter notebookOpen Unit 1’s notebook and run the first cells. The build your own agent cell looks like this in compressed form.
from smolagents import CodeAgent, Tool, HfApiModel
def gala_guest_name(query: str) -> str:
"""Look up a gala guest by name fragment.
Args:
query: A fragment of the guest's name.
Returns:
The full guest name as a string, or 'unknown' if no match.
"""
return "Alfred Pennyworth" # stub for the example
guest_tool = Tool(
name="guest_lookup",
func=gala_guest_name,
description="Look up a gala guest by name fragment.",
)
agent = CodeAgent(
tools=[guest_tool],
model=HfApiModel(),
add_base_tools=True,
)
print(agent.run("Who is the guest whose name starts with Alfred?"))That is the entire pattern. You declare tools as Python functions wrapped in Tool, you hand them to a CodeAgent, the agent decides when to call them. Alfred is the throughline character of the course, named for the Batman butler because the first unit’s example is a gala host agent.
Comparison With Other Free Agent Courses
The Hugging Face course is one of several free agent courses we cover in this series. Knowing the differences helps you pick the right one for your background.
Versus the Kaggle Gen AI Intensive on this site. The Kaggle course is broader, covering LLMs, embeddings, RAG, agents, domain models, and MLOps in five days. The Hugging Face course is agents only, deeper on agents, with a benchmarked certificate. Kaggle is the prerequisite, Hugging Face is the agent specialization. If you have not done Kaggle yet, start there.
Versus Microsoft’s AI Agents for Beginners. Microsoft’s course is an eighteen lesson breadth survey on GitHub, taught with the Microsoft Agent Framework and Microsoft Foundry. It covers more topics at less depth per topic and ships no certificate. The Hugging Face course covers fewer topics at more depth per topic and ships two certificates. They are complementary. We cover the Microsoft course as Post 03 in this series.
Versus the LangChain Academy Introduction to LangGraph. The LangChain course is framework specific, teaching only LangGraph, which is one of three frameworks the Hugging Face course covers in Unit 2.3. If you already know you want LangGraph in production, skip directly to the LangChain course. If you want to compare frameworks before committing, do Hugging Face Unit 2 first.
Versus Andrew Ng’s Agentic AI on DeepLearning.AI. Andrew Ng’s course is paid, video first, and vendor neutral. It teaches four design patterns, reflection, tool use, planning, and multi agent, without picking a framework. The Hugging Face course is free, code first, and teaches three frameworks in depth. They pair well. Do Andrew Ng for the design pattern theory, do Hugging Face for the framework practice.
Versus the UC Berkeley LLM Agents MOOC. Berkeley is academic, twelve guest lectures from leading researchers, twelve quizzes, optional labs. The Hugging Face course is industry, four units built by Hugging Face engineers and ML engineers. Berkeley gives you the theoretical foundation. Hugging Face gives you the engineering practice. We cover Berkeley as Post 04 in this series.
What to Build After the Course
The Completion certificate signals you can build an agent that scores thirty percent on GAIA. That is a foundation, not a finish line. Four concrete projects are well suited to the month after you finish Unit 4, ordered by difficulty.
Project one, a research assistant over your papers. Take the Unit 3 agentic RAG pattern, swap the gala documents for your own reading list of academic papers, ship it as a Space. The Space becomes your personal research tool. Two to four hours of work.
Project two, a multi tool productivity agent. Take the CodeAgent pattern from Unit 2.1, add tools for your calendar, your notes, your email, ship it as a CLI. The agent becomes a personal assistant you actually use. Half a day of work if your tools have Python SDKs.
Project three, a specialized agent for your domain. Take the Bonus Unit 1 fine tuning pattern, train a small adapter on your domain data, plug it into a CodeAgent with domain specific tools. This is where the course’s smolagents plus LlamaIndex combination pays off. One to two days of work.
Project four, push your Unit 4 agent past fifty percent on GAIA. Most Unit 4 completers stop at thirty to forty percent. Pushing past fifty requires better tool design, better prompting, and probably a stronger base model than the free Hugging Face Inference tier. The process of pushing from thirty to fifty is where you actually learn agent engineering, because every gain comes from understanding a failure mode.
If you complete project one and project two, you have shipped more than the median course completer. If you complete project four, you have a portfolio piece and a leaderboard entry that signals real engineering skill.
A Worked Example, Unit 3 Agentic RAG in Depth
Unit 3 is the payoff unit. It is where the three frameworks from Unit 2 collide with a real use case. The use case is the Alfred gala host agent from Unit 1, but now Alfred has to answer guest questions that require documents, weather, and live data. The course teaches the same use case three times, once per framework, which lets you compare implementations directly.
The setup is simple. Alfred is hosting a gala. Guests ask questions. Some questions are answerable from background documents Alfred was given before the gala. Some require live weather data because the gala has fireworks and weather matters. Some require sports or culture knowledge that the LLM might or might not have in its pretrained prior. Alfred’s job is to figure out which tool to use for each question, call it, and answer in character.
The agentic RAG pattern differs from naive RAG in one specific way. Naive RAG retrieves the same set of documents for every query, regardless of whether the query needs them. Agentic RAG lets the agent decide whether to retrieve, what to retrieve, and what to do with the result. Sometimes the agent retrieves and answers from the documents. Sometimes the agent skips retrieval because the question is in its pretrained prior. Sometimes the agent retrieves, realizes the documents are insufficient, and calls a different tool.
In smolagents, the implementation is roughly twenty lines of code. You declare a retrieval tool that wraps an embedding based look up, declare a weather tool that calls an API, declare a search tool as fallback, hand them to a CodeAgent. The agent’s prompt establishes Alfred’s persona. The framework handles the loop.
In LlamaIndex, the same agent is more code but more structure. You define a QueryEngine for the documents, an external tool for weather, a router that decides which QueryEngine to invoke. LlamaIndex’s strength is the QueryEngine abstraction, which handles chunking, embedding, retrieval, and synthesis in one object. The trade off is the abstraction is one you have to learn.
In LangGraph, the same agent is the most code but the most explicit. You define a state with the question, the retrieved documents, the weather, the answer. You define nodes for retrieval, weather lookup, synthesis. You define edges that route based on what the question asks. LangGraph’s strength is that the routing logic is in the graph definition, where you can see it, not in the model’s prompt where you cannot.
By the end of Unit 3 you have run the same problem three ways and you have a real opinion about which framework fits your next project. That opinion is the unit’s output.
AI Agents Course: Common Mistakes to Avoid
The course is well structured but it invites a few predictable mistakes that show up in Discord and on the leaderboard discussion.
- Stopping at the Fundamentals certificate. The Fundamentals certificate is the reading comprehension test. The Completion certificate is the engineering test. Stopping at Fundamentals means you skipped the actual building. If your goal is a credential that signals skill, do Unit 4.
- Trying to use the same framework for every unit. Unit 2 teaches three frameworks on purpose. If you skim two of them and only build in the third, you miss the point. Build the same use case in all three, even if it feels repetitive. The comparison is the lesson.
- Skipping Bonus Unit 2 on observability. When your Unit 4 agent fails the benchmark, and it will, you need observability to figure out why. Bonus Unit 2 covers OpenTelemetry tracing for smolagents. Skipping it means debugging by print statements on a benchmark with hundreds of questions.
- Not reading the GAIA paper before Unit 4. The GAIA paper is short and readable. It explains what the benchmark tests and what kinds of agents do well. Reading it before Unit 4 saves you from building the wrong kind of agent for the benchmark.
AI Agents Course: Best Practices
- Do the units in order. Unit 2’s three frameworks each assume Unit 1’s agent fundamentals. Unit 3 assumes Unit 2. Unit 4 assumes everything.
- Publish your Unit 1 Alfred agent to a Hugging Face Space even if you do not care about the certificate. The Space is your portfolio piece. Anyone you show it to can click and interact with the agent.
- Pick a single LLM provider early and stick with it across all units. Switching providers mid course means reworking your environment and your prompts. The course examples use Hugging Face Inference, which is free and works out of the box.
- Pair the course with a browse the AI Agents track on this site for the other courses. We cover Microsoft AI Agents for Beginners next as a complementary breadth survey, and LangGraph in depth later in the track.
- Read the Student Leaderboard before you start Unit 4. Knowing what scores other learners achieved sets a realistic target. As of mid 2026 the median score is around forty percent and the top score is over eighty percent.
AI Agents Course: Frequently Asked Questions
Is the Hugging Face AI Agents Course still free in 2026?
Yes. The course text is open source MDX in the GitHub repository under Apache 2.0. The Hugging Face Hub is free. The Hugging Face Spaces free tier runs your Unit 1 Alfred agent. The Student Leaderboard is free to submit to. There are no paid tiers and no upsells.
Do I need a Hugging Face account?
You can read the units without one. You need a free Hugging Face account to publish agents to Spaces, submit to the GAIA Student Leaderboard, take the Unit 1 quiz for the Fundamentals certificate, and earn the Completion certificate.
How long does the course take?
The course site recommends three to four hours per week, one chapter per week. With four main units that is roughly twelve to sixteen weeks at the recommended pace. In practice, learners with prior Python experience finish Units 1 and 2 in a weekend and Unit 3 in another weekend. Unit 4 is open ended, the benchmark does not have a deadline.
What is the difference between the Fundamentals and Completion certificates?
Fundamentals is earned at the end of Unit 1 by passing a quiz on agent fundamentals. Completion is earned at the end of Unit 4 by building an agent that scores thirty percent or higher on a GAIA benchmark subset. Fundamentals tests reading. Completion tests engineering.
Is there a deadline for the course?
No deadline is stated anywhere in the README or any unit introduction. The course is currently active and under active maintenance. Hugging Face could change this policy, but as of mid 2026 the certificates do not expire.
How does this course compare to the Kaggle Gen AI Intensive on this site?
The Kaggle course is a broad survey of all of generative AI across five days, only one of which is agents. The Hugging Face course is agents only, deeper, and graded against a real benchmark. Kaggle is the prerequisite, Hugging Face is the agent specialization.
AI Agents Course is the right second course if you have completed the Kaggle Gen AI Intensive and want agent specific depth with a real certificate. Pair it with Microsoft AI Agents for Beginners for a second framework opinion, and with the LangGraph course later in this track for production grade agent graphs.