微软 AI Agent 入门课专题
本专题共 50 篇。内容依据 microsoft/ai-agents-for-beginners 仓库的公开内容整理。凡仓库里没有写明的地方，文中一律照实写 「仓库里没有找到相关说明」，不做推断。
微软 AI Agent 入门课环境配置：requirements.txt 与 .env 怎么填
ai-agents-for-beginners 的 notebook 打开就跑不通，多半卡在依赖版本、环境变量少填、或者 Python 与 .NET 两条路线的准备步骤串了。本文按仓库 00-course-setup/README.md 与各章代码样例，把依赖、变量清单、两条路线的差异和验证方式逐条对上。
环境、接入与两条语言路线
这门课的示例分 Python 与 .NET 两套，同一课常有两份实现。这一组覆盖 GitHub Models 的 token 权限、在 Azure AI Foundry 里建 Agent 的完整步骤与常见权限报错、notebook 依赖打架、.NET 示例的 SDK 与包引用，最后一篇逐项对照两套实现在客户端构造、工具注册、异步模型三处的写法差异。
GitHub Models 跑微软 AI Agent 入门课示例：token 报错
从旧教程或旧 fork 里抄来的 GITHUB_TOKEN 配置，在 ai-agents-for-beginners 当前版本上跑不通。本文按仓库里的 .env.example、00-course-setup/README.md、各课 notebook 与迁移 skill，把「缺哪个环境变量」「权限范围是什么」「哪条报错对应哪个配置项」逐条对上号，并说清哪些报错跟 token 根本没关系。
在 Azure AI Foundry 里建 Agent：微软 AI Agent 入门课给的完整步骤
ai-agents-for-beginners 的第 02 课带了一份门户建 Agent 的动手练习，从建 hub、部署模型一路走到 playground。这篇把练习文档里写明的每一步拆开说清在改什么，补上课程环境配置那一课要求的权限与依赖，并指出门户产物与 notebook 代码之间到底靠哪两个变量对接、哪些地方仓库里没有给说明。
Azure AI Foundry 权限报错：微软 AI Agent 入门课的前置条件
跟着 ai-agents-for-beginners 第 2 课建 Agent，卡在建 hub 或建项目的权限上是最常见的一类中断。这篇按仓库里 azure-ai-foundry-agent-creation.md 与 00-course-setup 白纸黑字写明的角色与资源要求，把「先确认哪一层」「缺什么补什么」「哪些报错其实不是权限」逐条拆开。
notebook 依赖装不上或版本打架：微软 AI Agent 入门课的三处依赖源
ai-agents-for-beginners 的依赖不止 requirements.txt 一处，每课 notebook 第一格还会自己 pip install，个别课还带精确钉版。本文按仓库里的三处依赖来源梳理冲突从哪来、怎么用仓库自带的判定动作确认，以及哪些报错其实跟依赖无关。
微软 AI Agent 入门课的 .NET 示例跑不起来：SDK 版本与包引用对一遍
ai-agents-for-beginners 的 .NET 示例是单文件应用形态，没有 csproj，靠文件头的
Python 版和 .NET 版差在哪三处：微软 AI Agent 入门课同课对照
ai-agents-for-beginners 每一课都配了 Python notebook 和 .NET 单文件脚本两份代码。两份读下来会发现差异并不是均匀分布的，而是集中在客户端构造、工具注册、异步模型三处。本文逐处对照仓库里的原始写法，指出哪些差异只是语言习惯，哪些差异会真的卡住你。
第一个 Agent、工具注册与 Agentic RAG
一个普通函数怎么变成 Agent 能调的工具、参数注解为什么影响触发、AzureSearch 的索引与字段怎么配。排查侧接两个高频问题：工具注册了却不被调用（从课程自带的插件测试文件反查）、Agentic RAG 检索结果为空。最后对照普通 RAG 与 Agentic RAG 差在谁来决定检索。
01-python-agent-framework.ipynb 拆解：微软 AI Agent 入门课
第一课的 notebook 只有寥寥几个 cell，真正卡住人的是三处：client 用什么参数初始化、agent 由谁构造出来、run 的调用形态为什么有两种。本文对着仓库里的这个文件逐块拆，并把依赖版本上那处容易踩的不一致标出来。
微软 AI Agent 入门课第 4 课的工具注册：函数怎么变成能调的工具
沿着 ai-agents-for-beginners 第 4 课的 Python notebook 走一遍工具注册：@tool 装饰器把普通函数变成工具时读走了哪些信息，Annotated 参数注解落到哪里，tools 该挂在 as_agent 还是 run 上，以及这一课里 response_format 的说法与代码对不上的那处落差。
Agentic RAG 检索谁来决定：微软 AI Agent 入门课第 5 课的 @tool 封装
ai-agents-for-beginners 第 5 课把检索封装成 tool 交给 agent 调用，而不是在生成前固定跑一遍。本文顺着 05-agentic-rag 的 Python notebook 走一遍：搜索函数怎么用 @tool 装饰、要不要检索的决定权落在哪、Python 与 .NET 两份示例接文档源的路子有何不同，以及冒烟测试断言了什么。
AzureSearch.md 的 Python 与 .NET 两份代码：微软 AI Agent 入门课
ai-agents-for-beginners 的 00-course-setup 里给了 Azure AI Search 的 Python 与 .NET 两份建索引示例，字段定义写法并不一样。本文把索引与字段定义、连接配置项、两种语言的写法逐项对上，并交代仓库里写明的边界与验证点。
工具注册了却不被调用：从微软 AI Agent 入门课的插件测试文件反查
工具都传给 agent 了，模型却始终用自然语言糊弄过去，一次 tool call 都不发。本文按 ai-agents-for-beginners 第四课 04-tool-use 的测试文件与 Python notebook，给出一条从「工具对象在不在」到「描述与参数注解写没写」的反查路径，并说明哪些现象不属于这个原因。
Agentic RAG 检索为空：微软 AI Agent 入门课第 5 课三层排查
跑 ai-agents-for-beginners 第五课的 Agentic RAG 示例时，Agent 一本正经地说知识库里没有这条信息。本文按工具返回结构、查询字段对应、索引字段声明三层拆开，逐层给出可在 notebook 里执行的判定动作，依据全部来自课程仓的 05 章代码与 Azure AI Search 配置文档。
普通 RAG 和 Agentic RAG：微软 AI Agent 入门课里谁决定检索
用 ai-agents-for-beginners 第五课的代码，把「固定管线式 RAG」和「Agentic RAG」的分界线落到具体写法上——检索由谁触发、多轮检索靠什么表达、Python 与 .NET 两份示例的代码结构差在哪，以及什么时候这个差异会咬到你。
多智能体与 workflow 编排
第 8 课给了 basic / sequential / concurrent 三种编排跑法，加上一个条件分支示例。这一组讲清节点怎么连、结果怎么汇聚、条件不命中时是什么表现，以及两组选型：编排式 workflow 与自主 Agent 的控制流归属差在哪、单 Agent 到多 Agent 的复杂度增量值不值。规划设计一篇讲任务怎么被拆成子步骤。
basic/sequential/concurrent 差在哪：微软 AI Agent 入门课第 8 课
第 8 课 workflows-agent-framework 目录下的三个 Python notebook，正文铺陈很长，真正的差别集中在 WorkflowBuilder 那几行。本文按仓库代码逐个拆开 add_edge、add_fan_out_edges、output_executors 的连接方式与结果汇聚差异，并指出 README 与 notebook 之间几处对不上的地方。
微软 AI Agent 入门课第 8 课的多智能体：角色、消息与终止条件怎么写
ai-agents-for-beginners 第 8 课把多智能体讲成了设计模式，但真正动手时卡住的是三件事：角色到底写在哪个参数里、一条消息怎么从上一个 agent 走到下一个、什么时候算跑完。本文沿着该课 code_samples 下的 Python notebook 与 .NET 示例，把这三处在代码里的确切位置找出来。
workflow 条件分支不走：微软 AI Agent 入门课第 8 课的判定写在哪一行
第 8 课的条件工作流示例最常被问到两种症状——该拦的稿子进了发布分支，或者审完之后整条流程没了下文。这篇沿着 04.python-agent-framework-workflow-aifoundry-condition.ipynb 把条件节点的定义位置、判定值的来源、以及分支未命中时图上会发生什么，逐处指到具体函数与具体那一行。
workflow 还是自主 Agent：微软 AI Agent 入门课第 8 课的两种写法
ai-agents-for-beginners 第 8 课同时给了两组代码：一组把下一步跑谁写死在图的 edge 上，一组把决定权交给 agent 自己的 instructions 与 tools。本文沿着课程仓里 08-multi-agent 的 Python 与 .NET 样例，把控制流归属、跑前能不能预演、出错落在哪一层这三件事拆开讲，并给出一条按处境倒推的选择路径。
该拆成多 Agent 吗：微软 AI Agent 入门课第 1 课与第 8 课对照
ai-agents-for-beginners 的第 1 课和第 8 课用的是同一个模型客户端、同一个旅行场景，差别全在编排层。本文把两课的 Python 与 .NET 示例逐段对照，说清楚从单 Agent 走到 WorkflowBuilder 到底多写了哪些代码、多背了哪些状态与消息的管理成本，以及什么时候这笔成本值得付。
微软 AI Agent 入门课第 7 课的规划：TravelPlan 在哪一步被推翻
ai-agents-for-beginners 第 7 课讲规划设计，但课程正文与配套 notebook 给的计划结构并不是同一个。本文沿着 07-planning-design 的 README 与 07-python-agent-framework.ipynb 走一遍：计划的字段怎么定义、response_format 怎么把它变成硬约束、concierge 怎么执行、以及重规划的触发点写在哪里。
协议：MCP 与 A2A
课程第 11 课给了 MCP 的 client/server 两端最小实现和一个 A2A 示例。这一组把两端怎么起、工具怎么暴露与发现、会话断了怎么用 resumable client 续上讲清楚，并对照两个协议解决的根本不是同一个问题——通信对象与消息内容都不同。
接 MCP：微软 AI Agent 入门课第 11 课的 client 与 server 最小实现
以 ai-agents-for-beginners 第 11 课的 mcp-agents 示例为准，逐段拆开 server 端怎么用装饰器暴露工具、client 端怎么发现工具并把参数填进去，以及一次 tools/call 在两端代码里各经过哪些对象。附前置条件、Windows 侧启动方式、示例代码里明确写死的边界，以及连上之后该看哪几行输出确认配对成功。
微软 AI Agent 入门课第 11 课：WorkflowBuilder 怎么串起三个 Agent
拆 ai-agents-for-beginners 第 11 课的 A2A 示例代码：三个专职 agent 各自的角色定义写在哪、WorkflowBuilder 怎么把它们连成一条边、事件流按什么字段分段，以及这份 notebook 与真正的 A2A 协议之间隔着什么。顺带对照同一课 MCP 示例，看两个协议在代码里落在了不同的参数位。
MCP 连不上：微软 AI Agent 入门课 client 端连接流程逐步核
ai-agents-for-beginners 第 11 课的 mcp-agents 示例跑不通时，别急着怀疑网络。本文顺着 client/client.py 的代码把一次连接拆成取 token、建传输、建 session、initialize、list_tools 五段，指出每段对应的报错长什么样、怎么定位，以及哪些现象说明问题根本不在连接上。
MCP 会话断了怎么续：微软 AI Agent 入门课的 resumable client
ai-agents-for-beginners 的第 11 课带了一套可续跑的 MCP 客户端与服务端示例。这篇按排查顺序拆开看：事件存到哪张表、重放时到底重放哪一段、以及重启客户端后「说是在恢复但什么都没发生」时该看哪几行日志、哪几个文件。
MCP 与 A2A 的代码入口在哪：微软 AI Agent 入门课第 11 课
ai-agents-for-beginners 第 11 课同时讲 MCP、A2A、NLWeb 三个协议，但代码目录里能跑协议的只有一条链。本文顺着 11-agentic-protocols/code_samples 走一遍：两个 notebook 分别模拟了什么、真正的 MCP 客户端与服务端在哪个文件、一次 travel_agent 调用经过哪些回调，以及三个协议在代码层面的落差。
MCP 和 A2A 不是同一个问题：微软 AI Agent 入门课第 11 课
ai-agents-for-beginners 第 11 课同时给了 MCP 与 A2A 两组示例代码，很多人读完仍然分不清该用哪个。本文只对照这两组示例里白纸黑字写明的东西——各自在跟谁通信、消息里装的是什么、代码把边界划在了哪里，并指出 A2A 那份 notebook 自己声明了它是简化的进程内模拟。
上下文与记忆
课程把上下文拆成哪几块来管、对话滚到超限时摘要示例插在流程哪一步、被摘掉的内容范围有多大。记忆侧有两种实现，这一组讲清它们各自的数据模型与召回方式、写入读出的键怎么构造，以及什么时候该上外部记忆层。
微软 AI Agent 入门课第 12 课：summarize_preferences 落在五块里的哪块
ai-agents-for-beginners 第 12 课把 Agent 要管的上下文拆成五类，并配了一个 Python notebook 做摘要示例。本文沿着 12-context-engineering/README.md 与 12-chat_summarization.ipynb 走一遍：五类分别对应代码里的哪一行，summarize_preferences 这个工具究竟压缩了哪一块，以及仓库里那个 scratchpad 文件为什么和 notebook 对不上。
对话越滚越长：微软 AI Agent 入门课第 12 课的摘要接在哪一步
ai-agents-for-beginners 第 12 课给了一个 summarize_preferences 摘要工具，但照着加完会发现历史一点没变短。本文沿着 12-chat_summarization.ipynb 的代码，把摘要的触发位置、被摘走的内容范围、摘要结果的回填形式三件事逐一定位，并给出排除其它原因的判定动作。
两个 notebook 的记忆存取路径：微软 AI Agent 入门课第 13 课
ai-agents-for-beginners 第 13 课给了两份记忆实现，一份把偏好塞进进程内的字典，一份挂在 Cognee 知识图谱上。本文顺着两个 notebook 的代码，逐个指出存储后端在哪、写入调用点在哪、召回调用点在哪，以及 README 与代码对不上的几处。
微软 AI Agent 入门课第 13 课的记忆结构：两种实现的抽象不同
ai-agents-for-beginners 第 13 课给了两个 notebook，一个把长期记忆存成进程内的 dict，一个交给 Cognee 的知识图谱。本文沿着两份代码走一遍：数据写进去时是什么形状，取出来时走的是哪条路，以及两处仓库里白纸黑字的不一致。
记忆写进去读不出来：微软 AI Agent 入门课第 13 课两种实现的存取键
第 13 课给了两份记忆实现，一份用进程内字典，一份用 Cognee 知识图谱。两份都存在写的时候好好的、换个会话就读不出来的坑，但坑的位置完全不同。本文按现象、判定动作、处置、验证、排除的顺序，把两份 notebook 里的键构造、作用域和清理时机逐行对出来。
两种记忆实现怎么选：微软 AI Agent 入门课第 13 课的外部记忆层
ai-agents-for-beginners 第 13 课给了两份 notebook，一份用进程内 dict 存偏好，一份用 Cognee 知识图谱。本文按依赖、数据模型、召回能力三条线对照两者在仓库里白纸黑字写明的差异，并给出从你的处境倒推的选择路径，顺带指出课程 README 与 notebook 之间几处对不上的地方。
课程主线解读
课程怎么定义 Agent 的最小构成、框架全景带你看的是哪几层、设计模式落到 notebook 里长什么样、元认知那一步怎么插进流程。加上 Microsoft Agent Framework 一课的示例覆盖面，以及同一课里 LangChain 托管写法与原生写法的对照。
微软 AI Agent 入门课怎么定义 Agent：第 1 课划的最小构成
ai-agents-for-beginners 第 1 课没有用形容词定义 Agent，而是把它压成三个部件，再用一份 notebook 把这三个部件落到几行代码上。本文沿着 01-intro-to-ai-agents 的 README 与 Python/.NET 两份示例走一遍，指出「聊天机器人」与「Agent」在代码里究竟差在哪一个参数上，以及第 1 课埋了哪个没解释的开关。
Client/Agent/Tools/Session 四层：微软 AI Agent 入门课第 2 课全景
第 2 课给了三份代码示例，很多人当成三条并列教程去读。本文按课程自己给出的 Client、Agent、Tools、Session 四层视角，把一次「查目的地是否可订」的请求沿着代码走一遍，标出每层在哪个文件、对应哪个类名与配置项，并指出 notebook 说明文字与可执行 cell 之间的一处不一致。
微软 AI Agent 入门课第 3 课的 Agentic 设计模式：notebook 里是哪三个
ai-agents-for-beginners 第 3 课的 README 讲的是人机交互层面的设计原则，而同一课的 Python notebook 落地的是另外三个代码模式。本文沿着 03-python-agent-framework.ipynb 从 provider 初始化走到两个单一职责 agent 的手工串联，标出每个模式对应的类名、装饰器与配置项。
微软 AI Agent 入门课第 9 课的元认知：自评插在哪、评完给谁用
ai-agents-for-beginners 第 9 课讲元认知，但真正要落地只有两个问题：自评这一步写在流程的哪个位置，以及评估出来的那段文字被谁消费。本文顺着 09-metacognition 的 notebook 一行行走，标出两个自评插入点、评估结果的去向，并对照第 16 课里那个真的会拦住发布的 evaluation_gate。
Microsoft Agent Framework 从哪抄起：微软 AI Agent 入门课第 14 课
ai-agents-for-beginners 第 14 课把同一个订房场景写了好几遍，条件路由、middleware、人工介入各占一份。本文沿着 code-samples 目录里的代码走一遍：一次工具调用从 @tool 到 yield_output 经过哪几层，几个示例分别在这条骨架上加了什么，以及同目录两份写法不一致时该照哪一份抄。
LangChain 托管与 Agent Framework：微软 AI Agent 入门课第 14 课
ai-agents-for-beginners 第 14 课的 code-samples 目录里同时放着 LangGraph 托管示例和 Microsoft Agent Framework 原生 notebook，两段代码的入口、环境变量名、人工介入的接法都不一样。本文只对照仓库里白纸黑字写明的机制，给出从你的处境倒推的选路依据。
可信、安全与人工介入
系统消息的结构化写法值得单独读一遍；人工介入的中断点具体设在代码哪一行、待确认信息怎么传递；第 18 课盯的是 Agent 特有的哪几类风险，以及那个票据处理示例演示的攻击路径与拦截点。
可信 Agent 怎么写：微软 AI Agent 入门课第 6 课的系统消息框架
ai-agents-for-beginners 第 6 课里最能直接搬走的，是「用 LLM 生成 system message」的四步框架。本文沿该课 README 与 06-system-message-framework.ipynb 逐格走一遍：meta 提示词、产出的结构化骨架、鉴权与四个可选参数，以及校验环节究竟在哪。
微软 AI Agent 入门课第 6 课：人工介入的中断点设在哪一行
ai-agents-for-beginners 第 6 课的 README 片段把审批放在模型输出之后，配套 notebook 06-human-in-the-loop.ipynb 把它挪到了动作执行之前。本文沿 run_with_revision、tiered_gate、gate_action 这条调用链，说清中断点落在哪一行、驳回后什么被回传。
Agent 安全防哪几类风险：微软 AI Agent 入门课第 18 课的 verify_chain
ai-agents-for-beginners 第 18 课讲的不是提示注入清单，而是「审计员凭什么相信你的日志没被改过」。本文沿着 18-securing-ai-agents 的两个 notebook 走一遍，把课程真正设防的几类风险与它们在 verify_receipt、verify_chain、verify_envelope 里对应的那几行检查一一对上，并交代收据明确不证明什么。
签名票据的防护拦在哪一层：微软 AI Agent 入门课第 18 课
ai-agents-for-beginners 第 18 课用签名票据给 agent 的工具调用留审计痕迹。把它接进自己的项目后，最常见的困惑是分不清验证失败到底卡在签名、链接还是授权哪一层。本文顺着 sample_receipts 里三个 fixture 的数据形态，把课程演示的几条攻击路径和它们各自的拦截点拆开，并说明哪几层这套代码压根不拦。
生产化与部署
第 10 课用报销案例演示了可观测、错误处理、评估三块在代码里的位置；第 16 课的可扩展部署有仓库自带的 skill 写明步骤；第 17 课讲不连云端怎么跑本地 Agent，并对照本地与云端在依赖、配置、伸缩三个维度的取舍。browser-use 一课讲让 Agent 去操作浏览器的接入方式与边界。
微软 AI Agent 入门课第 10 课：报销 demo 里可观测与评估落在哪几行
ai-agents-for-beginners 第 10 课讲的是把 Agent 送进生产环境需要的可观测与评估，但同章那个报销单 demo 打开后并没有 tracer。这篇沿着 10-expense_claim-demo.ipynb 的代码路径走一遍，指出可观测、错误处理、评估这三块在这个 notebook 里实际落在哪几处、哪一块干脆不在这里。
微软 AI Agent 入门课第 16 课：自带 skill 写了哪些部署步骤
ai-agents-for-beginners 的 .agents/skills/deploying-scalable-agents/SKILL.md 把第 16 课压缩成一份可执行清单。本文沿着这份 skill 逐块拆开它列的步骤、它指向的部署产物（hosted agent、smoke-test workflow、测试目录），以及 notebook 里那几个真正管伸缩的配置项，并标出 skill、课程 README 与代码三处对不上的地方。
微软 AI Agent 入门课第 17 课：本地 Agent 不连云端怎么跑
ai-agents-for-beginners 第 17 课把 Agent 从云端搬到单机。本文顺着这一课的 README 与 notebook，讲清 FoundryLocalManager 怎么接出本地端点、工具调用循环为什么要手写、Chroma 那段本地 RAG 的代码与文档不一致在哪，以及它跟第 4 课云端示例差在哪几处。
本地还是云端：微软 AI Agent 入门课第 17 课与第 16 课的取舍
ai-agents-for-beginners 的第 16 课把 Agent 推上 Microsoft Foundry，第 17 课把它拉回单机。本文只对照两课示例代码里白纸黑字写明的三件事——要装什么依赖、缺哪个配置会崩、伸缩这一层写在哪里，并指出 README 片段与 notebook 实际代码对不上的两处。
微软 AI Agent 入门课第 15 课：browser-use 接入与任务描述
ai-agents-for-beginners 第 15 课把 Browser-Use、Playwright 和 CDP 串在一起跑浏览器自动化。这篇按仓库里的 15-browser-use/README.md 与 15-browser-user.ipynb，讲清它的接入链路、Agent 任务描述的写法、结构化抽取用的 Pydantic 模型，以及课程自己划出的边界和几处源内不一致。
仓库工程与课程选择
这个仓自己就带七个 skill 文件，微软怎么把工作流固化成文件值得单独看；skill 和 tool 是两回事，触发时机、承载内容、给谁用都不同。最后一篇对照两门 beginners 课都讲 Agent 时的深度差异与学习顺序。
.agents/skills/：微软 AI Agent 入门课怎么固化一套工作流
ai-agents-for-beginners 仓库里藏着一个 .agents/skills/ 目录，把「验证课程 notebook」「迁移到 Responses API」这类反复要讲的流程写成了文件。本文沿着 SKILL.md 的结构约定、frontmatter 里的触发写法、以及 references 子目录的分工走一遍，顺带指出仓库里两处对不上的地方。
skill 和 tool 是两回事：微软 AI Agent 入门课自己就给了两套
同一个课程仓里既有 .agents/skills/ 下的 SKILL.md，又有 04-tool-use 里的 @tool 装饰器，很多人把它们当成一件事的两种写法。本文按触发时机、承载内容、给谁用三个维度，把这两套东西在仓库里的原文依据摆开，并给出一条从你的处境倒推到选型的路径。
微软生成式 AI 入门课第 17 课 vs 微软 AI Agent 入门课第 1 课：深度差在哪
同一个作者组织的两门入门课都有一节讲 AI Agent，读者常纠结先读哪个、会不会白读。本文把 generative-ai-for-beginners 的 17-ai-agents 和 ai-agents-for-beginners 的 01-intro-to-ai-agents 两个 README 与代码目录摊开对照，落到定义写法、示例文件形态、客户端类名、包名与环境变量这些能核到的差别上，并按不同处境给出读的顺序。
课程跑完了，怎么把 Agent 真正用到工作里？
从 Agent 工程落地到组织级应用，站内有成体系的教程与学习路线。