The Problem

Building AI agents requires navigating a fragmented ecosystem: multiple frameworks (Semantic Kernel, AutoGen, Agent Framework), agentic design patterns, tool use, RAG, multi-agent coordination, and production concerns like memory, security, and observability. Each topic has scattered tutorials with inconsistent quality and no coherent learning path.

What This Does

This is a fork of Microsoft's ai-agents-for-beginners course — 18 self-contained lessons covering the full agent development lifecycle. Each lesson is a folder with a README, a Jupyter notebook (Python), and a C# code sample. The course spans 01-intro-to-ai-agents through 15-browser-use, plus 18-securing-ai-agents.

The repo is a portfolio, not a single codebase. The substantial projects are 11-agentic-protocols (MCP client/server implementation), 08-multi-agent (agent orchestration patterns), 18-securing-ai-agents (receipt signing), and 05-agentic-rag (retrieval-augmented generation). The translations/ directory contains 50+ language versions of every lesson, generated automatically.

How It Is Wired

Each lesson is self-contained. The most substantial code lives in 11-agentic-protocols/code_samples/mcp-agents/ — a working MCP server (server/server.py) with an event store (server/event_store.py), and a resumable client (client/resumable_client.py). The client's run_long_running_task function loads resumption tokens, executes work, and clears tokens on completion — clear_resumption_tokens is called from 2 places, making it the most-connected function.

The server's event_store.py owns all database effects: store_event, replay_events_after, get_event_count, clear_events. The client's resumable_client.py owns file I/O via load_resumption_tokens and save_resumption_tokens.

18-securing-ai-agents/code_samples/sample_receipts/generate_fixtures.py performs cryptographic operations — sign_receipt calls b64url_nopad, and receipt_hash uses hashlib.sha256. The traced path from main reaches crypto in two hops.

The .agents/skills/jupyter-notebook/scripts/new_notebook.py is a utility script with a main function that reaches 14 functions and handles file operations.

How To Use It

Clone with sparse checkout to avoid the 9,000+ translation files:

git clone --filter=blob:none --sparse https://github.com/moses-y/ai-agents-for-beginners.git
cd ai-agents-for-beginners
git sparse-checkout set 01-intro-to-ai-agents 02-explore-agentic-frameworks 11-agentic-protocols

Each lesson's notebook runs in Jupyter. The MCP sample requires pip install -r requirements.txt (only exists in 18-securing-ai-agents/code_samples/). The .devcontainer/Dockerfile provides a containerized environment. No lockfile exists, so builds are not reproducible.

Real-World Use

The MCP sample demonstrates resumable long-running tasks — useful for production agents that must survive crashes. The event_store.py pattern (event sourcing for agent state) applies directly to building audit trails for agent actions. The receipt signing in 18-securing-ai-agents shows how to add cryptographic verification to agent outputs.

Code Health & Issues

Static analysis found 9 issues across 4 kinds:

  • High — Duplicated code blocks: 87 repeated 6-line blocks across 12 C# files in 01-intro-to-ai-agents through 04-tool-use. Extract shared helpers.
  • Medium — Broad exception handling in event_store.py, client.py, and resumable_client.py. Bare except swallows errors.
  • High — Deep nesting in MCP client/server files: max indentation depth 12 in client.py. Flatten with early returns.
  • Medium — High branching density: 19 branch points over 66 lines in 02-dotnet-agent-framework.cs.

Additional SDLC findings:

  • High — GitHub Actions pinned to mutable tags (pozil/auto-assign-issue@v2) in .github/workflows/. Pin to commit SHAs.
  • Medium — No Dependabot/Renovate configured despite 2 manifests.
  • Medium — Container base image mcr.microsoft.com/devcontainers/python:3.12 unpinned by digest.
  • Medium — No dependency vulnerability scan in CI.
  • Low — No timeout-minutes on workflow jobs.

The Bottom Line

A solid, well-structured course for learning agent development, with working MCP and security examples that go beyond toy demos. The translation bloat and lack of lockfiles hurt reproducibility, but for learning purposes the trade-off is acceptable. Best for engineers who want a guided path through agent frameworks and protocols, not for production code.