notebook 依赖装不上或版本打架：微软 AI Agent 入门课的三处依赖源

2026-08-18

按 00-course-setup/README.md 建好 venv、装完 requirements.txt，打开某一课的 notebook，第一格 %pip install 跑得好好的，第二格 import 就崩了——这是这门课最容易撞上的一类问题，而且它跟 Azure 配置没关系。原因在于 ai-agents-for-beginners 的依赖不止一处，至少有三处会往同一个环境里写东西，它们的版本约束方向还不完全一致。

下面按”这三处分别是什么、怎么判定是它、仓库给了什么处置、怎么验证、什么情况说明不是它”的顺序过一遍。仓库持续更新，文中的文件路径与包名以仓库最新内容为准。

一、三处依赖分别在哪

第一处，仓库根的 requirements.txt。 这是 00-course-setup/README.md 与 AGENTS.md 都让你先跑的那一份：

pip install -r requirements.txt

第二处，每课 notebook 的第一格。 几乎每个 NN-python-agent-framework.ipynb 开头都有一行自己的安装命令，而且不少带 -U。例如 04-tool-use/code_samples/04-python-agent-framework.ipynb 的第一个代码格是：

%pip install agent-framework azure-ai-projects azure-identity python-dotenv -U -q

08-multi-agent/code_samples/workflows-agent-framework/python/ 下那四个 workflow notebook 值得单独看一眼，它们和上面这条路子并不一样：01、02、03 三个的第一格里，pip install agent-framework -U 是被注释掉的，上面还留了一句 Already covered by repo-level requirements.txt; left for reference；而 04.python-agent-framework-workflow-aifoundry-condition.ipynb 的第一格是活的，装的还是另一个包：

! pip install agent-framework-azure-ai -U

agent-framework-azure-ai 不在根 requirements.txt 里。CHANGELOG.md 对这一处写了理由：这个 notebook 有意保留 AzureAIAgentClient，因为它要用 Microsoft Foundry Agent Service 的 hosted tools（Bing grounding、code interpreter）——这是仓库文档自述，不是我们的推测。

第三处，单课自带的额外依赖。 这一处最容易漏：

13-agent-memory/13-agent-memory-cognee.ipynb 第一格装的是 "cognee[redis]==0.4.0"，这是个精确钉死的版本；
15-browser-use/README.md 的 Setup 一节要你装 browser_use playwright python-dotenv，还要额外跑 playwright install chromium，这一步装的是浏览器本体，不是 Python 包；
14-microsoft-agent-framework/README.md 讲把 LangGraph agent 托管到 Foundry 时，要装 "langchain-azure-ai[hosting]>=1.2.4"；
18-securing-ai-agents/code_samples/ 下有一份自己的 requirements.txt，里面是 pynacl、jcs、ipykernel，用的是 >= 而不是根目录那种钉法。

这三处写进的是同一个 venv。冲突就是从这儿来的。

二、版本约束到底钉了什么

根 requirements.txt 里那段注释写得很直白，它自己解释了为什么不装 meta 包：

# Pinned to the 1.10.x line: 1.11.0 introduced breaking API changes used by the
# course notebooks (removed ChatMessage and HostedWebSearchTool, changed the
# Message constructor, and dropped the model= argument on Agent.run()).
#
# NOTE: agent-framework-core is pinned directly (not via the agent-framework meta-package)
# to avoid the [all] extras pulling in unpinned integration sub-packages whose newer
# pre-releases require agent-framework-core>=1.11.0 and cause a pip conflict.
agent-framework-core==1.10.0
agent-framework-foundry~=1.10.0
agent-framework-openai~=1.10.0

把它和第二处放在一起看，关系就很清楚了：根文件刻意绕开 agent-framework 这个 meta 包、只钉 agent-framework-core，而各课 notebook 第一格装的恰恰就是 agent-framework，还带 -U。两处方向相反，这是我们从两个文件里读出来的事实，至于你的环境最终会解析成什么，取决于当时的包索引，我们没有跑过。

注释里点名的四个破坏点也不是空的。08-multi-agent/code_samples/workflows-agent-framework/python/04.python-agent-framework-workflow-aifoundry-condition.ipynb 里就有 from agent_framework import HostedWebSearchTool，14-microsoft-agent-framework/code-samples/hotel_booking_workflow_sample.py 里用到了 ChatMessage。也就是说，这几个符号一旦在你装到的版本里不存在，报错会落在具体的这几课上，而不是全课程一起挂。

另外记一笔：CHANGELOG.md 里那条依赖变更写的是把 agent-framework、agent-framework-foundry、agent-framework-openai 钉到 ~=1.10.0，与 requirements.txt 实际写的 agent-framework-core==1.10.0 并不是同一句话。以文件为准。同样地，AGENTS.md 末尾的 Dependencies 清单里仍列着 azure-ai-inference，而 CHANGELOG.md 有一条明确写着已把 azure-ai-inference 移除（它此前只被迁走的 GitHub Models 示例用到），当前 requirements.txt 里确实没有这一项。看这类清单时留个心。

三、怎么确认是依赖问题

AGENTS.md 的 Testing Instructions 给了三个动作，都能直接用：

python --version  # Should be 3.12+
pip list | grep -E "(agent-framework|azure-ai|azure-identity)"

jupyter nbconvert --to script <lesson-folder>/code_samples/<notebook>.ipynb --stdout | python

第二条把 notebook 转成脚本再执行，AGENTS.md 给它加的注释就是 tests imports——依赖装错时，报错会落在 import 这一层，而不是等到业务逻辑那一段才暴露。

Windows 侧有两点要注意。第一，上面那条 pip list | grep 是 bash 写法，PowerShell 里没有 grep，要么在 Git Bash / WSL 里跑，要么直接看 pip list 的完整输出自己找那几行。第二，00-course-setup/README.md 给出的 venv 激活命令，Windows 那一段标的是 Command Prompt 的写法：

venv\Scripts\activate

同一节还专门提醒：如果你机器上没有 Python 3.12，装好之后要用 python3.12 去建 venv，否则从 requirements.txt 装出来的版本不对。同一个文件里还有一个 Setup VSCode 小节，只说了一句”确认你在 VSCode 里用的是对的 Python 版本”——配合第二处的 %pip install，你选的哪个解释器，包就落到哪个环境里（这一条是 Jupyter 的通用行为，不是该课程的说明）。

更省事的判定动作是仓库自带的批量校验脚本 scripts/validate-notebooks.ps1，它用 nbconvert 逐个跑 Python notebook 并打一张 PASS/FAIL 表：

# Just list what would run (no execution)
pwsh scripts/validate-notebooks.ps1 -List

# A single lesson, with a longer per-cell timeout
pwsh scripts/validate-notebooks.ps1 -Filter '08-*' -Timeout 600

# Explicit interpreter (if `python` is not on PATH, e.g. Windows Store alias)
pwsh scripts/validate-notebooks.ps1 -Python "C:/path/to/python.exe"

最后那条注释是仓库自己写给 Windows 用户的：python 不在 PATH 上时（技能文档举的例子就是被 Windows Store 的别名占掉），要用 -Python 显式指定解释器，别指望自动探测。脚本的文档里还写明，它把 ImportError、TypeError 这类确定性代码错误归为不重试，只对 429、Azure CLI 取 token 抖动、超时这类做重试——这条分类规则可以直接借来自查：一个错压根没被重试，说明它落在确定性那一类，往依赖与写法方向查；被重试了，说明脚本把它认成了 429、取 token 抖动或超时，那是配额与网络侧的事，跟你装了哪个版本没关系。

以上命令与参数均取自仓库文档，组合方式为按其参数语义拼出的示例，未经实测，以仓库最新内容与 --help 的实际输出为准。

四、仓库给出的处置

AGENTS.md 的 Common Gotchas 一节里，Package conflicts 那条给了三句话：用干净的虚拟环境；从 requirements.txt 装而不是逐个包装；有些 notebook 需要它自己 markdown cell 里提到的额外包。配合前面三处依赖来源，落到操作上就是：

先按 00-course-setup/README.md 用 Python 3.12 建 venv、装根 requirements.txt，把这份”被仓库自己校验过的集合”作为基线；
再跑某一课时，清楚第一格的 %pip install ... -U 会往这个基线上追加或升级什么；
对 Lesson 13（cognee 精确钉版）、Lesson 15（browser_use + Playwright 浏览器）、Lesson 17（Foundry Local 运行时）这类自带重依赖的课，考虑给它们单独开环境——这是通用做法，不是仓库的官方指引，仓库只说了”用 fresh 虚拟环境”。

CHANGELOG.md 里还留了一句可以直接抄的自查提示：这门课的 agent 创建调用是 client.as_agent(...)，如果你钉了别的版本，要确认方法还在不在（as_agent 与 create_agent 的差别）。遇到 AttributeError 落在这一层，方向就是版本，不是代码写错。

五、处置完怎么验证

按由轻到重三步：

pip list 里确认 agent-framework-core / agent-framework-foundry / agent-framework-openai 三项都在，且和根 requirements.txt 的写法对得上；
对出问题的那一课跑 jupyter nbconvert --to script ... --stdout | python，import 过了就说明依赖这一关过了；
跑 pwsh scripts/validate-notebooks.ps1，它会把执行副本、每个 notebook 的日志和 results.json 写到 $env:TEMP\aiab-nbval，FAIL 的行会带上第一条 *Error / *Exception，完整 traceback 去对应的 log_*.txt 里翻。

环境变量是否读到，AGENTS.md 也给了一行现成的：

python -c "import os; from dotenv import load_dotenv; load_dotenv(); print('✓ AZURE_AI_PROJECT_ENDPOINT' if os.getenv('AZURE_AI_PROJECT_ENDPOINT') else '✗ AZURE_AI_PROJECT_ENDPOINT missing')"

六、什么情况说明不是依赖的问题

这一步别省，否则很容易在环境里反复重装。以下几类，仓库里都写明了另有原因：

报缺环境变量（比如取不到 AZURE_AI_PROJECT_ENDPOINT）：是 .env 没建或没填。Windows 上用 Copy-Item .env.example .env，然后按 00-course-setup/README.md 的表格填 endpoint 与部署名。
认证类报错：这门课绝大多数 notebook 走 AzureCliCredential / DefaultAzureCredential，靠的是你的 az login 会话，跟包版本无关。先 az account show 确认登录状态。
HTTP 429：校验脚本把它归为 transient 并会重试；技能文档还专门写了，如果某个模型部署经常 429，要看订阅级的 GlobalStandard TPM 配额，只提单个部署的容量没用。
StdinNotImplementedError：技能文档写明，这是 human-in-the-loop 那类需要输入的 cell 在无人值守执行下的表现，会被每格超时（-Timeout）兜住，不是装错了包。
Lesson 05 / 16 找不到 Azure AI Search：这两课有 in-memory 的兜底路径，本来就能跑；Lesson 16 只有在 AZURE_SEARCH_SERVICE_ENDPOINT 与 AZURE_SEARCH_API_KEY 两个都设置时才切到 Azure AI Search，它用的是基于 key 的认证。
*-dotnet-* notebook 跑不起来：校验脚本默认排除 .NET notebook，需要 .NET Interactive kernel 并加 -IncludeDotnet。.NET 侧的版本由仓库根的 global.json 约束，00-course-setup/README.md 要求 .NET 10 SDK 或更高，自查命令是 dotnet --list-sdks。
macOS 上的 SSL 证书报错：00-course-setup/README.md 的 Troubleshooting 给了三个选项（跑 Python 的 Install Certificates 脚本、connection_verify=False、装 truststore）。这里有个要留意的地方：Option 2 说 Lesson 6 的 notebook 里”已经放了一段注释掉的 workaround”，但我们在 06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb 里没有找到 connection_verify 这个字样，该 notebook 当前用的是 OpenAI 客户端加 client.responses.create(...)，而不是文档里那段 ChatCompletionsClient。文档这一节还没跟上代码。顺带一提，文档自己也标了警告：关掉 SSL 校验会降低安全性，只作为开发环境的临时手段。

判定顺序上，我的建议是先跑 -List 确认脚本认得出你的解释器，再对单课跑 nbconvert 冒烟，最后才动手重建环境。三处依赖来源心里有数之后，绝大多数”装不上”其实是在问”这一格 -U 把我基线里的哪一个包顶掉了”。

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

文中出现的包名与版本写法为仓库当前文件的原样内容，随版本变动，不构成对你环境中解析结果的保证。安全与合规相关做法请结合自身环境评估，本文不构成安全方案建议。