项目快照：microsoft/ai-agents-for-beginners，约 72,368 个 Star，23,966 个 Fork；最新推送时间 2026-07-29T19:47:29Z。本文基于仓库公开资料撰写。
项目地址：https://github.com/microsoft/ai-agents-for-beginners · https://aka.ms/ai-agents-beginners
项目速览（TL;DR）
ai-agents-for-beginners 是 Microsoft 发布的人工智能代理（AI Agents）入门课程仓库，仓库描述为“18 Lessons to Get Started Building AI Agents”。项目以课程资料、README、短视频入口和代码示例为主要组成，默认分支为 main，主要语言标注为 Jupyter Notebook，许可证为 MIT。
根据给定 GitHub 元信息，仓库拥有 72,368 个 Star 和 23,966 个 Fork。该数据未附带抓取时间，不能据此推导增长趋势、用户规模、课程完成率或代码质量指标；课程实际运行所需的云资源、模型部署和服务权限，应以仓库当前版本的课程设置说明为准。
- 项目类型：面向初学者的 AI Agent 课程仓库。
- 课程规模：README 和项目描述指向 18 个课程单元。
- 主要技术形态：Jupyter Notebook 与 Python 代码示例。
- 核心服务：Microsoft Foundry、Microsoft Agent Framework（MAF）和 Microsoft Foundry Agent Service V2。
- 默认分支：
main。 - 许可证：MIT License。
定位与目标用户
该仓库定位为“从基础开始构建 AI Agent”的学习型代码库，而不是已经封装好的生产代理平台。读者可以按课程单元学习，也可以根据已有知识直接进入特定主题；README 明确说明每个课程单元覆盖独立主题。
它面向希望理解代理基本组成、调用 Microsoft 服务并运行 Python 示例的学习者。若读者尚未接触生成式人工智能（Generative AI），README 建议先学习 Microsoft 的 Generative AI For Beginners 课程；这属于课程路径建议，不代表当前仓库包含该课程的全部内容。
- 希望从模型调用进一步学习工具、工作流、检索和多代理概念的开发者。
- 需要通过 Notebook 和代码示例理解 AI Agent 执行流程的工程师。
- 使用 Microsoft Foundry 或计划评估 Microsoft Agent Framework 的团队。
- 希望阅读多语言课程说明的学习者。
课程内容与学习路径
课程采用按单元拆分的组织方式，每个单元通常包含书面课程说明、短视频、Python 示例以及额外资源链接。由于给定资料没有提供 18 个单元的完整标题清单，本文不虚构逐课目录。
课程入口位于仓库根目录的 README.md，课程设置位于 00-course-setup/README.md，示例代码位于 code_samples 目录。资料还显示仓库包含 50 多种语言的翻译目录，因此完整克隆会增加下载内容。
- 先阅读课程设置，确定 Microsoft Foundry 项目、模型部署和相关连接配置。
- 选择一个课程单元，结合 README 与对应 Notebook 阅读。
- 运行该单元需要的代码示例，并记录模型、搜索或 Bing 连接等外部依赖。
- 根据示例涉及的组件，分别检查身份认证、数据访问和输出处理边界。
核心功能
仓库的核心价值在于把 AI Agent 的学习内容与可阅读的代码示例放在同一课程结构中。功能并非一个单独的命令行程序，而是由课程说明、Notebook、服务配置和外部平台共同构成的学习闭环。
Agent 基础概念与代码示例
课程通过 Python 示例展示如何使用 Microsoft Agent Framework 与 Microsoft Foundry 构建代理。输入通常来自课程示例中的用户任务或模型请求，输出则由代理流程返回；具体函数签名、消息类型和调用方式没有在给定 README 片段中完整列出，因此不能在本文中伪造统一 API。
触发条件取决于所学习的课程单元。代码运行至少涉及模型部署和 Microsoft Foundry 项目端点；如果某个单元还使用 Azure AI Search 或 Bing grounding workflow，则必须额外配置相应服务。
Microsoft Foundry Agent Service V2
README 将 Microsoft Foundry Agent Service V2 列为课程使用的服务之一。它承担代理服务侧的运行能力，但仓库资料没有给出服务端部署拓扑、区域要求、配额、并发上限或 SLA，因此这些内容不能从课程仓库推断。
课程示例使用 Microsoft Foundry 项目端点和模型部署名称作为配置入口。输入输出格式、会话保存方式以及服务端日志保留策略，应以对应课程代码和 Microsoft Foundry 官方文档为准。
Agentic RAG
README 明确指出，第 05 课的 Agentic RAG 需要 Azure AI Search。该能力的基本依赖关系是：课程代码发起代理任务，代理流程访问搜索服务，再将检索结果用于后续模型处理；具体检索字段、索引结构和返回数据格式，给定资料没有提供。
因此，配置 Azure AI Search 端点和密钥只能说明运行前置条件，不能保证任意搜索服务已经具备课程示例所需的索引。测试时应使用已授权、可删除或已脱敏的数据集，避免把个人信息或未经授权的业务数据送入模型。
Bing grounding workflow
README 将 Bing connection 标记为第 08 课的必需配置，并将该课程描述为 Bing grounding workflow。触发该工作流需要配置 BING_CONNECTION_ID，但资料没有给出连接创建命令、请求参数或结果 schema。
该能力涉及外部检索和模型生成的组合，运行结果可能依赖外部内容变化。课程仓库没有提供搜索结果准确率、内容时效性或引用完整性的保证，实际应用应自行设计来源展示和人工复核机制。
浏览器使用与成本感知路由
环境变量示例显示，第 15 课使用名为 browser-use 的场景，并配置 AZURE_OPENAI_CHAT_DEPLOYMENT_NAME；第 16 课支持小模型与大模型之间的路由，使用 AZURE_AI_SMALL_MODEL 和 AZURE_AI_LARGE_MODEL。资料没有提供浏览器操作的目标站点、自动化动作清单或路由算法实现。
第 16 课的配置说明明确指出：未设置小模型或大模型变量时，默认使用 AZURE_AI_MODEL_DEPLOYMENT_NAME。这说明示例用于演示模型层级路由的配置方式，但不能据此宣称固定的成本下降比例或性能提升。
系统架构与关键模块
从仓库资料看，系统由课程层、示例代码层、模型与代理服务层、可选外部连接层组成。它不是单体应用，运行一个课程单元时，实际依赖范围由该单元使用的组件决定。
| 层次 | 资料中的模块 | 输入 | 输出或职责 | 运行依赖 |
|---|---|---|---|---|
| 课程层 | README.md、各课 README、短视频入口 |
主题说明与学习任务 | 解释概念、提供资源链接 | 仓库文件 |
| 示例层 | code_samples、Jupyter Notebook |
课程示例输入 | 演示代理代码及调用过程 | Python、课程依赖 |
| 代理框架层 | Microsoft Agent Framework（MAF） | 代理任务与模型请求 | 提供代理编排能力 | 框架及认证配置 |
| 服务层 | Microsoft Foundry Agent Service V2 | 项目端点、模型部署 | 提供代理服务运行入口 | Microsoft Foundry Azure 账户 |
| 外部连接层 | Azure AI Search、Bing connection | 搜索请求或 grounding 请求 | 返回检索或外部信息 | 对应服务和授权 |
上述架构是根据 README 和 .env.example 对依赖关系进行的结构化整理，不等同于仓库声明的正式架构图。仓库资料没有给出模块间的网络端口、部署清单、容器拓扑或请求时序图。
依赖与运行环境
课程代码以 Python 和 Jupyter Notebook 为主要表现形式，但给定资料没有提供 Python 版本、Jupyter 版本、操作系统支持矩阵或完整依赖锁定文件。运行环境因此不能按本文自行设定版本，建议以当前仓库的课程设置和各课目录为准。
Microsoft Foundry 是大多数课程的必需项目，README 同时明确标注需要 Azure 账户。直接调用模型的课程使用 Azure OpenAI Responses API；资料特别说明 GitHub Models 已弃用，并计划于 2026 年 7 月退出，同时不支持 Responses API。
- 仓库获取：Git，仓库地址为
https://github.com/microsoft/ai-agents-for-beginners.git。 - 代码形态：Jupyter Notebook 与 Python 示例。
- 模型服务：Microsoft Foundry 和 Azure OpenAI Responses API。
- 认证方式：
.env.example说明可使用 Entra ID / AzureCliCredential，也可选择 Azure OpenAI API key。 - 可选模型提供商：MiniMax，使用 OpenAI 兼容接口。
资料没有提供安装包列表、依赖版本和通用启动脚本。不要根据仓库语言标注自行推断可以使用某个固定的 pip install 命令；应先阅读目标课程的设置文件。
快速开始
快速开始可以可靠地完成仓库获取、可选的翻译裁剪和文件验证；课程代码的实际执行还需要 Azure 资源、模型部署以及按课程配置的凭据。下面的命令均来自 README 中给出的 Git 操作或基于仓库资料中明确存在的目录进行本地检查，不会访问未授权的远程目标。
安装：获取仓库
git clone https://github.com/microsoft/ai-agents-for-beginners.git
cd ai-agents-for-beginners这里的“安装”指获取课程源代码与 Notebook，并不代表已经安装 Python 依赖或完成云服务配置。官方仓库未提供统一的依赖安装命令，建议进入 00-course-setup/README.md 查阅当前版本要求。
运行：使用不含翻译的大体积裁剪方式准备课程
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'以上命令是 README 提供的 macOS、Linux 和 Bash 方案，目的在于排除 translations 与 translated_images。Windows CMD 方案应使用 README 中的双引号写法；两种方式都不会替代课程运行所需的模型和服务配置。
验证：检查课程入口与示例目录
test -f README.md && echo "README.md: OK"
test -f 00-course-setup/README.md && echo "course setup: OK"
test -d code_samples && echo "code_samples: OK"验证命令只检查资料中明确提到的文件和目录是否存在，不会发起模型请求。若检查失败，先确认当前目录是仓库根目录，并检查稀疏检出规则；若课程目录在最新版本中发生变化，应以最新 README 为准。
最小可运行边界
给定资料没有提供一个完整、可独立复制的 Python 程序，也没有给出 Notebook 的启动命令、依赖安装命令或通用入口函数。因此，本文不虚构一个声称能够调用代理服务的 Python 示例；要形成真正的模型调用闭环，必须以目标课程中的实际 Notebook 和课程设置为准。
在不填入真实凭据的情况下，可以先完成本地仓库闭环：克隆仓库、准备课程目录、验证入口文件。模型运行闭环需要授权的 Azure 资源和部署名称，禁止把下方占位符直接当作有效密钥使用。
配置说明
.env.example 是资料中最明确的配置来源，包含 Microsoft Foundry、Azure OpenAI、Azure AI Search、Bing 和 MiniMax 的变量示例。字段是否被某一课程使用，取决于课程单元；并非所有变量都需要在每次运行时同时填写。
| 字段名 | 类型 | 默认值 | 作用 |
|---|---|---|---|
AZURE_AI_PROJECT_ENDPOINT |
字符串 | "https://..." |
Microsoft Foundry 项目端点；大多数课程需要。 |
AZURE_AI_MODEL_DEPLOYMENT_NAME |
字符串 | "gpt-5-mini" |
Foundry 项目中的模型部署名；示例要求使用支持 Responses API 且未弃用的模型。 |
AZURE_AI_SMALL_MODEL |
字符串 | "gpt-5-nano" |
第 16 课模型路由中的小模型部署名。 |
AZURE_AI_LARGE_MODEL |
字符串 | "gpt-5-mini" |
第 16 课模型路由中的大模型部署名。 |
AZURE_OPENAI_ENDPOINT |
字符串 | "https://<your-resource>.openai.azure.com" |
Azure OpenAI Responses API 端点。 |
AZURE_OPENAI_DEPLOYMENT |
字符串 | "gpt-5-mini" |
直接调用模型时使用的 Azure OpenAI 部署名。 |
AZURE_OPENAI_API_KEY |
字符串 | "..." |
可选的 Azure OpenAI API key；也可使用 Entra ID / AzureCliCredential。 |
AZURE_OPENAI_CHAT_DEPLOYMENT_NAME |
字符串 | "gpt-5-mini" |
第 15 课 browser-use 场景使用的聊天部署名。 |
AZURE_SEARCH_SERVICE_ENDPOINT |
字符串 | "https://..." |
第 05 课 Agentic RAG 使用的 Azure AI Search 服务端点。 |
AZURE_SEARCH_API_KEY |
字符串 | "..." |
第 05 课 Azure AI Search 的 API key。 |
BING_CONNECTION_ID |
字符串 | "..." |
第 08 课 Bing grounding workflow 的连接标识。 |
MINIMAX_API_KEY |
字符串 | "..." |
MiniMax OpenAI 兼容服务的 API key。 |
MINIMAX_BASE_URL |
字符串 | "https://api.minimax.io/v1" |
MiniMax 的 OpenAI 兼容接口基础地址。 |
MINIMAX_MODEL_ID |
字符串 | "MiniMax-M3" |
MiniMax 模型标识。 |
上表中的字段名和示例默认值均来自给定的 .env.example。模型部署名只是配置样例，不表示读者的 Foundry 项目已经部署相同模型；应替换为当前项目中实际存在且符合课程要求的部署。
配置文件示例
AZURE_AI_PROJECT_ENDPOINT="https://..."
AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5-mini"
AZURE_OPENAI_ENDPOINT="https://<your-resource>.openai.azure.com"
AZURE_OPENAI_DEPLOYMENT="gpt-5-mini"
AZURE_OPENAI_API_KEY="<你的-Azure-OpenAI-API-KEY>"该片段仅用于说明变量形态，不能作为真实凭据。API key、项目端点和搜索密钥不应提交到公开仓库、Notebook 输出或日志；资料没有说明仓库是否自动加载环境文件，也没有给出密钥轮换、密钥托管或权限最小化的具体实现。
进阶用法
进阶使用的重点是按课程单元拆解依赖，而不是一次性配置所有服务。对于只学习基础代理的单元，可以先准备 Foundry 项目和模型部署；进入 Agentic RAG、Bing grounding 或 browser-use 相关课程时，再补充对应配置。
- 稀疏检出：仓库包含 50 多种翻译，磁盘或网络受限时可按 README 排除翻译目录。
- 多语言学习：README 提供简体中文、繁体中文以及其他语言的翻译入口，翻译由 GitHub Action 支持并保持更新。
- 模型路由：第 16 课可配置小模型和大模型部署，未设置时回退到
AZURE_AI_MODEL_DEPLOYMENT_NAME。 - 替代提供商：部分示例支持 MiniMax 等 OpenAI 兼容提供商，具体配置以课程设置说明为准。
- 课程分叉：可以 Fork 仓库，在自己的副本中运行和修改代码；Fork 本身不代表获得 Azure 资源或第三方服务授权。
在场景 A 中，如果目标是理解 Microsoft Agent Framework 与 Microsoft Foundry 的组合，应优先按照课程默认技术栈操作；在场景 B 中，如果已有 OpenAI 兼容服务，且目标课程明确支持替代提供商，可以依据课程设置评估 MiniMax。资料没有提供不同提供商之间的准确率、延迟、价格或功能对比，因此不应作出量化结论。
可观测性与运维
给定资料主要描述课程和配置，没有提供统一的日志格式、指标名称、链路追踪方案、告警规则或生产部署文档。仓库 README 中的 GitHub issues、Pull Requests 和 Discord 入口适合反馈课程代码问题，但不能当作运行时监控系统或服务级支持承诺。
运行课程示例时，建议至少记录课程编号、使用的模型部署名、外部连接类型、输入是否经过脱敏以及错误发生阶段。以下属于根据本文作者的经验判断，不是仓库明确承诺的功能：如果把示例扩展到业务环境，应将模型调用、工具调用和检索结果分别记录，避免只保留最终文本而无法定位错误来源。
- 区分身份认证失败、模型部署不存在、外部搜索连接失败和代码异常。
- 不要在日志中输出
AZURE_OPENAI_API_KEY、AZURE_SEARCH_API_KEY或其他凭据。 - 对模型输出和外部检索结果保留可追溯的课程或请求上下文。
- 在修改模型部署后重新验证课程示例，不把部署名称当作模型能力的充分证明。
仓库未提供并发控制、重试策略、超时配置、成本预算、数据保留和灾备方案。部署到生产前，这些部分需要由使用团队自行设计并通过所使用的 Microsoft 服务文档核验。
安全与合规边界
该项目包含模型调用、检索、Bing grounding 和 browser-use 等能力，使用时必须限制在已授权的 Azure、搜索连接和测试数据范围内。课程资料没有提供绕过访问控制、规避检测或攻击第三方系统的内容，本文也不提供面向未授权目标的操作方法。
凭据与数据
- API key、项目端点和连接标识应通过受控配置注入，不应写入公开提交。
- Azure AI Search 的索引内容应具备合法的数据来源和访问权限。
- 发送给模型的输入应先评估是否包含个人信息、商业秘密或受合同约束的数据。
- browser-use 相关示例只能用于获得授权的浏览器环境和测试站点。
外部内容与模型输出
Bing grounding 或搜索增强会引入外部内容，外部内容不等于已验证事实。对于医疗、金融、法律、身份认证或其他高影响决策，不能仅凭课程示例的模型输出直接执行决策。
仓库没有声明特定行业合规认证、隐私承诺、数据驻留范围、SLA 或安全审计结果。相关要求应由部署组织结合 Azure 服务条款、内部制度和适用法律单独核验。
许可证与商用条款
仓库包含 MIT License，版权归 Microsoft Corporation 所有。MIT License 授予获得软件及相关文档的人员使用、复制、修改、合并、发布、分发、再许可和销售副本的许可，但分发时必须保留版权声明和许可声明。
因此，从许可证文本看，代码和文档在满足 MIT 条款的前提下可以用于商业场景；但该结论仅针对仓库许可证，不自动覆盖 Azure、Microsoft Foundry、Azure OpenAI、Bing、MiniMax、模型权利、数据来源或第三方服务的独立条款。
- 再分发软件或实质性部分时，应保留 MIT License 要求的版权与许可文本。
- MIT License 按“现状”提供，不提供适销性、特定用途适用性和不侵权保证。
- 仓库许可证不能替代云服务账号、模型部署和外部数据的授权。
- 具体分发方式和组合产品中的责任边界，以仓库 LICENSE 及相关服务条款为准。
局限性与已知限制
该项目是入门课程，不是面向所有生产场景的完整工程模板。给定资料没有提供性能基准、并发规模、错误率、成本数据、版本兼容矩阵或服务等级承诺，因此这些指标均应视为未提供。
- 没有完整列出 18 个课程单元的标题和每课依赖。
- 没有在给定资料中提供 Python、Jupyter 或框架的版本号。
- 没有提供通用的依赖安装命令、Docker 镜像或容器编排文件。
- 部分课程依赖 Microsoft Foundry、Azure AI Search 或 Bing connection，脱离相应服务不能完整运行。
- 课程示例不能自动推导生产级认证、审计、监控、限流和数据治理方案。
- GitHub Models 已在 README 配置说明中标记为弃用，并注明不支持 Responses API。
官方仓库未提供上述缺失信息，建议以最新 README、目标课程的设置说明和对应服务官方文档为准。仓库处于持续更新状态时，环境变量、模型名称和课程代码也可能随服务生命周期变化。
适合谁
判断是否采用该课程，关键在于已有技术栈、云资源条件和学习目标是否与仓库边界一致。以下信号越多符合，越适合从该仓库开始。
- 团队或个人已经拥有 Azure 账户，并能创建或使用 Microsoft Foundry 项目。
- 学习目标是理解 AI Agent 的组成和工作流，而不是直接采购一个带 SLA 的成品系统。
- 能够阅读 Python、Jupyter Notebook 和环境变量配置。
- 希望学习 Microsoft Agent Framework、Microsoft Foundry Agent Service V2 或 Azure AI Search 的组合用法。
- 可以在授权的测试数据和测试站点中验证搜索增强、浏览器使用等示例。
不适合谁
如果项目要求在无云资源、强版本锁定或高合规约束下立即上线，该仓库不能单独满足这些条件。以下任一信号成立时，应先补充工程化评估或选择与约束更匹配的方案。
- 团队无法使用 Azure 账户，且目标课程依赖 Microsoft Foundry 或 Azure AI Search。
- 需要明确的 Python、依赖、并发、延迟、成本或 SLA 指标，而仓库资料未提供这些承诺。
- 需要完全离线运行，但目标课程依赖云端模型、搜索服务或 Bing connection。
- 要直接处理未脱敏的个人信息、金融数据、医疗数据或其他受严格监管的数据。
- 需要一个已经完成认证、审计、限流、监控和灾备的生产级代理平台，而不是课程示例。
常见问题与排查（FAQ / Troubleshooting）
排查应先区分仓库获取问题、配置问题、身份认证问题和外部服务问题。不要把所有失败都归因于模型或 Notebook 本身。
为什么克隆后目录很大
README 说明仓库包含 50 多种语言翻译，会显著增加下载大小。需要减少下载内容时，可使用 README 提供的 sparse checkout 命令排除 translations 和 translated_images。
为什么模型调用失败
先检查 AZURE_AI_PROJECT_ENDPOINT、AZURE_AI_MODEL_DEPLOYMENT_NAME、AZURE_OPENAI_ENDPOINT 和对应部署名称是否与实际资源一致。若使用 API key，确认变量没有直接保留示例占位符；若使用 Entra ID / AzureCliCredential，则需按当前课程和 Azure 文档完成身份配置。
第 05 课为什么需要额外配置
根据 .env.example，Agentic RAG 需要 AZURE_SEARCH_SERVICE_ENDPOINT 和 AZURE_SEARCH_API_KEY。即使变量已填写，也需要确认搜索服务中存在课程代码要求的可查询数据结构；给定资料没有提供该结构的定义。
第 08 课为什么无法执行 grounding workflow
该课程需要 BING_CONNECTION_ID。仓库资料没有提供连接创建步骤和权限范围，排查时应确认连接标识属于当前授权的 Microsoft Foundry 环境，并以相关官方文档核验服务状态。
能否直接使用 GitHub Models
根据 .env.example 的说明，GitHub Models 已弃用，计划于 2026 年 7 月退出，并且不支持 Responses API。课程配置示例改为 Azure OpenAI Responses API，因此不应把 GitHub Models 作为当前课程的默认运行依赖。
没有版本号怎么办
给定资料没有提供 Python、Jupyter、Microsoft Agent Framework 或其他依赖的版本号。官方仓库未提供该信息，建议以当前分支的 00-course-setup/README.md、各课程文件和最新 README 为准，避免自行固定未经仓库声明的版本。
社区协作与问题反馈
仓库 README 提供 GitHub Issues、Pull Requests 和 Microsoft Foundry Discord 入口。代码错误、拼写错误和课程建议可以通过 Issue 或 Pull Request 反馈；使用云服务时遇到的账号、配额和权限问题，还需要结合对应服务的支持渠道处理。
- 提交问题时说明课程编号、复现步骤、脱敏后的错误信息和使用的配置类别。
- 不要在 Issue、Pull Request 或 Discord 中粘贴 API key、完整端点密钥或业务数据。
- 如果问题只在某个模型部署出现，应同时记录部署名称，但不要公开敏感资源标识。
- 提交修改前确认翻译目录、Notebook 输出和课程代码之间没有不一致。
事实范围与核验说明
本文事实主要来自项目 README、LICENSE、.env.example 以及用户提供的 GitHub 元信息。Star、Fork、语言和默认分支属于给定元信息，不代表永久不变的仓库状态。
凡是资料没有明确说明的版本、端口、依赖、性能、并发、SLA、接口签名和部署细节，本文均未补写。涉及学习路径、生产化日志设计和数据治理的建议，已明确标注为根据本文作者的经验判断，不能视为项目官方承诺。
项目地址与资源
下列链接均来自项目资料或 README 中列出的官方入口，使用前应以对应站点当前内容和服务条款为准。
- ai-agents-for-beginners GitHub 仓库
- AI Agents for Beginners 官网与文档入口
- Generative AI For Beginners 课程
- Microsoft Foundry 课程资源
- Microsoft Agent Framework 课程资源
- Microsoft Foundry Agent Service V2 课程资源
- Microsoft Foundry Discord 社区
- GitHub Issues 问题反馈
- GitHub Pull Requests 协作入口
- MiniMax 官方平台
- Azure co-op-translator 支持语言说明
