在 Visual Studio Code 中创建托管代理工作流（预览版）

使用 Microsoft Foundry for Visual Studio Code 扩展创建、测试和部署托管的 Foundry 代理工作流。 托管工作流允许多个代理按顺序协作，每个代理都有自己的模型、工具和说明。

在开始之前，使用扩展 在 Foundry 代理服务中生成代理 。 然后，可以将托管工作流添加到该代理。

本文介绍如何创建工作流项目、在本地运行、可视化执行并将其部署到 Foundry 工作区。

先决条件

• 具有已部署模型或 Azure OpenAI 资源的 Foundry 项目。
• 已安装 用于 Visual Studio Code 扩展的 Microsoft Foundry 。
• 分配了 Azure AI 用户 和 AcrPull 角色的项目托管标识。 此外，将 acrPull 角色分配给计划在其中部署托管代理的 Foundry 项目的托管标识。
• 托管代理支持的区域。

• Python 3.10 或更高版本。

• .NET 9 SDK 或更高版本。

创建托管代理工作流

可以使用 Foundry for Visual Studio Code 扩展创建托管代理工作流。 托管代理工作流是一系列协同工作的代理来完成任务。 工作流中的每个代理都可以有自己的模型、工具和说明。

1. 打开命令面板（Ctrl+Shift+P）。

2. 运行以下命令：>Microsoft Foundry: Create a New Hosted Agent。

3. 选择编程语言。

4. 选择要在其中保存新工作流的文件夹。

5. 输入工作流项目的名称。

使用托管代理项目所需的文件（包括一个示例代码文件）创建一个新文件夹，以帮助你入门。

安装依赖项

安装托管代理项目所需的依赖项。 依赖项因创建项目时所选的编程语言而异。

1. 创建虚拟环境。

    python -m venv .venv
   

2. 激活虚拟环境。

   # PowerShell
   ./.venv/Scripts/Activate.ps1
   
   # Windows cmd
   .venv\Scripts\activate.bat
   
   # Unix/MacOS
   source .venv/bin/activate
   

3. 安装以下包：

   pip install azure-ai-agentserver-agentframework
   

1. 转到项目目录并运行以下命令以获取所需的 NuGet 包：

   dotnet restore
   

在本地运行托管工作流

示例工作流项目使用必要的环境变量创建一个 .env 文件。 使用 Foundry 凭据创建或更新 .env 文件：

AZURE_AI_PROJECT_ENDPOINT=https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>

AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

重要

从不将 .env 文件提交到版本控制。 将其添加到 .gitignore 文件。

对托管代理进行身份验证

托管代理示例使用 DefaultAzureCredential 进行身份验证。 将开发环境配置为通过某个受支持的源提供凭据，例如：

• Azure CLI （az login）
• Visual Studio Code 帐户登录
• Visual Studio 帐户登录
• 服务主体的环境变量（AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET）

在运行示例之前，通过运行 Azure CLI az account show 或 az account get-access-token 命令在本地确认身份验证。

可以在交互式模式或容器模式下运行托管代理。

在交互式模式下运行托管代理

在 VS Code 中按 F5 开始调试。 或者，可以使用 VS Code 调试菜单：

1. 打开 “运行和调试 ”视图（Ctrl+Shift+D / Cmd+Shift+D）
2. 从下拉列表中选择“调试本地工作流 HTTP 服务器”
3. 选择绿色 的“开始调试 ”按钮（或按 F5）

这将：

1. 在启用调试的情况下启动 HTTP 服务器
2. 打开 AI 工具包代理检查器进行交互式测试
3. 允许设置断点并实时检查工作流执行。

在容器模式下运行托管代理

小窍门

在启动容器代理程序之前打开本地环境，以确保可视化功能正常运作。

若要在容器模式下运行托管代理，请执行以下作：

1. 打开 Visual Studio Code 命令面板并执行 Microsoft Foundry: Open Container Agent Playground Locally 该命令。
2. 执行 main.py 以初始化容器化托管代理。
3. 通过沙盒界面向代理提交请求。 例如，输入一个提示，例如：“为新的电动运动型多用途车创建一个标语，既经济实惠又驾驶乐趣无穷。”
4. 在游乐场界面中查看代理的响应。

示例工作流项目使用必要的环境变量创建一个 .env 文件。 使用 Foundry 凭据创建或更新 .env 文件：

1. 根据您的操作系统设置环境变量：

   Windows （PowerShell）

   $env:AZURE_AI_PROJECT_ENDPOINT="https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>"
   $env:AZURE_AI_MODEL_DEPLOYMENT_NAME="your-deployment-name"
   

   Windows （命令提示符）

   set AZURE_AI_PROJECT_ENDPOINT=https://your-resource-name.openai.azure.com/
   set AZURE_AI_MODEL_DEPLOYMENT_NAME=your-deployment-name
   

   macOS/Linux （Bash）

   export AZURE_AI_PROJECT_ENDPOINT="https://your-resource-name.openai.azure.com/"
   export AZURE_AI_MODEL_DEPLOYMENT_NAME="your-deployment-name"
   

对托管代理进行身份验证

托管代理示例使用 DefaultAzureCredential 进行身份验证。 将开发环境配置为通过某个受支持的源提供凭据，例如：

• Azure CLI （az login）
• Visual Studio Code 帐户登录
• Visual Studio 帐户登录
• 服务主体的环境变量（AZURE_TENANT_ID、AZURE_CLIENT_ID、AZURE_CLIENT_SECRET）

在运行示例之前，通过运行 Azure CLI az account show 或 az account get-access-token 命令在本地确认身份验证。

可以在交互式模式或容器模式下运行托管代理。

在交互式模式下运行托管代理

直接运行托管代理进行开发和测试：

dotnet restore
dotnet build
dotnet run

在容器模式下运行托管代理

小窍门

在启动容器代理程序之前打开本地环境，以确保可视化功能正常运作。

若要在容器模式下运行代理，请执行以下作：

1. 打开 Visual Studio Code 命令面板并执行 Microsoft Foundry: Open Container Agent Playground Locally 该命令。
2. 使用以下命令初始化容器化的托管代理。

   dotnet restore
   dotnet build
   dotnet run
   

3. 通过沙盒界面向代理提交请求。 例如，输入一个提示，例如：“为新的电动运动型多用途车创建一个标语，既经济实惠又驾驶乐趣无穷。”
4. 在游乐场界面中查看代理的响应。

可视化托管代理工作流执行

Foundry for Visual Studio Code 扩展提供了一个实时执行图，显示工作流中的代理如何交互和协作。 在项目中启用可观测性以使用此可视化效果。

通过添加以下代码片段在工作流中启用可视化效果：

from agent_framework.observability import setup_observability
setup_observability(vs_code_extension_port=4319) # Default port is 4319

将以下引用添加到 csproj 文件：

<ItemGroup>
    <PackageReference Include="OpenTelemetry" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
    <PackageReference Include="System.Diagnostics.DiagnosticSource" Version="9.0.10" />
</ItemGroup>

更新程序以包括以下代码片段：

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4319";

var resourceBuilder = OpenTelemetry
    .Resources.ResourceBuilder.CreateDefault()
    .AddService("WorkflowSample");

var s_tracerProvider = OpenTelemetry
    .Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.Agents.AI.*") // All agent framework sources
    .SetSampler(new AlwaysOnSampler()) // Ensure all traces are sampled
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri(otlpEndpoint);
        options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.Grpc;
    })
    .Build();

监视和可视化托管代理工作流

若要实时监视和可视化托管代理工作流执行，请执行以下步骤：

1. 打开命令面板（Ctrl+Shift+P）。

2. 运行以下命令：>Microsoft Foundry: Open Visualizer for Hosted Agents。

VS Code 中将打开一个新选项卡以显示执行图。 可视化图表在工作流进行时自动更新，以显示代理之间的流向及其交互。

端口冲突

对于端口冲突，可通过在 Foundry 扩展设置中进行配置来更改可视化端口。 为此，请执行以下步骤：

1. 在 VS Code 的左侧栏中，选择齿轮图标以打开设置菜单。
2. 选择 Extensions>Microsoft Foundry Configuration。
3. 找到该 Hosted Agent Visualization Port 设置并将其更改为可用的端口号。
4. 重启 VS Code 以应用更改。

更改代码中的端口

通过设置 FOUNDRY_OTLP_PORT 环境变量更改可视化端口。 在 workflow.py 文件中相应地更新可观测性端口。

例如，若要将端口更改为 4318，请使用以下命令：

  export FOUNDRY_OTLP_PORT=4318

在 workflow.py中，更新可观测性配置中的端口号：

  setup_observability(vs_code_extension_port=4318)

小窍门

若要启用更多调试信息，请将 enable_sensitive_data=True 参数添加到 setup_observability 函数。

对于任何端口冲突，请通过设置 FOUNDRY_OTLP_PORT 环境变量来更改可视化端口。 相应地更新程序中的 OTLP 终结点。

例如，若要将端口更改为 4318，请使用以下命令：

  $env:FOUNDRY_OTLP_PORT="4318"

在程序中，更新 OTLP 终结点以使用新的端口号：

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4318";

部署托管代理

在本地测试托管代理后，将其部署到 Foundry 工作区，以便其他团队成员和应用程序可以使用它。

重要

请确保提供在 Foundry 工作区中部署托管代理所需的权限，如 先决条件中所述。 可能需要与 Azure 管理员协作才能获取所需的角色分配。

1. 打开 Visual Studio Code 命令面板并运行 Microsoft Foundry: Deploy Hosted Agent 该命令。
2. 通过选择目标工作区、指定容器代理文件（container.py以及根据需要定义任何其他部署参数）来配置部署设置。
3. 成功部署后，托管代理将显示在 Hosted Agents (Preview) Microsoft Foundry 扩展树视图的部分中。
4. 选择已部署的代理，以通过集成的沙盒界面访问详细信息并测试其功能。

1. 打开 Visual Studio Code 命令面板并运行 Microsoft Foundry: Deploy Hosted Agent 该命令。
2. 通过选择目标工作区、指定容器代理文件（<your-project-name>.csproj以及根据需要定义任何其他部署参数）来配置部署设置。
3. 成功部署后，托管代理将显示在 Hosted Agents (Preview) Microsoft Foundry 扩展树视图的部分中。
4. 选择已部署的代理，以通过集成的沙盒界面访问详细信息并测试其功能。

相关内容

• 托管代理概念
• 在 Foundry 代理服务中生成代理
• 在 Microsoft Foundry 中发布和共享代理