mcp-for-beginners 实战指南：Microsoft Foundry Toolkit 基础与 AI Agent 构建（Module 1）

• 教程
• 文档
• 人工智能

本篇文章对应开源课程 mcp-for-beginners 中「Streamlining AI Workflows: Building an MCP Server with Microsoft Foundry Toolkit」工作坊的第一个模块，系统讲解 Microsoft Foundry Toolkit 扩展在 VS Code 中的安装、模型目录（Model Catalog）浏览、Playground 模型测试，以及用 Agent Builder 创建定制 AI Agent 的完整流程。读完本文，你将掌握一条从零开始搭建生成式 AI 开发环境、选型与对比模型、设计高质量系统提示词并交付可运行 Agent 的实战路径，为后续通过 Model Context Protocol（MCP）连接外部工具打下基础。

一、学习目标与模块定位

本模块是四段式工作坊的起点，官方标定的学习时长约为 15 分钟，难度为入门级，前置条件仅为安装 VS Code。完成本模块后，你应当具备以下能力：

• 安装并配置 VS Code 的 Microsoft Foundry Toolkit 扩展；
• 在 Model Catalog 中浏览模型并理解不同模型来源的差异；
• 使用 Playground 对模型进行实时测试与实验；
• 借助 Agent Builder 创建自定义 AI Agent；
• 对比不同供应商模型在同一提示词下的性能表现；
• 应用提示词工程（Prompt Engineering）最佳实践。

从整条学习路径看，工作坊总览 README 明确将本模块定位为「Microsoft Foundry Toolkit Fundamentals」，其产出目标是：在具备对 Microsoft Foundry Toolkit 各项能力的全面理解之上，创建一个可用的 AI Agent。后续 Module 2 将在此基础上把 Agent 接入 MCP 工具（如 Playwright 浏览器自动化），Module 3 与 Module 4 则进一步手写自定义 MCP 服务器，因此本模块的每一个基础操作都会在后续环节反复使用。

二、Microsoft Foundry Toolkit 是什么

Microsoft Foundry Toolkit（VS Code 扩展）是微软面向 VS Code 的旗舰级 AI 开发扩展，其目标是把 VS Code 变成一个完整的 AI 开发环境：它连接了 AI 研究与实际应用开发之间的鸿沟，让不同水平的开发者都能上手生成式 AI。

2.1 核心能力总览

2.2 为什么值得关注

• 加速开发：从想法到原型只需数分钟；
• 统一工作流：一个界面对接多个 AI 供应商；
• 便捷实验：无需复杂配置即可横向对比模型；
• 生产就绪：从原型到部署的过渡平滑。

需要说明的是，工作坊总览中同时点明了这套工具栈的另一半——Model Context Protocol（MCP），它被描述为「AI 的 USB-C」，用于统一 AI 与外部工具、数据源之间的连接。本模块先掌握扩展本身，MCP 的接入则从下一模块开始。

三、前置条件与安装

3.1 系统要求

工作坊总览给出了与本模块直接相关的环境基线：

3.2 安装 Microsoft Foundry Toolkit 扩展

第一步：进入扩展市场

1. 打开 Visual Studio Code；
2. 进入扩展视图（快捷键Ctrl+Shift+X，macOS 为Cmd+Shift+X）；
3. 搜索「Microsoft Foundry Toolkit」。

第二步：选择版本

• 🟢Release（正式版）：推荐用于生产环境；
• 🔶Pre-release（预发布版）：抢先体验最新功能，但稳定性相对较低。

第三步：安装并激活

点击 Install 完成安装后，侧边栏会出现 Microsoft Foundry Toolkit 图标。下面是扩展安装后的界面示意：

验证清单：

• VS Code 侧边栏出现 Microsoft Foundry Toolkit 图标；
• 扩展已启用并激活；
• 输出面板（Output Panel）无安装错误。

四、动手实验一：探索 Microsoft Foundry 模型

🎯 目标：掌握 Model Catalog，并完成第一个 AI 模型的测试。

4.1 第一步：浏览 Model Catalog

Model Catalog 是进入 AI 生态的入口，它聚合了多个供应商的模型，方便发现与对比。操作方式：在 Microsoft Foundry Toolkit 侧边栏中点击MODELS - Catalog。

提示：优先寻找与你使用场景匹配的模型能力标签（如代码生成、创意写作、数据分析等）。

[!NOTE] GitHub Models 已于 2026 年 7 月 30 日退役。请改用 Microsoft Foundry 模型部署，并使用 Microsoft Entra ID 或 Azure API 密钥进行身份认证。

4.2 第二步：添加并配置第一个模型

模型选型策略：

• GPT-5.1：推荐的通用模型，擅长工具调用与推理；
• Phi-4-mini：轻量、响应快，适合简单任务。

配置流程：

1. 在目录中选择OpenAI GPT-5.1；
2. 点击Add to My Models——该操作会注册模型以供使用；
3. 选择Try in Playground启动测试环境；
4. 等待模型初始化（首次使用可能需要一点时间）。

理解模型参数：

• Temperature（温度）：控制创造性，0为确定性输出，1为高创造性输出；
• Max Tokens（最大令牌数）：限制响应最大长度；
• Top-p：核采样（Nucleus Sampling）参数，控制响应多样性——模型只在累积概率达到p的最小 token 集合中采样，p越大候选词越多、输出越多样。

4.3 第三步：掌握 Playground 界面

Playground 是 AI 实验台。以下提示词工程最佳实践可直接套用：

1. 具体明确：清晰、详细的指令带来更高质量的结果；
2. 提供上下文：包含相关的背景信息；
3. 给出示例：用例子告诉模型你期望的输出形态；
4. 迭代优化：基于初步结果持续打磨提示词。

三个可直接复制的测试场景：

# 示例 1：代码生成 "Write a Python function that calculates the factorial of a number using recursion. Include error handling and docstrings." # 示例 2：创意写作 "Write a professional email to a client explaining a project delay, maintaining a positive tone while being transparent about challenges." # 示例 3：数据分析 "Analyze this sales data and provide insights: [paste your data]. Focus on trends, anomalies, and actionable recommendations."

4.4 挑战练习：跨模型性能对比

目标：用完全相同的提示词对比不同模型，理解各自优势。

步骤：

1. 将Phi-4-mini加入工作区；
2. 对 GPT-5.1 与 Phi-4-mini 使用同一条提示词；
3. 对比响应质量、速度与准确性；
4. 在结果区记录你的发现。

值得探索的关键洞察：

• LLM 与 SLM（小语言模型）分别在什么场景更合适；
• 成本与性能之间的权衡；
• 不同模型的专项能力差异。

五、动手实验二：用 Agent Builder 构建自定义 Agent

🎯 目标：创建面向特定任务与工作流的定制 AI Agent。

5.1 理解 Agent Builder

Agent Builder 是 Microsoft Foundry Toolkit 的亮点功能：它允许你将大语言模型的强大能力与自定义指令、特定参数和领域知识结合，创建「专用型」AI 助手。

Agent 架构组成：

• 核心模型（Core Model）：底层 LLM（如 GPT-5.1、Phi 系列）；
• 系统提示词（System Prompt）：定义 Agent 的人格与行为；
• 参数（Parameters）：为最优表现微调设置；
• 工具集成（Tools Integration）：连接外部 API 与 MCP 服务；
• 记忆（Memory）：对话上下文与会话持久化。

5.2 Agent 配置深入：系统提示词模板

创建有效系统提示词的结构模板：

# Template Structure: ## Role Definition You are a [specific role] with expertise in [domain]. ## Capabilities - List specific abilities - Define scope of knowledge - Clarify limitations ## Behavior Guidelines - Response style (formal, casual, technical) - Output format preferences - Error handling approach ## Examples Provide 2-3 examples of ideal interactions

当然，你也可以直接使用Generate System Prompt功能，让 AI 帮你生成并优化提示词。

参数优化建议表：

5.3 实战：构建 Python 编程 Agent

任务：创建一个专门的 Python 编码助手。

配置步骤：

1. 模型选择：选择Claude 3.5 Sonnet（代码能力出色）。

2. 系统提示词设计：

# Python Programming Expert Agent ## Role You are a senior Python developer with 10+ years of experience. You excel at writing clean, efficient, and well-documented Python code. ## Capabilities - Write production-ready Python code - Debug complex issues - Explain code concepts clearly - Suggest best practices and optimizations - Provide complete working examples ## Response Format - Always include docstrings - Add inline comments for complex logic - Suggest testing approaches - Mention relevant libraries when applicable ## Code Quality Standards - Follow PEP 8 style guidelines - Use type hints where appropriate - Handle exceptions gracefully - Write readable, maintainable code

3. 参数配置：

• Temperature：0.2（保证代码输出的一致性与可靠性）；
• Max Tokens：2000（容纳详细解释）；
• Top-p：0.9（保持均衡的创造性）。

5.4 测试你的 Python Agent

测试场景：

1. 基础函数：「Create a function to find prime numbers」；
2. 复杂算法：「Implement a binary search tree with insert, delete, and search methods」；
3. 真实问题：「Build a web scraper that handles rate limiting and retries」；
4. 调试任务：「Fix this code [paste buggy code]」。

成功标准：

• ✅ 代码可无错误运行；
• ✅ 包含完善的文档字符串；
• ✅ 遵循 Python 最佳实践；
• ✅ 提供清晰的解释；
• ✅ 能提出改进建议。

六、模块小结与后续衔接

6.1 知识自检

• 能否解释目录中不同模型之间的差异？
• 是否已成功创建并测试一个自定义 Agent？
• 是否理解如何针对不同场景优化参数？
• 能否设计有效的系统提示词？

6.2 通往 MCP：仓库中的源码佐证

本模块创建的 Agent 是后续一切能力扩展的载体。在仓库中，你可以找到与「Agent + 工具」这一演进方向直接对应的实现证据：

• lab2/code/agent.py 是一个纯 Python 实现的 MCP 客户端：它通过mcp的ClientSession、stdio_client/sse_client连接 MCP 服务器，再调用session.list_tools()拉取工具清单、session.call_tool()执行工具调用，并把工具以 OpenAI function calling 格式注入chat.completions.create的tools参数——这正是 Agent Builder 中「把 Agent 接到 Playwright 等 MCP 服务器」这一能力的底层形态；
• Module 2 会在本模块基础上，把 Agent 连接到外部工具（Playwright 浏览器自动化、文件操作、企业系统等）；
• Module 3 与 Module 4 则转向反向实现——从零构建自定义 MCP 服务器（Weather MCP Server、GitHub Clone Server），并配合 MCP Inspector 进行调试。

6.3 下一步

如果你已掌握 Microsoft Foundry Toolkit 的基础能力，可以继续进入Module 2: MCP with Microsoft Foundry Toolkit Fundamentals，学习：

• 使用 Model Context Protocol（MCP）将 Agent 连接到外部工具；
• 用 Playwright 构建浏览器自动化 Agent；
• 将 MCP 服务器集成进 Microsoft Foundry Toolkit Agent；
• 用外部数据与能力为 Agent 赋能。

至此，你已经完成 Microsoft Foundry Toolkit 的基础训练，具备继续构建更高级 AI 应用的能力。

• 教程
• 文档
• 人工智能