GitHub Models 跑微软 AI Agent 入门课示例：token 报错

2026-08-18

站内工具 token 计算器 → 粘一段文本，估算它占多少 token、按当前单价一次调用大概花多少钱。

现象：你的 `.env` 和课程的 `.env.example` 已经不是一套东西了

最常见的处境是这样的：你从某篇写于早些时候的上手文里抄了一份 .env，里面写着 GITHUB_TOKEN、GITHUB_ENDPOINT、GITHUB_MODEL_ID；或者你 fork 了 ai-agents-for-beginners 之后一直没同步。然后打开某一课的 notebook 一跑，报错五花八门——KeyError、404 Not Found、401 Unauthorized、deployment not found——你开始怀疑是 token 的权限范围（scope）勾少了，跑去 GitHub 设置页反复改 PAT 的勾选项。

这个方向多半是错的。ai-agents-for-beginners 仓库在多处逐字写明：GitHub Models 已废弃、退役时间为 2026 年 7 月，且不支持 Responses API。CHANGELOG.md 的迁移条目写明，.env.example 里的 GITHUB_TOKEN、GITHUB_ENDPOINT、GITHUB_MODEL_ID 三个变量已被移除，取而代之的是 AZURE_OPENAI_ENDPOINT、AZURE_OPENAI_DEPLOYMENT 和可选的 AZURE_OPENAI_API_KEY。也就是说，你要配的根本不是 GitHub 侧的 token 权限，而是 Azure 侧的凭据与部署名。

.agents/skills/azure-openai-to-responses/references/troubleshooting.md 把话说得更死：GitHub Models 那条代码路径「没有迁移路径」，要整段删掉。

第一步：怎么确认自己撞的就是这个问题

三个可执行的判定动作，按顺序做：

动作一，比对变量名。 打开仓库根目录的 .env.example，看它当前分了哪几组。当前版本里，多数课依赖的是 AZURE_AI_PROJECT_ENDPOINT 与 AZURE_AI_MODEL_DEPLOYMENT_NAME；第 6、8 课那种直连 Azure OpenAI 的示例另外要 AZURE_OPENAI_ENDPOINT 与 AZURE_OPENAI_DEPLOYMENT。如果你的 .env 里一个 AZURE_ 开头的都没有，问题到这里就已经定位了。

动作二，搜残留的旧 endpoint。 仓库自带的迁移 skill 里有个脚本 .agents/skills/azure-openai-to-responses/scripts/detect_legacy.py，它用来识别旧路径的正则里就包含 models\.github\.ai|models\.inference\.ai\.azure，并标注为「Responses API not supported — remove」。同一个 skill 根目录下的 .agents/skills/azure-openai-to-responses/SKILL.md 在验收清单里要求这个模式零命中。所以你在自己代码里搜这两个域名，搜到就是命中。

动作三，看报错是「取不到变量」还是「取到了但不对」。 这一条容易被忽略，但它决定了你该往哪边查。第 11 课的 11-agentic-protocols/code_samples/github-mcp/app.py 里，两种取法是混用的：

provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

而同一个文件靠前的位置，Azure AI Search 的两个值是这么取的：

search_service_endpoint = os.getenv("AZURE_SEARCH_SERVICE_ENDPOINT")
search_api_key = os.getenv("AZURE_SEARCH_API_KEY")

os.environ[...] 取不到会直接抛 KeyError，os.getenv(...) 取不到返回 None 然后继续往下传。所以：报 KeyError 的，去查那两个必填的 Foundry 变量；不报错但行为不对的，去查 getenv 那一组。

第二步：仓库给出的处置——权限范围到底指什么

这里是最容易配错的一层。课程当前的默认路线是无密钥：00-course-setup/README.md 的 Step 3 写明，多数 notebook 通过 azure-identity 包里的 AzureCliCredential 或 DefaultAzureCredential 认证，两者都会读取你的 az login 会话，因此不需要在 .env 里放 API key。README 自述这是安全实践。

所以「权限范围」在这条路线上不是 GitHub PAT 的勾选项，而是 Entra ID 令牌的 scope。第 6 课 06-building-trustworthy-agents/code_samples/06-system-message-framework.ipynb 的第二个代码单元把它写死在了代码里：

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

client = OpenAI(
    base_url=f"{endpoint.rstrip('/')}/openai/v1/",
    api_key=token_provider,
)

两个细节值得停一下：一是 api_key 位置传的是 token_provider 这个可调用对象，不是字符串；二是 base_url 手工拼了 /openai/v1/ 且带结尾斜杠——同一份 notebook 的注释说明 Responses API 走的是稳定的 /openai/v1/ 端点，不需要 api-version。

至于 Azure AI Search 这条可选路线，仓库确实给了具体的角色名。00-course-setup/README.md 与 00-course-setup/AzureSearch.md 都写了同样两条命令，要分配的是 Search Service Contributor 与 Search Index Data Contributor 两个角色，之前还要把服务的认证方式打开：

az search service update --name <service-name> --resource-group <resource-group> --auth-options aadOrApiKey

需要注意仓库自己标出的例外：README 写明第 16 课的 notebook 当前用的是基于 key 的认证，只有 AZURE_SEARCH_SERVICE_ENDPOINT 与 AZURE_SEARCH_API_KEY 两个都设了才会从内存检索切到 Azure AI Search，否则一直留在内存检索。README 还特意补了一句：上面那两条 RBAC 步骤适用于 setup 指南的示例和你自己的代码，并不会让第 16 课的 notebook 变成无密钥。这一条很反直觉，照着 RBAC 配完发现没生效的人，多半就是撞在这里。

报错与配置项的对应关系，仓库的 troubleshooting.md 里已经列过一部分，挑跟凭据、地址、部署名相关的几条：

报错	仓库给出的对应配置项
`404 Not Found` on `/openai/v1/responses`	`base_url` 缺 `/openai/v1/` 后缀（且要带结尾斜杠）
`401 Unauthorized` after switching to `OpenAI()`	`api_key` 没设，或 token provider 没按可调用对象传进去
`deployment not found`	`model` 参数要用部署名，不是模型名
`AzureDeveloperCliCredential` → `CredentialUnavailableError`	租户不对或没登录，需要显式传 `tenant_id`
`404 Not Found` 指向 `models.github.ai`	GitHub Models 不支持 Responses API，删掉这条路径

这张表怎么读：前四行是「配对错了」，最后一行是「路线本身没了」。先判断自己是哪一类，再动手改。

第三步：改完怎么验证

Windows 侧和 Linux/macOS 侧的差异集中在两处，README 里都给了成对的命令。建虚拟环境之后激活：

# Command Prompt for Windows
venv\Scripts\activate

# zsh/bash
source venv/bin/activate

复制配置模板：

# PowerShell
Copy-Item .env.example .env

# zsh/bash
cp .env.example .env

登录态用这条确认：

az account show

README 的 Step 3 把它列为第 4 步「Verify」。如果你在没有浏览器的远程环境或 Codespaces 里，README 给的是 az login --use-device-code。

依赖侧还有一个容易被跳过的检查：requirements.txt 里把 Microsoft Agent Framework 的核心包钉在了某个版本线上，并在注释里说明更高版本引入了破坏性改动（移除了部分类型、改了构造函数、去掉了某个方法上的 model= 参数）。如果你是从旧 fork 升上来的，pip install -r requirements.txt 之后最好确认装的确实是这个 pin，而不是你早先手工装的更高版本。这是仓库当前的 pin，随版本可能变动。

第四步：`GITHUB_TOKEN` 什么时候仍然是对的

不要一刀切地把这个变量名当成过期物。CHANGELOG.md 的验证条目自述：仓库里剩下的 GITHUB_TOKEN 引用只有两处——GitHub Actions workflow 里的 Actions token，以及第 11 课 GitHub MCP 服务器所需的 PAT——两者都是合法的，与 GitHub Models 无关。

顺带说一处仓库内部的不一致，翻到这里的人容易被绕进去：同在 11-agentic-protocols/code_samples/github-mcp/ 目录下，README.md 给的连接方式是在命令行上传 --env GITHUB_PERSONAL_ACCESS_TOKEN=[YOUR PERSONAL ACCESS TOKEN]，而 MCP_SETUP.md 的「Environment Variables」一节写的是在 .env 里放 GITHUB_TOKEN=your_github_token。两个文件写的变量名不一样。这里只是把两处摆在一起提醒你注意，具体以你实际启动的那个 MCP server 版本读哪个名字为准。

第五步：什么情况说明不是 token 的问题

以下几类报错跟凭据、权限范围完全无关，别在这上面浪费时间，troubleshooting.md 把它们归在别处：

missing_required_parameter: tools[0].name、unknown_parameter: input[N].tool_calls：这是工具定义与多轮工具结果还停留在 Chat Completions 的形状，要改成 Responses API 的扁平写法与 function_call_output 条目。
输出为空或被截断：max_output_tokens 给小了。仓库写明推理模型的 reasoning token 也计入这个上限。
temperature 或 top_p 报错：GPT-5 与 o 系列不接受这些显式取值，仓库给的处置是去掉或按其说明处理。
429 Too Many Requests：限流，且仓库特意提醒 Responses API 流式下 429 可能发生在流中途，异步迭代器会抛异常，要自己包 try/except。
macOS 上的 ssl.SSLCertVerificationError：这是证书信任问题，README 单列了一节，首选方案是跑 Python 自带的 Install Certificates.command，或者装 truststore 后在脚本顶部调 truststore.inject_into_ssl()。这一节是 macOS 专属，Windows 上遇到证书错误不适用这些步骤。

最后一条 SSL 的处置里还藏着一个对不上号的地方，值得提前打个招呼：00-course-setup/README.md 的 Option 2 标题逐字写的是「for GitHub Models notebooks only」——这一节本身就是那条已废弃路线留下的残迹；它说第 6 课的 notebook 里「已经包含一段注释掉的 connection_verify=False」，让你按需取消注释。但在当前仓库的英文内容里，connection_verify 这个字符串只出现在这份 README 自己里面，它指向的那个 notebook 里搜不到。两处对不上，你照着去找会白找一趟。顺带一提，README 那段本身也标注了警告：关闭 SSL 校验会降低安全性，只应作为开发环境下的临时手段。

整篇的结论其实很短：这门课已经不走 GitHub Models 了，所以「token 权限没配对」这个命题在当前版本上多半不成立。 你真正要对上的是三件东西——.env 里的变量名、az login 的登录态与租户、以及部署名。三者对上之后，剩下的报错基本都在 Responses API 的参数形状上，那是另一类问题。

该课程持续更新，上面提到的文件路径、变量名与命令随版本变动，请以仓库最新内容为准。

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

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