你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
使用 Microsoft Foundry Toolkit for Visual Studio Code 从 Microsoft Agent Framework 示例创建基于代码的工作流。 使用代理检查器在本地运行它，然后将其源代码作为托管代理部署到 Foundry 代理服务。 你负责维护代码及其依赖项。 Foundry 负责托管基础设施和扩缩容。
托管工作流在代码中协调代理。 它们不同于即将停用的 Foundry 声明性工作流服务。 有关其他创建路由，请参阅 “创建代理”。
先决条件
选择具有已部署模型的 Foundry 项目。 使用 受支持的托管代理区域。
使用模型和部署托管代理的权限。 对于源代码部署，在项目范围内，Foundry Project Manager 角色包含代理操作和角色分配权限。 请参阅 托管代理权限。
重要
Foundry RBAC 角色最近已更名。 Foundry 用户、Foundry 所有者、Foundry 帐户所有者和 Foundry 项目经理之前的名称分别为“Azure AI 用户”、“Azure AI 所有者”、“Azure AI 帐户所有者”和“Azure AI 项目经理”。 在重命名推出时，你仍可能会在某些位置看到以前的名称。重命名后，角色 ID 和核心权限保持不变。
使用 Azure CLI 执行本文中的本地身份验证步骤。
对于容器部署，请提供Azure 容器注册表设置所需的注册表和映像访问权限。 这些注册表要求不适用于源代码部署。
- 用于示例配置的托管运行时的 Python 3.13。
- 用于Visual Studio Code的 Python 扩展。
- .NET 10 SDK。
- 适用于 Visual Studio Code 的 C# 开发工具包。
主部署路径使用具有远程包模式的代码，并且不需要本地 Docker 生成。 本地执行仍向 Foundry 发送模型请求，并会产生费用。 查看服务限制和可用性以及工具包发行说明，了解你使用的功能。
创建托管代理工作流
选择使用响应协议的代理框架示例。 无需首先创建单独的提示代理。 若要比较示例、代理生成器和Copilot辅助编码，请参阅“选择创建路由”。
使用 多代理工作流（代理框架），它将编写器、审阅者和格式化程序链接在一起。 最终响应来自格式器。 查看Python工作流示例，了解完整的实现及其模型指南。
使用 翻译工作流，将三个翻译代理链接在一起：英语到法语、法语到西班牙语和西班牙语到英语。 查看 C# 工作流示例 以获取完整的实现。
在 Foundry 工具包 视图中，选择 “开发人员工具>生成>创建代理”。
在 “对示例中的代理进行编码”下，选择“ 浏览所有示例”。
在 “从示例创建托管代理”中，按 语言、 框架 = 代理框架和 协议类型 = 响应进行筛选。 搜索
workflow。以下屏幕截图显示了库，并选择基本托管智能体作为示例。 在本指南中，请改为选择对应你所用语言的工作流示例。
选择语言的工作流示例。
选择“下一步”。
在 “创建”上，选择 “工作区文件夹”。 如果该文件夹已包含文件，请输入新建子文件夹的文件夹名称。
如果出现“环境设置”，请选择“使用 Microsoft Foundry 设置”，然后选择你的订阅和项目。 选择默认项目后，窗体将使用该项目。
选择现有的兼容 模型部署。
以下屏幕截图显示了隐藏了本地路径的示例项目设置。 请使用您自己的目标终结点以及示例所需的模型部署。
查看目标，然后选择“ 创建”。
在 Visual Studio Code 中打开生成的项目并阅读其
README.md。
创建代理中的 Agent Framework、Copilot SDK 和 LangGraph 卡片会打开 创建 选项卡，并选中 hello-world 入门模板。 使用 浏览所有示例 来选择工作流，而不是其中一个入门模板。 还可以从我的资源>代理>托管代理>添加托管代理打开库。
示例名称和内容可能会因目录而异。 某些版本会标记这些示例 工作流。 使用示例的GitHub链接确认你选择了预期的工作流。
跳过现在 会生成代码，而无需完成模型设置。 如果选择它，请在运行示例之前配置所需的项目和模型值。 部署并使用新模型（若提供此选项）会预配模型部署资源，而不是托管代理。 创建本地项目文件不会部署代理。
配置本地项目
将包含 azure.yaml 的文件夹作为工作区根目录保持打开。 检查该文件中的托管代理服务 project 的路径以查找其源目录。
| 工件 | Purpose |
|---|---|
azure.yaml |
声明托管代理服务、源目录、运行时、协议和部署设置。 |
源目录中的 main.py 或 Program.cs |
实现工作流并启动其响应服务器。 |
requirements.txt 或 .csproj 文件 |
声明所选语言的依赖项。 |
.env 位于源目录中 |
保存本地项目和模型值。 当示例提供该文件时，工具包会从 .env.example 中创建该文件。 |
.vscode/launch.json 和 .vscode/tasks.json |
配置本地服务器、调试器附件和代理检查器。 |
示例布局可能会更改。 使用生成的 README.md ， azure.yaml 而不是假设代码和环境文件位于工作区根目录中。
安装依赖项
使用已生成示例的依赖文件。 使所选解释器或 SDK 与其运行时配置保持一致。
运行Python：从命令面板创建环境...以创建虚拟环境，或Python：选择解释器以选择现有Python 3.13 环境。 有关环境设置和选择，请参阅Visual Studio Code中的Python环境。
打开一个已激活该环境的终端。 更改为包含
main.py和requirements.txt. 的源目录。安装示例项目的依赖包：
python -m pip install -r requirements.txt这些要求包括
debugpy，生成的 F5 配置会使用其中的内容。 参考：Python工作流依赖项。
运行 C#：从命令面板检查工作区要求 。
在终端中，更改为包含
.csproj文件的源目录并还原其包：dotnet restore参考： dotnet restore。
有关调试器控件和配置，请参阅Visual Studio Code中的 C# 调试。
设置项目和模型
检查源目录中的 .env 文件。 如果不存在，请使用示例所需的值创建它。
| Variable | 值 |
|---|---|
FOUNDRY_PROJECT_ENDPOINT |
您的项目端点，格式为 https://<resource-name>.services.ai.azure.com/api/projects/<project-name>。 |
AZURE_AI_MODEL_DEPLOYMENT_NAME |
该项目中的模型部署名称，而不只是模型的目录名。 |
两个工作流示例在启动时加载 .env 。 项目终结点不是 Azure OpenAI 帐户终结点。 不要将该文件纳入版本控制，也不要把凭据写入应用程序代码中。
在本地进行身份验证
示例使用 DefaultAzureCredential。 对于Azure CLI凭据路径，请使用可访问项目模型的帐户登录：
az login
参考：使用Azure CLI登录。
工具包登录时会为扩展操作选择项目。 本地代理进程还需要受支持的凭据。 有关其他选项，请参阅 DefaultAzureCredential for Python 或 适用于 .NET 的凭据链。
在本地运行托管工作流
使用生成的调试配置启动 HTTP 服务器并打开 代理检查器。 单独打开代理检查器不会启动服务器。
使用此测试请求：
Create a slogan for a new electric SUV that is affordable and fun to drive. 工作流在编写器、审阅者和格式化程序完成后返回格式化的标语。
使用此测试请求： The quick brown fox jumps over the lazy dog. 工作流运行其翻译链并返回响应。
- 返回到生成的项目工作区。
- 如果要检查执行，在工作流代码中设置断点。
- 按F5键。 如果系统提示，请选择 “调试本地代理 HTTP 服务器”。
- 等待服务器启动，并等待 Agent Inspector 打开。
- 发送针对您的样本的测试请求。
- 检查响应，然后用另一个请求重复此操作。 如果设置了断点，请检查值并继续执行。
示例工作完成后，修改工作流并重复本地测试。 如果你添加了工具，请发送一个需要真实工具结果的请求，并检查该调用。 仅模型答案或模拟响应并不能证明实时工具有效。
屏幕截图显示了启用了工具的本地代理，而不是工作流示例。 代理检查器通过延迟瀑布图和运行时间线展示其响应和工具调用。 可用的检查详细信息取决于正在运行的智能体及其检测配置。
如果你使用 GitHub Copilot，就可以在 Copilot 对话助手 中运行 /validate-microsoft-foundry-hosted-agent，按照 Foundry 最佳实践审查项目。 此聊天命令将打开报表;它不是终端命令，也不是运行工作流的替代项。
生成的任务使用代理服务器的端口 8088 。 Python调试也使用端口5679。 如果启动时报告端口冲突，请停止你自己拥有的冲突进程，或统一调整生成的任务配置。
在没有调试器的情况下运行
若要手动运行，请在示例的源目录中打开一个终端，其中包含可用的依赖项、环境值和Azure凭据。
python main.py
参考：Python工作流入口点。
设置本地服务器的 HTTP 地址，然后运行它：
$env:ASPNETCORE_URLS = "http://localhost:8088"
dotnet run
请参阅：ASP.NET Core 服务器 URL 和 dotnet run。
然后运行 Foundry Toolkit：从命令面板打开代理检查器 并连接到端口 8088上的本地服务器。 使用 python 或 dotnet run 运行示例时，启动的是本地进程，而不是容器。
可视化托管代理工作流执行
使用代理检查器检查正在运行的代理发出的事件、响应和工具调用。 当运行时产生工作流事件时，使用工作流可视化视图查看各步骤的执行顺序。
可用的详细信息取决于示例的检测配置。 请按照示例中的遥测设置说明，满足运行时特定要求。
这些步骤使用响应协议。 其他示例需要与协议匹配的客户端：HTTP 调用视图不是 WebSocket 客户端，Python活动示例使用 Microsoft 365 Agents Playground。 按照所选示例的本地测试说明进行操作。 更改配置中的协议名称不会将该协议添加到服务器。 请参阅 “选择托管代理协议”。
部署托管代理
本地工作流按预期方式运行后，请从项目工作区部署它。 Python和 C# 共享部署过程。 从 代码 和 远程 包模式开始，上传源并允许 Foundry 还原依赖项。
准备部署配置
查看并保存 azure.yaml 中的托管代理服务。 保留示例的协议配置，并在其中声明模型部署和其他必需的运行时设置。
部署过程会从源目录中的 .env 或进程环境中解析出已声明的环境变量值。 它不会转发每个本地 .env 条目。
平台提供保留的运行时值，例如 FOUNDRY_PROJECT_ENDPOINT，不要将其重新声明为部署设置。 请参阅 平台注入的环境变量。
在打包之前查看源目录的忽略规则。 将凭据、虚拟环境和缓存保留在 .env包外。 对于 ZIP 部署，源根.agentignore会替换其中.gitignore.dockerignore的规则，因此，如果添加该文件，请保留必要的排除项。
重要
不要提交或打包机密。 本地登录不会将用户的权限传输到已部署的代理。 为代理的运行时标识和支持的连接配置访问权限。 请参阅 托管代理权限。
使用远程包模式部署源
使用生成的工作区根目录，以便工具包可以读取服务配置并找到其源目录。
停止本地调试会话。
选择“开发人员工具>生成>部署到 Microsoft Foundry”。 还可以从命令面板运行 Foundry Toolkit：部署托管代理 。
如果出现 Foundry Project Setup，请选择订阅和项目，然后选择下一步。 否则，请确认默认项目是预期目标。
在 “基本信息”上，选择 “代码 作为 部署方法 ”，然后选择 “远程 ”作为 包模式。
选择 “新建代理 ”并输入 托管代理名称。 若要更新已部署的代理，请选择 “现有代理 ”，然后改为选择该代理。
选择“下一步”。
在查看 + 部署时，根据示例检查语言、运行时版本、入口点和 CPU 和内存。 确认源目录是否与服务
project的路径匹配。以下屏幕截图显示的是一个示例，其中 Python 3.14 及其入口点被隐藏，而不是这些工作流示例的设置。 对于Python，请使用 Python 3.13 和
python3 main.py. 对于 C#，请使用 .NET 10 以及为生成的项目检测到的入口点。
选择“部署”。 在通知和 输出 中查看进度。
继续 测试已部署的工作流。
将运行时与示例配置和本地环境匹配。 不要只因为是向导默认值而接受其他运行时。
提交表单时，工具包会保存部署选项。 这些本地设置不会证明云部署成功。 更新现有代理会创建新版本，而不是更改以前的版本。
选择其他 ZIP 包模式
工具包提供以下源代码打包选项：
| 封装模式 | 发生的情况 | 准备内容 |
|---|---|---|
| 远程 | Toolkit 软件包源码。 Foundry 会在预配过程中还原 Python 依赖项或 .NET 项目。 | 源、依赖项声明和兼容的入口点。 |
| 已捆绑 | 工具包暂存源，并在创建 ZIP 之前在本地运行 包命令 。 Foundry 运行已准备的包。 | 兼容的 Linux 依赖项以及该命令所需的本地工具。 默认 Python 命令会在 packages/ 中安装兼容的依赖项；.NET 命令会生成发布输出。 |
可选择的 ZIP 运行时包括 Python 3.13、Python 3.14 和 .NET 10。 将运行时与代码和依赖项匹配。 有关布局、限制和服务要求，请参阅 从源代码部署。 有关运行时支持策略，请参阅 支持的托管代理运行时。
部署容器镜像
如果需要自定义运行时映像或已有兼容的映像，请选择“基本”上的容器。
| 注册表选择 | 工具包行为 |
|---|---|
| 默认 ACR | 为所选项目创建或重复使用注册表，然后生成映像并通过Azure 容器注册表（ACR）推送映像。 |
| 自定义 ACR | 使用所选的现有注册表，然后生成映像并通过 ACR 推送映像。 |
| 自定义 ACR 映像 | 使用预生成的 ACR 映像引用，而无需生成或推送源。 |
对于生成选项，请在部署之前查看 Dockerfile 和生成上下文。 如果在向导中生成 Dockerfile，请查看该文件，然后选择“ 继续”并部署。 这些选项使用远程 ACR 生成，而不是本地 Docker 生成。
自定义注册表选项使用所选订阅中的注册表。 自定义注册表生成路径需要公用网络访问;预生成映像路径具有单独的专用网络要求。 选择镜像并不会配置网络连接。
在使用自定义注册表之前，请查看 容器要求 和 专用网络指南 。 这些部署针对 Foundry 代理服务，而不是已弃用的 Azure 容器应用 托管代理路径。 若要移动较旧的代理，请遵循 从托管代理预览版迁移。
测试已部署的工作流
成功的创建请求并不能证明运行时已准备就绪，或者其模型和工具可访问。 测试实际部署的确切版本。
- 在 “我的资源”>代理> 下，选择代理名称。
- 选择你刚刚部署的带编号的版本。
- 在 “详细信息”页面上，等待部署状态显示代理正在运行。 如果失败，请在重试之前检查部署输出。
- 打开 Playground 并发送在本地测试的相同请求。
- 查看响应。 如果您添加了工具，请发送一个需要使用这些工具的请求，并检查这些调用。
本地和云运行使用不同的凭据、依赖项环境和网络路径。 成功的本地响应不能保证成功的远程响应。
检查和更新已部署的代理
使用远程演练场来测试和检查您已部署的代理。 与使用 Agent Inspector 进行本地测试不同，此演练场中的请求会发送到托管在 Foundry 中的代理。
在 Foundry 工具包中，选择 “开发人员工具>生成>托管代理操场”。
在 “托管代理 ”下拉列表中，选择要检查的已部署代理和版本。 打开 Playground 以发送请求并查看响应和会话详细信息。
以下屏幕截图显示了已部署代理的响应，而不是任何一个工作流示例的预期输出。 代理和会话标识符处于隐藏状态。
使用这些控件检查和更新代理。 可用选项卡取决于其协议和连接的服务。
| 任务 | Action |
|---|---|
| 查看部署详细信息 | 打开详细信息以查看状态、配置和可复制的端点。 |
| 测试一个版本 | 为操场请求选择编号版本。 自动 遵循服务终结点的版本选择，这不一定是最新版本。 选取器不会更改其他客户端的路由。 |
| 查看运行时日志 | 打开 会话，选择会话并查看其日志。 运行时日志需要会话;生成输出是独立的。 停止日志流或取消请求不会停止托管代理。 |
| 检索已部署的代码 | 使用 下载代码资产 进行 ZIP 部署。 镜像部署提供的是镜像引用，而不是可下载的源项目。 |
| 更新行为 | 编辑并测试本地代码，然后使用现有代理重复部署过程以创建新版本。 |
如果可用，请使用 追踪 和 评估，以便在单次成功响应之外进行调查和质量衡量。 遵循 托管代理跟踪 和 托管代理评估的先决条件。
部署为代理提供了一个供程序调用的端点。 API 访问不需要单独的发布步骤。 发布到 Teams 或Microsoft 365是一项单独的任务。 请参阅 当前的代理终结点和发布模型。
Troubleshooting
使用报告的错误和示例配置来确定失败的步骤。
| 症状 | Action |
|---|---|
| 本地启动失败，因为缺少包。 | 确认所选解释器或 SDK，然后从示例的源目录中安装依赖项。 |
| 找不到项目终结点或模型。 | 检查 FOUNDRY_PROJECT_ENDPOINT 和 AZURE_AI_MODEL_DEPLOYMENT_NAME。 不要替换帐户终结点或模型目录名称。 |
| 身份验证或授权失败。 | 检查本地凭据和项目访问权限。 查看 托管代理权限 ，了解部署和运行时标识要求。 |
| 代理检查器无法连接。 | 确认服务器已启动且端口 8088 可用。 仅打开检查器并不会启动服务器。 |
| 部署失败。 | 查看部署错误并生成输出。 对于代码，请检查运行时、入口点、包模式和忽略规则。 对于容器，请检查映像和注册表权限。 |
| 本地响应有效，但部署的版本失败。 | 将部署的环境和标识权限与本地配置进行比较。 重新测试确切的已部署版本。 |
清理资源
完成后，停止本地调试会话。 如果不再需要已部署的测试代理，请按照 “管理托管代理 ”将其删除。
删除代理将移除其所有版本并终止当前活动会话。 它不会删除所有关联的 Azure 资源。
仅删除在本练习中创建且未被其他应用程序使用的云资源。 请勿删除共享 Foundry 项目、模型部署或容器注册表。
相关内容
使用以下指南扩展工作流：