奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

微软 AI Agent 入门课环境配置：requirements.txt 与 .env 怎么填

2026-08-18

把 ai-agents-for-beginners 克隆下来，双击打开第一课的 notebook，运行第二格，然后卡住——这大概是这门课最常见的开局。卡点通常不在代码，而在三件事没对齐：装的包和 requirements.txt 里写的不是一套；.env 只填了一半；以及你想跑 .NET 那份样例，却按 Python 那份的说明配了环境变量。

这三件事仓库里都写清楚了，只是分散在 00-course-setup/README.md、根目录的 requirements.txt、.env.example、global.json 和各章 code_samples/ 里。下面把它们串成一条线。

前置条件：四样东西，缺一样后面全白搭

00-course-setup/README.md 的 Requirements 一节列的是这几项：

  • Python 3.12+。README 特意加了一句 NOTE：如果本机没有 3.12，先装，然后用 python3.12 来创建 venv，这样 requirements.txt 里的版本才会装对。
  • .NET 10+，只有跑 .NET 样例才需要。仓库根目录的 global.json 把 sdk.version 写成 10.0.100，rollForward 是 latestFeature，allowPrerelease 是 false——这是仓库当前文件里的取值，随版本可能变动。
  • Azure CLI，README 标注为 Required for authentication。
  • Azure 订阅 + 一个 Microsoft Foundry 项目，项目里要有已部署的模型。

依赖那边有个容易被跳过的细节。requirements.txt 里 Microsoft Agent Framework 这一段不是随手写的，注释里说明了：agent-framework-core 被钉在 1.10.0，是因为 1.11.0 引入了课程 notebook 用到的破坏性改动（注释点名了移除 ChatMessage 与 HostedWebSearchTool、改了 Message 构造函数、去掉了 Agent.run() 的 model= 参数）；而且注释还说明了为什么直接钉 agent-framework-core 而不是走 agent-framework 这个 meta-package——避免 [all] extras 拉进未钉版本的集成子包。以上都是仓库注释自述，版本号是仓库当前 requirements.txt 里的取值，随版本可能变动，动手前以仓库最新内容为准。

这里有一处值得你自己留意的口径差别：requirements.txt 明确绕开 meta-package，但很多课的 notebook 第一个代码格写的是 %pip install agent-framework azure-ai-projects azure-identity -q 这类装 meta-package的命令。两处白纸黑字摆在一起就是这样，仓库里没有找到解释二者关系的说明。如果你已经按根目录 requirements.txt 装过一遍，跑到 notebook 里那格之前，值得先想清楚要不要执行它。

另外，requirements.txt 并没有覆盖全部课程。以 15 课的 browser-use 为例，它的 notebook 里自带 %pip install browser_use langchain-openai playwright，这几个包在根目录 requirements.txt 里找不到。

步骤：每一步在改什么

第一步，虚拟环境。 README 给的是：

python -m venv venv

激活命令 README 分了两块写，# zsh/bash 那块是 source venv/bin/activate，Windows 那块被标为 # Command Prompt for Windows：

venv\Scripts\activate

注意这里标的是 Command Prompt。README 在别处（复制 .env、删 .git）都单独给了 PowerShell 版本，唯独激活这一步没有给 PowerShell 的写法——仓库里没有找到相关说明，你在 PowerShell 里遇到执行策略之类的问题，得自己按环境处置。

第二步，装依赖。

pip install -r requirements.txt

README 建议在上一步创建的虚拟环境里执行。

第三步，登录 Azure。 这一步改的是「凭据从哪来」。README 的 Step 3 写明：大部分 notebook 通过 Azure CLI 登录态认证，用的是 azure-identity 包里的 AzureCliCredential 或 DefaultAzureCredential，两者都会读你的 az login 会话，因此不需要 API key。

az login

远程环境或 Codespaces 里没有浏览器时，README 给的是：

az login --use-device-code

第四步，.env。 复制模板，两个平台各一条：

# zsh/bash
cp .env.example .env

# PowerShell
Copy-Item .env.example .env

README 说大多数课只需要填两个值：

AZURE_AI_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com/api/projects/<your-project-id>
AZURE_AI_MODEL_DEPLOYMENT_NAME=gpt-5-mini

其中模型名是仓库示例里的值，换成你自己的部署名。第一个值在 Foundry 门户项目的 Overview 页，第二个在 Models + Endpoints 里那个部署的名字——这是 README 里的表格给的位置。

环境变量：哪些是按课追加的

.env.example 比 README 正文列得全，按课分组是这样：

变量什么时候需要
AZURE_AI_PROJECT_ENDPOINT / AZURE_AI_MODEL_DEPLOYMENT_NAME大部分课必需
AZURE_AI_SMALL_MODEL / AZURE_AI_LARGE_MODEL16 课的模型路由，.env.example 注释写明不设则回落到 AZURE_AI_MODEL_DEPLOYMENT_NAME
AZURE_OPENAI_ENDPOINT / AZURE_OPENAI_DEPLOYMENT6、8 课直接调 Azure OpenAI 的 Responses API 时
AZURE_SEARCH_SERVICE_ENDPOINT / AZURE_SEARCH_API_KEY想把 5、16 课接到真实索引时
BING_CONNECTION_ID8 课的 Bing grounding workflow

AZURE_SEARCH_API_KEY 这一条有个坑，README 讲得很直白：16 课的 notebook 目前用的是基于 key 的认证，只有 endpoint 和 key 两个都设了才会从内存检索切到 Azure AI Search，否则一直走内存检索。README 同一段还写明：那节给出的 RBAC 步骤适用于 setup 指南里的样例和你自己的代码，并不会让 16 课的 notebook 变成无密钥认证。所以别以为按 RBAC 配完角色就够了。

另外 README 提到，6、8 课的样例以前用的是 GitHub Models，现在改成了 Azure OpenAI 的 Responses API，原因是仓库自述 GitHub Models 已 deprecated 且不支持 Responses API。你如果照着老教程配，会配到一条已经不用的路上。

还有两条「换 provider」的支线也是靠环境变量开关的。README 的 MiniMax 一节说明：因为 Microsoft Agent Framework 的 OpenAIChatClient 能对接任何 OpenAI 兼容端点，所以设了 MINIMAX_API_KEY 之后，用到 OpenAIChatClient 的样例会自动检测并使用这份配置；MINIMAX_BASE_URL 在 .env.example 里给了默认值，这是仓库当前文件里的取值，随版本可能变动。另一条是 Foundry Local，思路一样，靠的也是 OpenAIChatClient 对 OpenAI 兼容端点的通用性，只不过端点在本机。

以上命令与变量均为仓库文档中的原样写法，我们没有跑过，请以仓库最新内容与各命令的实际输出为准。

不想在本机折腾：容器那条路

README 单列了 GitHub Codespaces 的用法，说明是为了避免在本地下载体量较大的仓库；它给的做法是先建 Codespace，再在里面执行前面那几条 shallow / sparse clone 命令，只把需要的课程目录拉进工作区。README 也提醒了另一面：直接用 Codespaces 打开仓库（不额外克隆）会去构建 devcontainer 环境，可能准备出比你需要的更多东西。

这个 devcontainer 里有什么，.devcontainer/devcontainer.json 写得很清楚：基础镜像是 mcr.microsoft.com/devcontainers/python:3.12，features 里装了 azure-cli、Node 与 .NET，updateContentCommand 就是 python3 -m pip install -r requirements.txt。换句话说，前面手工那几步（Python 版本、Azure CLI、.NET SDK、依赖安装）在这条路上是预置好的，你仍然要自己做的只剩 az login 和填 .env。

本机跑的话，README 还有一节 Setup VSCode，只讲一件事：确认 VS Code 里选的是正确的 Python 版本。这条看着琐碎，但你要是建了 venv 却让 notebook 挂在系统解释器上，装好的包一个都用不上，报错信息还会指向别处。

notebook 与 .NET：两条路线的准备差异

这是最容易串的地方。README 写明：所有 Python notebook 的命名都是 *-python-agent-framework.ipynb，代码用 Microsoft Agent Framework 的 FoundryChatClient 连 Microsoft Foundry Agent Service V2（Responses API）。你在 01-intro-to-ai-agents/code_samples/01-python-agent-framework.ipynb 里能看到它读的是 AZURE_AI_PROJECT_ENDPOINT 与 AZURE_AI_MODEL_DEPLOYMENT_NAME，凭据用 AzureCliCredential()，工具函数用 @tool 装饰。

.NET 侧不是简单地「同一份代码换语言」，连运行形态都有两种：

一种是 .cs 文件。01-intro-to-ai-agents/code_samples/01-dotnet-agent-framework.cs 首行是 #!/usr/bin/dotnet run，紧跟着几行 #:package 指令声明依赖，跑法在配套的 01-dotnet-agent-framework.md 里写明是 dotnet run ./01-dotnet-agent-framework.cs，zsh/bash 下也可以先 chmod +x 再直接执行脚本。也就是说这条路线不需要你手动建工程、加包引用，依赖写在源文件头部。

另一种是 .NET notebook。05-agentic-rag/code_samples/05-dotnet-agent-framework.ipynb 的 kernelspec 是 .net-csharp，依赖声明改成了 #r "nuget: ..." 这种写法——和 .cs 那边的 #:package 不是一回事，别互相套用。想在 VS Code 里开这类 notebook，.devcontainer/devcontainer.json 里列的扩展是 ms-toolsai.jupyter、ms-python.python 和 ms-dotnettools.dotnet-interactive-vscode，最后一个就是给 .NET Interactive 内核用的。

更关键的一处：变量名不一样。01-dotnet-agent-framework.md 的 Required Environment Variables 一节给的是 AZURE_OPENAI_ENDPOINT 与 AZURE_OPENAI_DEPLOYMENT，凭据同样靠 az login 后的 AzureCliCredential。它把 zsh/bash 的 export 和 PowerShell 的 $env: 两种写法分开给了，Windows 这边是：

# PowerShell
$env:AZURE_OPENAI_ENDPOINT = "https://<your-resource>.openai.azure.com"
$env:AZURE_OPENAI_DEPLOYMENT = "gpt-5-mini"

所以「Python 那条配好了，.NET 那条就能跑」这个假设不成立，一个走 Foundry 项目端点，一个走 Azure OpenAI 端点。

边界：仓库自己标出来的不确定处

  • 05-dotnet-agent-framework.ipynb 里的部分 #r "nuget:" 引用带 preview / beta 版本后缀，属于预览版依赖，仓库没有对其稳定性作出承诺。
  • Foundry Local 那条本地路线，README 的 Note 写明它暴露的是 OpenAI 兼容的 Chat Completions 端点，适用于本地开发与离线场景；要完整的 Responses API 能力（包括有状态会话），README 让你用 Azure OpenAI 或 Foundry 项目。Windows 侧的安装命令 README 给的是 winget install Microsoft.FoundryLocal。
  • macOS 的 SSL 证书报错，README 的 Troubleshooting 给了三个选项，其中 connection_verify=False 那条被自己标了警告：它会跳过证书校验、降低安全性，只能在开发环境临时用，不要用在生产。
  • 大仓库下载的问题，README 推荐 shallow clone 或 sparse clone，git sparse-checkout set 只取你要的课程目录；它也提醒删 .git 是不可逆操作，Windows 侧给的是 Remove-Item -Recurse -Force .git。

怎么确认配对了

三个各管一段：

dotnet --list-sdks

az account show

前者验 .NET SDK，后者验登录态与订阅——都是 README 里给的验证命令。

Python notebook 这边，仓库另有一个脚本 scripts/validate-notebooks.ps1，它的注释块写明作用是发现课程 notebook、用 nbconvert 无头执行、输出 PASS/FAIL 矩阵并把结果写进 results.json。几个参数值得知道：-List 只列出会跑哪些而不执行，适合先确认范围；-Filter 接一个匹配仓库相对路径的通配符（注释里的例子是 '01-*'）；-IncludeDotnet 默认关闭，要跑 .NET notebook 得显式开，并且需要 .NET Interactive 内核。脚本注释也写明了它的前提：装好 requirements.txt 加 nbconvert 与 ipykernel、根目录有配好的 .env、并且已经 az login。

顺带一句：这个脚本是对着真实服务执行 notebook 的，注释里明确提到会重试限流类的瞬时错误。也就是说它会真的调用云端模型，不是离线语法检查——跑之前心里有数。

最后提醒一句，这门课持续更新，上面这些文件路径、变量名、依赖钉版和脚本参数都可能随版本变动，动手前先照着仓库当前的 00-course-setup/README.md 对一遍。

本文依据 github.com/microsoft/ai-agents-for-beginners 仓库于 2026-08-18 的公开内容整理， 事实来自仓库内的课程正文与代码示例。我们没有跑过文中涉及的代码， 因此不涉及运行结果、耗时与 Agent 实际表现的任何描述。 该课程持续更新，文中涉及的文件路径、依赖与接口写法随版本变动，请以仓库最新内容为准。 文中涉及的云端服务调用会产生费用并可能上传数据，请自行评估密钥与数据边界。

安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员