Azure AI Foundry 权限报错：微软 AI Agent 入门课的前置条件

2026-08-18

第 2 课有两条路：一条是 notebook 里用 Microsoft Agent Framework 连过去，另一条是打开门户点着建一个 Agent。后面这条对应的文件是 02-explore-agentic-frameworks/azure-ai-foundry-agent-creation.md。它是这一课里唯一一份纯门户操作的练习稿，很多人是在这里第一次撞上权限问题——按钮点不动、创建资源被拒、或者页面上根本看不到该有的入口。

先说一个容易造成误会的命名。这份文件里逐字写着一句备注：Microsoft Foundry 的前身名字是 Azure AI Studio。仓库现在通篇用的是 Microsoft Foundry 这个称呼，而很多人搜的关键词还是 Azure AI Foundry / Azure AI Studio。你在门户里看到的界面标题与文档里的措辞对不上，不一定是版本对不上，先别急着怀疑自己找错了地方。

一、这份练习稿写明的前置条件只有两条

azure-ai-foundry-agent-creation.md 的 Prerequisites 一节短得很，只有两条：

一个带有效订阅的 Azure 账号；
你需要有创建 Microsoft Foundry hub 的权限，或者由别人替你创建好一个。

紧接着第 2 条下面还有一句限定：如果你的角色是 Contributor 或 Owner，就可以照着这份教程走下去。

这句话值得停一下。它给的是一个「够用」的判据，而不是「必须」的判据——文档没有说低于这两个角色就一定不行，也没有点名任何更细的内置角色。所以当你的账号既不是 Contributor 也不是 Owner 时，最省事的做法不是去猜该申请哪个角色，而是走第 2 条给的第二条路：让有权限的人先把 hub 建好，你只在项目层面往下做。

需要说清楚的是：运行第 2 课 notebook 需要哪个数据面角色，仓库里没有找到相关说明。 全仓明确点名角色的地方只有 Azure AI Search 那一段（后面会讲），Foundry 这边没有对应的角色清单。所以不要指望从课程文件里抄到一份 RBAC 配置表，这份东西不在仓库里。

二、先确认卡在哪一层，再动手

权限报错的第一步是分层，别一上来就找人加角色。这三层的判定动作都是可执行的。

第一层，订阅与登录。 00-course-setup/README.md 的 Step 3 把这一步写得很直白：绝大多数 notebook 通过你的 Azure CLI 登录态认证，用的是 azure-identity 包里的 AzureCliCredential（或 DefaultAzureCredential，它同样会捡起 az login 会话），因此不需要 API key。对应的动作是：

az login

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

az login --use-device-code

登录完之后，README 明确给了验证命令：

az account show

README 对 Windows 单独给写法的地方是虚拟环境激活这一步：zsh/bash 侧是 source venv/bin/activate，标注 Command Prompt for Windows 的那一段给的是 venv\Scripts\activate。如果你是在没激活的解释器里跑 notebook，缺的其实是包，不是权限。

第二层，资源与部署。 .agents/skills/testing-course-samples/SKILL.md 的前置检查里给了一条查部署的命令：

az cognitiveservices account deployment list -g <rg> -n <account> -o table

这一步是用来回答「模型到底部署了没有」。练习稿里的门户路径是：项目左侧 My assets → Models + endpoints → Model deployments 页签 → + Deploy model → Deploy base model，然后搜 gpt-5-mini 并确认。gpt-5-mini 是仓库文件里写的示例模型名，不是唯一选择，.env.example 的注释要求的是选一个未废弃且支持 Responses API 的部署。

第三层，配置有没有到位。 第 2 课的 Python notebook 02-explore-agentic-frameworks/code_samples/02-python-agent-framework.ipynb 里，建客户端那一格自己带了检查：读 AZURE_AI_PROJECT_ENDPOINT 与 AZURE_AI_MODEL_DEPLOYMENT_NAME，任一为空就 raise ValueError，报错文本直接告诉你缺哪两个变量。然后才是：

provider = FoundryChatClient(
    project_endpoint=endpoint,
    model=model,
    credential=AzureCliCredential()
)

这一格里没有出现任何 key。也就是说，如果你在找「Foundry 的 API key 填哪里」，方向就跑偏了——这条链路上凭据来自 CLI 登录态。

三、缺什么补什么

按上面三层对号入座：

建不了 hub：走练习稿给的第二条路，让 Contributor 或 Owner 建好 hub 再把项目交给你。
有 hub 没项目 / 没模型：00-course-setup/README.md 的 Step 1 把顺序写死了——先建 hub，在 hub 里建 project，再从 Models + Endpoints → Deploy model 部署模型。
.env 没配：Step 4 给了两条平行命令，bash 侧是 cp .env.example .env，PowerShell 侧是 Copy-Item .env.example .env。要填的两项在 README 的表格里写明了出处：endpoint 在项目的 Overview 页，部署名在 Models + Endpoints 里那个部署的名字。
第 5、16 课要接 Azure AI Search：这里才是仓库里唯一点名角色的地方。00-course-setup/AzureSearch.md 与 README 都写明，创建/加载索引并查询需要 Search Service Contributor 与 Search Index Data Contributor 两个角色，并给了开启 RBAC 的命令 az search service update ... --auth-options aadOrApiKey 以及两条 az role assignment create。
第 8 课的 Bing grounding：需要 BING_CONNECTION_ID，README 写明它在门户里项目的 Management → Connected resources 里那条 Bing 连接上。

Azure AI Search 这块有个坑是仓库自己点破的，值得单独拎出来：README 写明第 16 课的 notebook 目前用的是基于 key 的认证，只有当 AZURE_SEARCH_SERVICE_ENDPOINT 与 AZURE_SEARCH_API_KEY 两个都设置时才会从内存检索切到 Azure AI Search，否则一直走内存路径；上面那套 RBAC 步骤适用于配置指南里的示例和你自己的代码，并不会让第 16 课的 notebook 变成 keyless。这意味着你把两个角色都授干净了，第 16 课照样不走真实索引——这不是权限没配好，是那个 notebook 的取值条件就是这么写的。

四、补完之后怎么验证

除了 az account show 和上面那条 deployment list，仓库里带了一个批量跑 notebook 的校验脚本 scripts/validate-notebooks.ps1，.agents/skills/testing-course-samples/SKILL.md 里给了用法。只验第 2 课可以只跑这一课：

pwsh scripts/validate-notebooks.ps1 -Filter '02-*' -Timeout 600

想先看会跑哪些而不真跑，用 -List。如果 python 不在 PATH 上（skill 里点名了 Windows Store 的那个别名），用 -Python 指定解释器路径。脚本的 param 块里确实有 -Python、-Timeout、-Filter、-List、-Retries、-IncludeDotnet 这几个参数，默认排除 .NET 的 notebook。执行产物（逐个 notebook 的日志与 results.json）写在 $env:TEMP\aiab-nbval 下，退出码是失败个数。

以上为按仓库脚本 param 块与其注释帮助中的参数语义组合的示例，未经实测，以仓库最新内容为准。

练习稿最后还有一节 Clean up resources：测完之后到 Azure 门户里找到这次用的资源组，直接删掉整个资源组。这一步和权限相关的地方在于——删资源组同样要权限，别建的时候借别人的手，删的时候找不到人。

五、哪些报错其实不是权限问题

这一节比前面几节更值钱，因为把非权限问题当权限问题查，会白白等一轮审批。

scripts/validate-notebooks.ps1 里有一行注释和一个正则，把「值得重试的错误」框得很清楚：注释写的是共享配额的 429、Azure CLI 的 token 抖动、以及超时；正则里逐字包含 Too Many Requests、exceeded your current quota、CredentialUnavailable、Failed to invoke the Azure CLI、TimeoutError 这些片段。紧跟着的注释还写明：确定性的代码错误（ImportError、TypeError 这类）不重试。

据此可以反着读：

命中 CredentialUnavailable 或 Failed to invoke the Azure CLI —— 这是 CLI 会话取不到的问题，重新 az login 就是了，不是 RBAC 少给了角色。
命中 429 或配额相关字样 —— 这是配额。skill 里补了一句关键的：如果某个部署经常 429，要查订阅级的 GlobalStandard TPM 配额（az cognitiveservices usage list -l <region>），把单个部署的容量调大对订阅配额耗尽是没用的。练习稿里那句「降低 TPM 有助于避免过度占用订阅配额」的备注，说的是同一件事的另一头。
报的是 notebook 自己抛的 ValueError，文本里写着缺环境变量 —— .env 没加载或没填，跟权限无关。
报的是 as_agent / create_agent 找不到 —— 这是版本问题。CHANGELOG.md 里写明示例针对较新的 Microsoft Agent Framework，规范的建 agent 调用是 client.as_agent(...)，如果你固定了别的版本，要自己确认 as_agent 与 create_agent 哪个可用。顺带一提，第 2 课 notebook 的说明文字里写的是 provider.create_agent()，而代码单元里实际用的是 provider.as_agent()——同一个文件里这两处不一致，遇到 AttributeError 时先看这里。
macOS 上的 CERTIFICATE_VERIFY_FAILED —— README 的 Troubleshooting 一节专门讲了这个，是证书链问题。Windows 侧不适用这一条。

顺带提醒一句：README 在给那个 connection_verify=False 的临时绕法时，自己带了警告——关掉 SSL 校验会跳过证书验证、降低安全性，只在开发环境临时用，不要用在生产。别把它当成「权限问题的万能开关」。

一个可以自查的判断顺序：先看这条报错在不在上面那个「可重试」清单里，在，就先按会话或配额处理；不在，再看是不是 notebook 自己抛的配置检查；都不是，才值得回到角色这一层，按练习稿那两条前置条件核对。

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

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