使用 GitHub Copilot 和 Microsoft Foundry 构建托管智能体
低代码智能体非常适合快速验证行为，但大多数团队最终需要对代码、部署和集成进行更强的控制。在本章中，我们将进入代码优先的工作流，并构建一个托管智能体，该智能体可以在本地开发、使用工具进行调试并部署到 Microsoft Foundry 中。
到最后，你将拥有一个实用的蓝图，用于从提示词构思过渡到面向生产的托管执行。
正是在这里，智能体开发开始变得像真正的工程设计。
这一流程的每个部分本身都很有用。当骨架搭建、调试、工具和部署全部连接成一个可重复的系统时，真正的魔力就会发生。
问题界定：代码优先的智能体可提高运营可靠性
本章最大的转变不仅仅是用代码代替提示词编写，而是转向具有运营可靠性的生命周期。在低代码模式下，行为可以快速验证，但部署形态、工具集成和调试深度往往受到限制。
在代码优先模式下，你将获得可重复性：同一个仓库定义了运行时行为、工具连接和部署流程。
一个仓库。单一事实来源。更少的意外。
了解其价值的一个简单方法是比较如何诊断问题。在代码优先的工作流中，可以一起审查跟踪、配置和源代码更改，这通常会在托管环境中的行为发生漂移时缩短修复时间。
前提条件
在开始之前，请确保你的环境能够同时支持本地调试和托管部署。本章结合了 GitHub Copilot CLI、Foundry Toolkit 和 Azure 部署资产，因此缺少设置通常会在中途拖慢进度。
如果你首先验证了这些先决条件，那么本章的其余部分将专注于智能体工程，而不是环境故障排除。
- 编辑器和扩展：安装了 Foundry Toolkit 的 Visual Studio Code。
- GitHub Copilot 访问权限：在 Visual Studio Code 和终端工作流中可用的 GitHub Copilot。
- 云上下文：Azure 订阅和 Microsoft Foundry 项目。
- 模型部署：项目中已部署的 GPT-5 模型实例。
- CLI 准备就绪：Azure Developer CLI 以及登录 Azure 的能力。
你将学到什么
在本章中，你将为面向开发人员的内容创作创建一个基于代码的社交活动助手。与仅包含提示词的原型不同，此版本经过版本控制、可检查，并且可以作为托管智能体进行部署。
可以将其视为实验与生产就绪的团队工作流之间的桥梁。
你将学习如何
- 搭建智能体项目骨架：使用 GitHub Copilot CLI 提示词生成带代码的项目。
- 附加可重用工具：使用 Microsoft Learn MCP 和网络搜索配置 Foundry 工具箱。
- 运行本地运行时循环：使用基于 HTTP 的本地智能体服务进行调用和调试循环。
- 部署到托管目标：发布到 Foundry 中的托管智能体。
在我们动手操作之前，先明确团队选择此模型的实际原因会很有帮助。
为什么要转向基于代码的智能体
当团队需要比低代码生成器所能提供的更深层次的控制时，他们会选择基于代码的智能体。这通常包括特定于业务的逻辑、确定性配置文件、可重复的部署以及与应用程序代码的直接集成。
换句话说，基于代码的智能体并不是为了复杂性而复杂性。它们关乎控制力、可靠性和团队规模的可维护性。
如果你曾问过“如何确保此智能体在不同环境中具有可预测性？”，这就是回答该问题的工作流。
- 控制：在版本控制中对提示词、运行时设置和依赖项进行版本管理。
- 可扩展性：添加自定义逻辑和更丰富的工具编排模式。
- 可重复性：通过配置和基础设施文件重现环境。
- 生产契合度：通过托管智能体生命周期进行部署和运维。
第 1 步：使用 GitHub Copilot CLI 搭建解决方案骨架
首先在终端中启动 GitHub Copilot CLI，并用自然语言描述目标解决方案。在本章中，脚手架提示词包括活动助手行为、澄清问题行为、检索工具、GPT-5 模型使用以及托管可部署性。
以下是我们首先需要考虑的事情。
- 提示词：描述行为、工具、模型和部署意图。
- GitHub Copilot CLI：允许 GitHub Copilot 以较少的干扰执行多步骤设置。为此，请使用自动驾驶（Autopilot）模式。
让我们一步步了解如何搭建新智能体项目骨架
-
在你的工作文件夹中打开终端。
-
在该文件夹中启动 GitHub Copilot CLI。运行
copilot。 -
启用自动驾驶模式（/autopilot on），以便设置能够以较少的干扰运行。
-
确认你看到了消息 已启用具有所有权限的自动驾驶模式。
-
输入描述智能体行为、工具和部署意图的自然语言提示词。
使用示例图片中的此提示词
Create a Foundry agent solution for a developer social media campaign assistant promoting developer productivity tools. The agent should ask clarifying questions, use data retrieval tools to extract the right context for the campaign and generate social post options. The agent should be configured to use a Foundry toolbox, including the MS MCP Learn server to retrieve Microsoft official documentation and the web search tool to access fresh data. It should be deployable as a hosted agent. Use a gpt-5 model instance. Open project folder when done. -
确认生成的文件已创建在指定的项目位置。
请参阅下面的示例提示词
图 01：GitHub Copilot CLI 脚手架提示词和生成的项目输出。
此时，你的磁盘上应该已经有一个项目骨架。接下来，让我们来看看生成了什么，并确认它是否符合你的意图。
第 2 步：检查 GitHub Copilot 生成的内容
让我们来看看生成了什么。以下是你预计会在项目文件夹中看到的内容
- 主运行时：
main.py包含核心助手逻辑和运行时连接。 - 智能体配置：
agent.yaml定义了行为、托管、协议和运行时设置。 - 工具配置：
toolbox.yaml描述了连接的工具和工具终结点。 - 部署配置：
azure.yaml和infra/Bicep 模板驱动预配和部署。
如果此处任何文件的角色看起来不明确，请在部署前停下来解决它。一旦涉及到云资源，此步骤中的模糊不清通常会带来高昂的代价。
第 3 步：验证工具的创建和设置
既然你已经从宏观上了解了搭建好的骨架，接下来让我们深入探讨作为骨架设置一部分而配置的工具。
在你打开的项目中，打开 toolbox.yaml 文件并确认至少创建了两个工具：一个用于 Microsoft Learn MCP，另一个用于网络搜索。
以下是它们为我们所做的事情
- 网络搜索：检索有关时间敏感或热门信息的当前网页上下文。
- Microsoft Learn MCP：检索受信任的产品事实和文档上下文。
请参见下方这些工具是如何配置的
图 02：Foundry 工具箱配置。
附加工具后，花一分钟时间阅读生成的资产，以便在执行任何操作之前预测其行为。
第 4 步：在本地运行和调用智能体
在部署之前，通过基于终端的命令验证本地行为。这为你提供了快速的反馈循环，并在涉及云资源之前捕获指令或运行时问题。
在本章流程中，本地调用确认了预期的澄清问题行为。
-
从项目根目录运行
azd ai agent run。此命令安装所需的依赖项，启动本地运行时，并将智能体作为 HTTP 服务提供。
-
等待本地运行时报告其已就绪，然后打开新终端来调用智能体。
-
在单独的终端中使用
azd ai agent invoke和切合实际的活动提示词运行智能体。你应该会看到类似于以下内容的结果
图 03：本地智能体运行和提示词调用。
第 5 步：配置 Agent Inspector 集成
为了进行深入检查和故障排除，请为 Agent Inspector 配置项目。本章流程使用 GitHub Copilot 来验证 HTTP 服务要求、安装依赖项并准备 Visual Studio Code 调试配置。
正是在这里，你的项目变得易于反复调试，而不仅仅是只能运行一次。
-
通过在 GitHub Copilot Chat 中运行一个提示词来设置检查器，该提示词描述了如何将本地智能体连接到检查器。
请参阅下面的图片，简而言之，你需要告诉它安装工具并为 Visual Studio Code 配置 tasks.json 和 launch.json。
一旦检查器连接到位，你就可以直接评估因果关系，而不必从最终输出文本中进行猜测。
第 6 步：使用 Agent Inspector 进行调试
现在是运行检查器的时候了
开始调试并打开 Agent Inspector 以观察实时的运行时行为。这使你能够直接查看事件、流式增量、元数据、跟踪和工具调用。
你应该会看到一个可以与之交互的游乐场以及右侧的跟踪。你看到的内容应该与下图类似。
图 04：带有事件时间线和跟踪视图的 Agent Inspector 调试会话。
正是在这里，智能体开发从黑盒猜测转变为了可检查的工程。
在测试提示词时，请观察事件时间线和跟踪视图，以确认响应正在按预期进行，而没有静默跳过检索逻辑。
- 事件时间线：检查响应生命周期状态和 Token 进度。
- 工具可见性：审查每个工具调用的输入、输出和调用原因。
- 跟踪分析：使用跟踪视图快速诊断行为分歧。
- 迭代循环：提示、检查、精炼指令并重新测试。
提示 (TIP)：在完成一次干净的跟踪后，强制输入一个如果没有检索就无法很好回答的提示词，以便对工具连接进行真正的压力测试。
第 7 步：通过后续提示词确认检索行为
此时，智能体已启动并向你提出后续问题。现在我们要回复一些内容，同时确保智能体确实在使用我们配置的检索工具。
键入如下提示词
Highlight the mobile chat feature, drive installs, general dev audience, technical tone, #github copilot
现在你应该会看到工具被调用并生成了如下响应
图 05：带有工具调用和结构化输出的后续提示词响应。
第 8 步：部署为托管智能体
接下来，将智能体部署到托管环境。此步骤使用你刚刚在本地调试过的相同项目资产，因此你可以确信行为将保持一致。
-
单击右上角 Agent Inspector 中的“Deploy”按钮。
你应该会看到以下屏幕
图 06：通过 Agent Inspector 部署。
-
单击“下一步 (Next)”。
-
在“Review and Deploy”中，选择“Select Existing Dockerfile”并在计算机中找到它。最后单击“Deploy”以开始部署过程。
快速提问
如果本地 runs 看起来正确，但托管响应发生漂移，你应该首先检查什么：提示词措辞、工具调用还是运行时/部署配置？
回答
从运行时和部署配置以及工具调用跟踪开始，然后重新审视提示词措辞。托管漂移通常来自仅凭提示词文本无法察觉的环境或集成差异。一旦确认了运行时的一致性，提示词的精炼就会变得更加可靠。
下一步计划
在发布托管的基于代码的智能体之后，下一步是强化持续发布的生命周期。随着智能体范围的扩大，重点应放在更强的评估管道、由跟踪驱动的调试实践以及用于部署和回归检查的自动化上。
下一章应该让人感觉是对这个工作流的延伸，而不是重置。
你的挑战
既然你已经看到了完整的托管流程，请自己尝试一个小型生产风格的练习。其目标是证明你可以从骨架搭建过渡到可重复的验证，而无需猜测。使用此检查清单作为你的行动计划。
- 使用 GitHub Copilot CLI 为不同的场景搭建一个新的托管智能体骨架。
- 至少添加一个基础工具以及关于必须使用它的时机的指令规则。
- 使用至少两个强制使用工具的提示词在本地验证行为。
- 部署智能体并将一个本地跟踪与一个托管跟踪进行比较。
- 记录一个行为差异以及你所应用的修复方案。
成功目标：你可以解释从提示词输入到托管输出的完整路径，并为每个阶段出示证据。
了解更多
如果你想在本章之后进行更深入的学习，最好的路径是将平台指南与托管智能体部署参考结合起来。这为你提供了生产上下文以及接下来该做什么的实用后续步骤。使用以下链接作为实际的延续路径。
- Visual Studio Code 中的 GitHub Copilot：在 Visual Studio Code 文档中查看 Copilot 工作流。
- Azure AI Foundry 概述：了解更广泛的 Azure AI Foundry 平台和工作流。
- Azure AI 智能体概述：查看托管智能体概念和生命周期指导。
- Azure Developer CLI 文档：使用 azd 进行可重复的设置和部署工作流。