常见问题与排错指南

先确定故障发生在网站、Python、身份权限、模型调用还是工具执行。不要连续更换框架来碰运气；一次只改变一个变量，并保留不含敏感信息的错误类型与版本。

网站安装与访问

现象	优先检查	处理
npm ci 失败	Node 版本、网络、锁文件	用 Node 22 LTS；保留 package-lock，不随意 npm update
端口被占用	本机其他服务	npm run dev -- --port 4174 --strictPort
深层页面刷新 404	是否部署完整 dist、URL 是否带 .html	使用本站生成的 .html URL；不要只上传首页
子目录部署资源 404	BASE_PATH 是否带首尾斜线	用同一 base 重新构建并部署整个输出
搜索没命中英文缩写	试中文名称或完整词	正文与术语表都在本地索引，无在线搜索服务
进度未保存	浏览器禁止 localStorage 或清理了站点数据	在允许本地存储的普通窗口使用；无账号同步
图太宽	流程/表格/代码容器可横向滚动	点击图片放大；键盘聚焦滚动区域后操作

Python 与依赖

python3 --version 确认 3.12+。网站 Node 环境和 Python 实验环境相互独立。标准库综合项目不需安装上游的大型依赖集合。

• ModuleNotFoundError：在同一个虚拟环境执行 python -m pip ... 和运行脚本；Jupyter 选同一内核。
• SyntaxError: await outside function：使用 Notebook，或把异步部分包进 async def main() 并调用 asyncio.run()。
• ImportError / 方法不存在：核对 agent-framework-core 版本；本课程核心固定 1.10.0，README 仍有旧 API 片段，见来源说明。
• 类型约束没有生效：Python 注解不自动验证；检查实际是否传了 response_format 并读取解析对象。
• 本地文件损坏：先备份对应 .assistant-data 文件；不要把异常当空数据覆盖。确认愿意清除该命名空间时使用 --forget。

身份、部署与网络

错误	常见原因	处理方向
401 / 登录过期	凭据无效、租户不符	在本地重新 az login，确认账号与租户
403	项目或模型权限不足	请资源管理员核对访问角色，不能靠改 key 名称绕过
404 deployment	填模型家族名而非实际部署名，或端点错误	对照项目端点与已部署名称
429	配额或请求速率超限	限并发、有限退避与告警，检查账号额度
TLS / 证书错误	公司代理证书、网络拦截	配置可信证书链或联系网络管理员；不要关闭证书校验
Search 未启用	endpoint 和 key 未同时配置	第 16 章远端 Search 只在两者齐全时启用
超时	排队、长输出、工具卡住	按调用链拆分耗时，增加合理超时与退出机制

不要将完整 .env、访问令牌、客户文档或浏览器截图提交到公开 issue。错误报告可包含包版本、去掉敏感信息的错误码、触发步骤和是否能用最小输入复现。

模型、工具与证据

模型说“已预订”，为什么工具没有执行？ 模型生成的自然语言不是执行凭证。检查应用的工具执行事件、业务确认编号和权限结果。原课程多处工具返回预设数据，不会真实订票。

模型调用了工具却答错？ 检索到的资料可能不相关、未选入窗口、内容过期或被错误解释。分别观察候选、实际上下文、引用与原文。参考交互 RAG。

为什么提示“禁止泄露密钥”还不够？ 提示不能替代执行层权限。密钥不进入模型上下文，工具只暴露必要范围，外部资料当数据处理。

多 Agent 一定更好？ 不一定。多一次角色交接就多一次延迟、上下文传递和失败机会；先比较单 Agent 基线，再用评估判断是否值得拆分。

为什么演示结果永远一样？ 三个浏览器演示和默认 Python 模型是明确的预设模拟。它们用来学习控制流；真实模型需单独开通资源并测量结果。

怎样提供可复现问题

记录课程编号、来源提交、Python/Node 与 SDK 版本、运行文件和最小输入；说明预期结果与实际现象。把网站检查与云账号限制分开。源文件缺失、历史 API 与实际验证范围统一记录在检查报告。