文档中心

Appearance

控制台

构建使用公开文档 MCP 的技术文档助手 ​

本实战将 Microsoft Learn 的公开文档 MCP Server 接入智能体开发服务平台（AgentWorks），构建一个先搜索、再读取官方页面并附上来源链接的技术文档助手。基础路径用于检查正常查询、页面不存在和连接恢复；进阶路径再加入 Todo 和受管文件系统，让智能体规划研究步骤、生成 Markdown 简报并复核文件内容。你可以在 Playground 查看回答和工具调用，并在 Trace 有记录时核对调用顺序。

Microsoft Learn MCP Server 是 AgentWorks 外部的公共服务。本实战不需要配置认证 Header，只处理公开、非敏感问题。服务不可用、页面调整或限流时，搜索结果和回答可能变化；遇到这类情况时，先检查 Microsoft Learn 的可用性和使用限制，再决定是否重试。

准备条件和测试资源 ​

开始前需要：

  • 一个可以正常回复的模型凭证和模型。尚未完成验证时，先运行创建第一个智能体并完成基础验证。
  • 创建 MCP 模板、MCP 实例、智能体模板和智能体实例，以及编辑这些测试资源的权限。
  • 租户已经启用 MCP，且平台网络可以访问 https://learn.microsoft.com/api/mcp。
  • 一组只用于本实战的测试资源。不要修改由其他智能体或生产流程引用的 MCP 实例。

本文使用以下名称，便于识别配置关系：

资源名称
MCP 模板recipe-mslearn-docs-mcp-template-v1
MCP 实例recipe-mslearn-docs-mcp-v1
智能体模板recipe-mslearn-docs-assistant-v1
智能体实例recipe-mslearn-docs-assistant-test-v1

如果环境中已经存在同名资源，请为四个名称统一追加简短后缀，例如 -team-a，以免覆盖、修改或复用来源不明的资源。

MCP 工具调用会把文档搜索词和请求读取的 URL 发送给 Microsoft，返回的文档内容会进入 AgentWorks 的模型上下文，并可能显示在 Trace 中。因此，只使用公开、非敏感问题完成测试，不要提交密钥、个人信息、客户资料、租户标识或内部故障信息。

创建 Microsoft Learn MCP 模板和实例 ​

先用 MCP 模板保存固定连接配置，再从模板创建独立实例并确认工具列表。这样可以复用同一连接配置，而不必在创建实例时重复填写参数。

创建 MCP 模板 ​

  1. 从左侧导航进入 MCP 管理，选择 MCP 模板，再选择 新建 MCP 模板。
  2. 将 名称 设为 recipe-mslearn-docs-mcp-template-v1，在 描述 中填写 Microsoft Learn 公开文档 MCP。
  3. 将 Server URL 设为 https://learn.microsoft.com/api/mcp。
  4. 保持 超时时间: 为页面默认值。
  5. 保持 跳过 TLS 校验 关闭，并保持 Headers 为空。
  6. 本实战使用固定地址且不需要认证，不把 URL 路径参数 或 Headers 标记为 可配置。
  7. 选择 创建 MCP 模板。

从模板创建 MCP 实例 ​

  1. 从左侧导航进入 MCP 管理，打开刚创建的 recipe-mslearn-docs-mcp-template-v1 模板详情。
  2. 要继承本实战的模板，请在模板详情页选择 创建实例。MCP 实例列表中的 新建 会直接创建独立实例，不会继承该模板。
  3. 将 实例名称 设为 recipe-mslearn-docs-mcp-v1，然后创建实例。本模板没有开放可配置参数，因此创建表单不需要重新填写 Server URL、Headers 或超时。
  4. 创建后打开 MCP 实例概览，确认它继承的地址为 https://learn.microsoft.com/api/mcp、Headers 为空、正常执行 TLS 校验，并使用模板的默认超时。继承值不符时停止，不要继续创建智能体；返回模板修正配置后重新创建本实战实例。
  5. 在 MCP 实例中选择 测试连接。成功提示可能只短暂显示；确认结果后选择 工具 页签。
  6. 确认 工具列表包含以下三个名称：
    • microsoft_docs_search
    • microsoft_docs_fetch
    • microsoft_code_sample_search

如果连接失败、工具列表为空或名称不同，请停止创建智能体，先检查地址、平台网络、TLS 和外部服务状态。不要通过关闭 TLS 校验来绕过证书问题，也不要根据本文猜测新的工具名称。

检查点 1：测试连接 成功，工具列表 显示三个预期工具。

创建技术文档助手 ​

  1. 打开 智能体模板，选择 创建智能体模板。

  2. 将 模板名称 设为 recipe-mslearn-docs-assistant-v1，并选择已经验证的 模型凭证和 模型。

  3. 在 系统提示词 中输入：

    language-text
    你是 Microsoft 技术文档助手。
回答 Microsoft 产品问题时，先搜索 Microsoft Learn，再读取最相关的官方页面。
只根据实际读取到的页面回答，并在答案中给出该官方页面链接。
页面读取失败或资料没有答案时，明确说明失败或资料不足，不要编造内容。
在当前智能体中直接完成搜索和读取，不要启动异步任务、子代理或后台任务。

  4. 关闭默认开启的 启用文件系统。保持 启用待办列表 和上下文压缩关闭，并暂时保持 插件配置 为空。在 工具权限 中暂不添加允许或拒绝规则。无规则时不会启用工具人工确认；页面显示的 审批（有规则时的默认） 只有在添加规则后才作为默认行为生效。

  5. 选择 创建智能体模板。

  6. 创建名为 recipe-mslearn-docs-assistant-test-v1 的智能体实例，等待状态变为 运行中。

  7. 在新会话中发送 请只回复 DOCS_ASSISTANT_MODEL_OK，不要调用工具。，确认智能体返回固定文字，且 Trace 中没有 MCP 工具调用。

这一步先确认模型可以正常回复。没有返回固定文字时，先检查模型和模型凭证；暂时不要改动 MCP 地址或工具权限。

检查点 2：新建模板时观察到文件系统默认开启、Todo 和上下文压缩默认关闭；关闭文件系统后创建的智能体实例可以正常回复，并且尚未调用 MCP 工具。

让现有实例加载 MCP 工具 ​

要让已有智能体实例使用 MCP 工具，请先把 MCP 实例关联到智能体模板，再同步已有实例。连接测试用于检查服务连接和工具发现，不会自动更新正在运行的智能体实例。

  1. 编辑 recipe-mslearn-docs-assistant-v1，在 插件配置 中选择 添加插件，添加 MCP - 实例，再选择 recipe-mslearn-docs-mcp-v1。

  2. 在 工具权限 中分别添加三条允许规则。每条规则只填写以下一个完整工具名称，不填写参数名或匹配正则：

    • microsoft_docs_search
    • microsoft_docs_fetch
    • microsoft_code_sample_search

  3. 将 默认行为设为 拒绝。这样三个明确列出的 Microsoft Learn 工具可以自动执行，其他未匹配的可审批工具会被拒绝。

  4. 选择 保存修改，并检查现有实例是否显示 智能体模板更新，实例需手动更新。

  5. 在智能体模板详情页执行重启操作。

  6. 打开 recipe-mslearn-docs-assistant-test-v1，选择 编辑。

  7. 核对实例参数仍与保存前一致，选择 保存修改。

  8. 等待实例重新变为 运行中，并确认不再显示模板更新提示。无论是否出现过该提示，都继续运行下一节的真实工具调用。

  9. 如需刷新工具列表，请刷新 MCP 实例页面，或者离开后重新进入 工具 页签，再在 工具列表 中确认三个工具仍然存在。

工具允许规则控制智能体是否可以执行已发现的调用。接入需要认证或可以修改数据的 MCP Server 时，还要配置最小权限凭证、服务端授权和相应的确认流程。

部分运行维护类内置工具始终自动通过，不受默认拒绝规则控制。因此，本页的测试问题会明确要求不要调用 start_async_task，不要启动子代理或后台任务。完整边界参见配置工具审批流程。

采用最新配置需要完成模板重启、实例编辑并保存，最后运行一次真实工具调用；仅再次保存智能体模板不会更新已有实例。

检查点 3：智能体模板只关联预期 MCP 实例，三个允许规则名称准确，默认行为为 拒绝；测试实例重新处于 运行中，并且已经手动保存以采用最新配置。

运行正常和失败用例 ​

每个用例使用 Playground 的一个新会话，避免上一条消息或工具结果影响本次判断。测试时只记录工具名称、调用顺序、结果状态和来源链接，不要粘贴工具返回全文、会话 ID 或其他运行标识。

验证搜索、读取和来源链接 ​

在测试实例的 Playground 中发送：

language-text
请直接在当前智能体中完成，不要调用 start_async_task，不要启动子代理或后台任务。
请先使用 microsoft_docs_search 搜索 Microsoft Learn，再使用 microsoft_docs_fetch
读取一个最相关的官方页面。然后说明 Azure Resource Manager 是什么、可以帮助我
管理什么，并给出你实际读取的官方页面链接。

回答不需要逐字固定。通过条件是：

  1. Trace 先显示 microsoft_docs_search，再显示 microsoft_docs_fetch。
  2. 读取的 URL 来自 Microsoft Learn 搜索路径，工具结果与问题相关。
  3. 最终回答只概括读取到的资料，并包含实际读取的官方页面链接。
  4. 没有调用 start_async_task，也没有启动子代理或后台任务。

搜索排名和页面内容可能变化，因此以工具调用顺序、来源域名和回答是否基于已读取页面为准，不要求固定页面、返回顺序或逐字相同的答案。

验证不存在的固定页面 ​

在新会话中发送：

language-text
请直接在当前智能体中完成，不要调用 start_async_task，不要启动子代理或后台任务。
请读取这个固定页面并概括内容：
https://learn.microsoft.com/en-us/agentworks-docs-assistant-not-found
如果页面不存在或读取失败，请明确说明失败，不要搜索替代页面，也不要编造内容。

Trace 应显示对该固定地址的 microsoft_docs_fetch 读取尝试和“无法获取”结果，最终回答应明确说明无法读取页面。回答不得声称该页面包含具体内容，也不得用另一个页面代替本次失败结果。

检查点 4：正常用例完成搜索、读取和带链接回答；不存在页面用例清楚说明失败且没有编造内容。

演练连接失败和恢复 ​

只在本实战专用的 MCP 实例上执行本节。修改共享或生产 MCP 实例可能同时中断其他智能体；无法确认引用范围时，跳过故障演练。

  1. 记录当前正确地址 https://learn.microsoft.com/api/mcp。
  2. 编辑 recipe-mslearn-docs-mcp-v1，只把 Server URL 改为 https://learn.microsoft.com/api/mcp/agentworks-docs-assistant-invalid，其他字段保持不变。
  3. 选择 测试连接，确认连接失败。不要用反复重试或并发请求测试外部服务的限流。如果无效地址意外通过，立即恢复正确地址并停止本次演练；不要临时构造其他故障。
  4. 立即把 Server URL 恢复为 https://learn.microsoft.com/api/mcp，保存后重新选择 测试连接。恢复后的测试仍失败时，保留正确地址并停止；先检查平台网络和外部服务状态，不要继续重启智能体或重复正常用例。
  5. 刷新页面或重新进入 工具 页签，在 工具列表 中确认三个预期工具已经重新发现。工具仍缺失时停止；先恢复工具发现，不要继续用智能体回答判断连接是否已经恢复。
  6. 在智能体模板详情页执行重启操作，再编辑测试智能体实例并选择 保存修改。等待实例恢复为 运行中。
  7. 使用 Playground 的新会话重新运行正常用例，确认搜索、读取和带来源链接的回答再次通过。

完成恢复需要同时确认工具已经重新发现、模板已经重启、实例已经手动保存，并且正常用例复测通过。

检查点 5：无效地址使连接测试明确失败；恢复正确地址并重新同步实例后，正常用例再次通过。

使用 Todo 和文件系统生成研究简报 ​

完成基础助手后，可以复用 Microsoft Learn MCP 实例，再加入 Todo 和受管文件系统，让同一个智能体依次规划、检索、撰写并复核研究简报。

本节只在同一任务中使用 Todo 管理步骤，并用受管文件系统保存工作文件。需要跨会话、实例重启或资源回收保留产物时，请在流程结束前把最终内容写入持久化系统。

创建研究简报智能体 ​

为了保留基础助手用于后续检查，新建一个智能体模板和实例，但继续复用 recipe-mslearn-docs-mcp-v1：

资源名称
研究简报智能体模板recipe-mslearn-report-assistant-v1
研究简报智能体实例recipe-mslearn-report-assistant-test-v1

  1. 新建 recipe-mslearn-report-assistant-v1，选择与基础助手相同的模型凭证和模型。

  2. 在 系统提示词 中输入：

    language-text
    你是 Microsoft 技术研究助手，只处理公开、非敏感的 Microsoft 产品问题。
处理研究简报时，先用 write_todos 建立并更新搜索资料、读取原文、撰写简报和复核文件四项计划。
先调用 microsoft_docs_search，再调用 microsoft_docs_fetch 读取最相关的官方页面。
只根据实际读取到的内容撰写 Markdown 简报，并包含标题、摘要、三个要点和实际读取的官方页面链接。
使用 write_file 将简报写入 /reports/azure-resource-manager-brief.md，再使用 read_file 复核内容。
页面读取失败时，明确说明失败，不要搜索替代页面，不要编造内容，也不要写入声称成功的简报。
在当前智能体中直接完成，不要启动异步任务、子代理或后台任务。

  3. 在 插件配置 中添加 MCP - 实例，选择 recipe-mslearn-docs-mcp-v1。

  4. 保持 启用文件系统开启，并保持 只读模式关闭，使智能体可以写入和复核简报。

  5. 开启 启用待办列表。如果页面显示 增强描述注入，保持开启，让模型获得更完整的待办列表使用说明。

  6. 保持上下文压缩关闭，让本节只演示一条固定研究任务。需要处理长对话时，可以在完成本实战后单独评估上下文压缩。

  7. 在 工具权限 中只添加以下三条允许规则，并把 默认行为设为 拒绝：

    • microsoft_docs_search
    • microsoft_docs_fetch
    • write_file

    本节不使用代码样例，因此不为 microsoft_code_sample_search 添加允许规则。write_todos 和只读文件工具 read_file 属于始终自动通过的内置工具，不需要重复添加允许规则。

  8. 创建模板，再创建 recipe-mslearn-report-assistant-test-v1。等待实例进入 运行中。

  9. 在新会话中发送 请只回复 DOCS_REPORT_MODEL_OK，不要调用任何工具。。确认只返回固定文字，并且没有工具卡片；模型回复检查失败时停止，不要继续排查 MCP 或文件系统。

检查点 6：研究简报模板只复用预期 MCP 实例，Todo 和可写文件系统已开启，允许规则只有搜索、读取和 write_file，默认行为为拒绝；模型回复检查没有调用工具。

生成并复核简报 ​

在 Playground 的新会话中发送：

language-text
请直接在当前智能体中完成，不要调用 start_async_task，不要启动子代理或后台任务。
请先用 write_todos 建立并跟踪四项计划：搜索资料、读取原文、撰写简报、复核文件。
然后使用 microsoft_docs_search 搜索 Microsoft Learn，再使用 microsoft_docs_fetch 读取最相关的官方页面。
根据实际读取到的资料，写一份中文 Markdown 简报，说明 Azure Resource Manager 是什么、可以帮助我管理什么，并列出三个要点和实际读取的官方页面链接。
必须使用 write_file 将简报写入 /reports/azure-resource-manager-brief.md，再使用 read_file 复核文件内容。
最后告诉我文件路径、简短摘要和实际来源链接。

回答措辞和搜索排序可能变化。通过条件是：

  1. Playground 的工具卡片显示 write_todos 建立并更新计划。
  2. microsoft_docs_search 先于 microsoft_docs_fetch，并且读取的是相关 Microsoft Learn 官方页面。
  3. write_file 先把简报写入 /reports/azure-resource-manager-brief.md，read_file 再成功读取该文件。
  4. 最终回答给出文件路径、简短摘要和至少一个实际读取的官方页面链接。来源列表只收录实际通过 microsoft_docs_fetch 读取的页面；不要把仅出现在搜索结果中的补充链接列为已读取来源。
  5. 没有调用 start_async_task，也没有启动子代理或后台任务。

判断本节是否成功时，以 Playground 中可见的工具卡片和文件回读为准。Trace 有对应记录时，可以补充核对调用顺序；Trace 暂无数据不会阻塞本节，只需确认上述可见结果。

验证页面读取失败时不写入简报 ​

在新会话中发送：

language-text
请直接在当前智能体中完成，不要调用 start_async_task，不要启动子代理或后台任务。
请先用 write_todos 建立并跟踪两项计划：读取指定页面、报告结果。
只调用 microsoft_docs_fetch 读取以下精确 URL，不要搜索替代页面：
https://learn.microsoft.com/en-us/agentworks-report-not-found
如果读取失败，必须明确说明无法读取；不要编造内容，不要调用 write_file，不要声称已生成报告。最后更新 Todo 并说明是否写入文件。

通过条件是 Playground 显示 write_todos 和对固定 URL 的 microsoft_docs_fetch 尝试，不显示 write_file 调用；最终回答明确说明页面无法读取、没有生成简报且没有写入文件。

随后再开启一个新会话，重复上一节的正常简报问题。正常流程再次完成时，说明智能体实例已经恢复并可以处理新任务。跨会话文件保留不在本节的检查范围内。

检查点 7：正常路径完成 Todo、搜索、读取、文件写入和回读；固定失败路径明确说明读取失败且没有写入简报；新会话中的正常复测再次通过。

将这个模式调整为其他研究任务时，为每种文件类型定义固定路径、内容结构、来源要求和失败时的处理方式。需要长期保存、下载、共享或审计产物时，把最终内容写入经过批准的持久化系统；不要把本节的受管工作文件当作对象存储、沙箱文件或长期档案。

调整为自己的文档服务 ​

将本实战替换为其他文档 MCP Server 时，先确认连接方式、工具名称和读写范围：

  • 需要认证：使用服务方要求的最小权限 Header，并按照团队凭证策略保存和轮换；不要把凭证放入系统提示词、用户问题或截图。
  • 工具名称不同：先进入 MCP 实例的 工具 页签，从 工具列表 复制实际名称，再更新允许规则和固定测试，不能沿用 Microsoft Learn 的名称。
  • 内容不完全公开：确认最终用户身份、服务端授权、数据驻留、日志和工具结果返回范围。工具权限不能代替这些控制。
  • 服务包含写操作：不要使用本实战的自动允许规则。为写操作增加服务端权限、幂等、审计和人工确认，并分别验证批准与拒绝。
  • 地址或工具定义发生变化：先在专用测试资源上完成连接、工具发现、实例同步、正常用例和失败用例，再更新生产引用。

准备上线和后续检查 ​

上线前，为外部服务可用性、超时和限流建立监控与失败提示，记录 MCP 地址、工具名称、智能体模板配置和用于验证的固定问题，并在每次模型、提示词、MCP 或工具定义变化后重新运行本页用例。参见验证智能体实例和将智能体投入生产。

完成验证后，可以保留本实战的专用测试资源，用于上线前检查或后续定期复测。记录负责人、保留用途和下次复查时间，并保持资源只服务于已记录的测试范围。如果后续改变或处置这些资源，先核对当前引用和团队的资源生命周期策略，不要影响共享模型、模型凭证或其他智能体。