# ai-agents-for-beginners is eighteen Azure-bound lessons you can start in the middle of

> An MIT-licensed Microsoft course whose lesson list is the repository's directory structure, and whose real curriculum is the dependency pinning and environment file rather than the prose. Solid on agent design patterns, and honest about the fact that nearly every notebook needs a funded Azure endpoint.

**microsoft/ai-agents-for-beginners** — GitHub describes it as 18 Lessons to Get Started Building AI Agents. The repository metadata lists Jupyter Notebook as its primary language. The metadata lists the MIT license. This article stays within the project description and details documented in the GitHub repository README.

- Repository: https://github.com/microsoft/ai-agents-for-beginners
- Website: https://aka.ms/ai-agents-beginners
- Stars: 76,092 · Forks: 24,989
- Language: Jupyter Notebook
- License: MIT
- Published: 2026-08-13 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/microsoft-ai-agents-for-beginners

## The lesson order is the directory listing, and the README says start anywhere

There is no syllabus file to reconcile with the code. The curriculum is eighteen numbered directories: 01-intro-to-ai-agents, 02-explore-agentic-frameworks, 03-agentic-design-patterns, 04-tool-use, 05-agentic-rag, 06-building-trustworthy-agents, 07-planning-design, 08-multi-agent, 09-metacognition, 10-ai-agents-production, 11-agentic-protocols, 12-context-engineering, 13-agent-memory, 14-microsoft-agent-framework, 15-browser-use, 16-deploying-scalable-agents, 17-creating-local-ai-agents and 18-securing-ai-agents. In front of them sits 00-course-setup, which is where configuration lives.

Read as a sequence, the order is an argument about what to learn before what. Frameworks come second, after an introduction, on the assumption you should know what you are choosing between. Design patterns precede tool use, so the tool-calling lesson arrives after the reasons for wanting one. Trustworthy agents at 06 comes before planning at 07, and production at 10 comes before the protocol, context and memory lessons that a production system actually needs.

The README nonetheless tells you that each lesson covers its own topic so you can start wherever you like, and for an experienced reader that is the right instruction. Lesson 14 is the Microsoft Agent Framework lesson, so someone arriving from another framework has a natural entry point that is not lesson 1.

## Dropping the translations takes a sparse checkout, and the command differs by shell

The repository carries more than fifty language translations, which the README says significantly increases the download size. The documented way to avoid that is not a shallow clone but a sparse checkout, given separately for Bash on macOS and Linux and for CMD on Windows:

```bash
git clone --filter=blob:none --sparse https://github.com/microsoft/ai-agents-for-beginners.git
cd ai-agents-for-beginners
git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'
```

The Windows variant is the same three lines with double-quoted patterns instead of single-quoted ones, which is the only difference between the two blocks. Both exclude the translations directory and the translated_images directory, the second of which exists so that images inside translated lessons do not pull in their localised copies.

The result is described as everything needed to complete the course with a much faster download. Worth knowing that this is the only install step in the repository: there is no pip command in the README, no environment activation recipe, and no notebook server instruction. Setup is delegated to the 00-course-setup lesson, and the configuration it expects lives in .env.example at the root.

## agent-framework-core is pinned to 1.10.0 because 1.11.0 removed what the notebooks call

The requirements file explains its own pins in comments, which makes it the most instructive file in the repository. agent-framework-core is held at exactly 1.10.0 because version 1.11.0 introduced breaking API changes that the course notebooks depend on: it removed ChatMessage and HostedWebSearchTool, changed the Message constructor, and dropped the model= argument on Agent.run(). The companion packages agent-framework-foundry and agent-framework-openai are held on the same 1.10.x line with compatible-release constraints.

The second comment is a lesson in packaging. agent-framework-core is pinned directly rather than through the agent-framework meta-package, because the meta-package's [all] extras pull in unpinned integration sub-packages whose newer pre-releases require agent-framework-core at 1.11.0 or later, which produces a pip conflict. In other words, the obvious install command is the one that breaks, and the file is arranged specifically to steer you away from it.

Two more constraints are stated the same way. openai is held at 1.108.1 or newer because the Responses API requires it. Lessons 17 and 18 bring their own dependencies, foundry-local-sdk and chromadb for local agents with Foundry Local and Qwen, and jcs and pynacl for securing agents with cryptographic receipts. The rest is a conventional data stack: httpx, ipykernel, nest-asyncio, numpy, pandas, pillow, python-dotenv and uvicorn, plus mcp[cli] for the Model Context Protocol and a2a-sdk.

## GitHub Models is gone from the samples, so Azure OpenAI is the only documented path

The environment template carries a deprecation notice that changes what a reader can expect. GitHub Models is marked as deprecated, retiring in July 2026, and noted as not supporting the Responses API, with the statement that all samples now use Azure OpenAI with the Responses API instead. That is a narrow door: the free-tier path many people start with is closed by design.

The variables reflect the same narrowing. AZURE_AI_PROJECT_ENDPOINT is marked required for most lessons, and AZURE_AI_MODEL_DEPLOYMENT_NAME is set to gpt-5-mini, with a comment that gpt-4.1 and gpt-4.1-mini retire on 14 Oct 2026. The direct model path uses AZURE_OPENAI_ENDPOINT and AZURE_OPENAI_DEPLOYMENT on the stable /openai/v1/ endpoint, with no api_version needed, and AZURE_OPENAI_API_KEY offered as an alternative to Entra ID or DefaultAzureCredential. Lesson 15, the browser-use lesson, has its own AZURE_OPENAI_CHAT_DEPLOYMENT_NAME, usually the same model.

One piece of cost control is built in. Lessons 16 and the model-routing setup accept AZURE_AI_SMALL_MODEL and AZURE_AI_LARGE_MODEL, defaulting to AZURE_AI_MODEL_DEPLOYMENT_NAME when unset, so you can point them at two deployed models to see cost-aware routing. A reader planning a budget should note that this requires two deployments rather than one, and that a non-deprecated model supporting the Responses API is a prerequisite, not a preference.

## Azure AI Search only switches on when two variables are both set

The retrieval lessons are written to degrade rather than fail, and the condition is specific. Azure AI Search is marked optional for lessons 05 and 16, which fall back to in-memory search when it is absent. The Lesson 16 notebook enables it only when both AZURE_SEARCH_SERVICE_ENDPOINT and AZURE_SEARCH_API_KEY are set, because it uses key-based authentication. One without the other leaves you on the in-memory path with no error to tell you why.

The template then adds a recommendation that contradicts its own default: for your own code, keyless auth via Entra ID or DefaultAzureCredential is advised over the key it requires here. So the lesson teaches a retrieval pattern through the less secure of two authentication routes, for a reason the file does not explain.

This is the pattern to watch across the course. Optional services are wired in with a fallback rather than an error, which is good for a notebook you want to run in five minutes and bad for a production lesson, because the difference between a working retrieval pipeline and a silently degraded one is two environment variables and nothing in the output. If you are copying these notebooks into anything real, replace the fallback with a hard failure before you trust the results.

## Fifty-plus translations are regenerated by a workflow, which is the whole bargain

The language table is marked as maintained by a GitHub Action and labelled automated and always up-to-date. The list runs from Arabic and Bengali through Chinese in four traditional variants, Croatian, Czech, Danish, Dutch, Estonian, Finnish, French, German, Greek, Hebrew, Hindi, Hungarian, Indonesian, Italian, Japanese, Kannada, Khmer, Korean, Lithuanian, Malay, Malayalam, Marathi, Nepali, Nigerian Pidgin, Norwegian, Persian, Polish, Portuguese for Brazil and Portugal, Punjabi, Romanian, Russian, Serbian in Cyrillic, Slovak, Slovenian, Spanish and Swahili, with more listed in a linked file.

That label is a promise with a specific failure mode. Regenerating translations from the English source keeps fifty languages current without fifty maintainers, and it means the English README is the only text a human actually edits. Anything a translator would have improved, a term of art that does not survive the round trip, an explanation that needed a human aside, gets overwritten on the next run. The repository is candid about the pipeline by pointing at the co-op-translator project's supported-languages file for anything not yet covered, which is where the real editorial judgement lives.

For a learner this cuts both ways. A translation is never going to be behind the English source, but it is also never going to be better than a machine rendering of it. If you are reading a translated lesson to learn a specific concept, check the English directory for the same lesson before concluding the concept is stated that way.

## The samples are Microsoft stack all the way down, with one escape hatch

Every code sample uses Microsoft Agent Framework with Microsoft Foundry Agent Service V2, and Microsoft Foundry is marked as requiring an Azure account. The course links the Agent Framework overview on Microsoft Learn and the Foundry Agent Service documentation, and the code samples live in a code_samples folder inside each lesson. The README asks you to fork the repository to create your own copy in order to run the code, which is the point at which you start needing a Foundry project and, behind it, a funded Azure resource.

The one concession to other providers is narrow and specific. Some code samples also support alternative OpenAI-compatible providers, MiniMax being the named example, which offers large-context models up to 204K tokens, with configuration details in the course setup lesson. Some samples, not all, and the configuration is opt-in rather than the default path.

That asymmetry is the honest shape of the course. The design-pattern material, the tool-use and RAG lessons, the planning, memory, context engineering, protocol and browser-use material are framework-agnostic enough to carry over. The notebooks that run are not. A reader who wants patterns will finish the course with a vocabulary and a set of transferable designs. A reader who wants a working agent on a different provider's stack will have to rewrite the samples rather than reconfigure them, and the 204K context figure is the only provider-specific number the repository offers.

## Conclusion

This course is a good fit for an engineer who already ships Python and wants the agent design vocabulary in one place: tool use, agentic RAG, planning, multi-agent patterns, metacognition, context engineering, memory, MCP and browser use, in that order and with working notebooks. It is a poor fit if you want provider-neutral examples, because the samples assume Azure OpenAI's Responses API and Microsoft Foundry Agent Service V2, and GitHub Models has been removed from them. Before starting, create the Foundry project, set AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME, and install the pinned requirements.txt as it stands rather than letting pip resolve agent-framework-core on its own, since 1.11.0 removed APIs the notebooks call.

## FAQ

### How can I learn AI agents?

This repository is an 18-lesson course, one numbered directory per lesson, running from 01-intro-to-ai-agents to 18-securing-ai-agents, and the README says each lesson covers its own topic so you can start wherever you like. If this is your first time building with generative AI models, it points to a separate 21-lesson Generative AI For Beginners course as preparation.

### How can I start using AI agents?

Lesson code samples are in a code_samples folder and use Microsoft Agent Framework with Microsoft Foundry Agent Service V2. Running them needs a Microsoft Foundry project, which the README marks as requiring an Azure account, and configuration is documented in the 00-course-setup lesson.

### What are AI agents for beginners?

That is this repository: 18 lessons under the MIT licence, each with a written lesson in the README, a short video and Python code samples. More than fifty language translations are regenerated by a GitHub Action, and questions are answered on the Microsoft Foundry Discord channel.

## Sources

- [Official documentation](https://aka.ms/ai-agents-beginners)
- [Official README](https://github.com/microsoft/ai-agents-for-beginners#readme)
- [Project repository](https://github.com/microsoft/ai-agents-for-beginners)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/microsoft-ai-agents-for-beginners