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

• Python 3.12 或更高版本。

• .NET 9 SDK 或更高版本。

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 文件：

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

MODEL_DEPLOYMENT_NAME=<your-model-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 命令在本地确认身份验证。

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

在代理检查器中运行托管代理

若要在 Visual Studio Code 本地运行托管代理，请选择 F5 密钥。 这会打开代理检查器并执行应用程序。

这将：

1. 启动代理服务器：agentdev的CLI在端口8087上将你的代理封装为HTTP服务器，并在端口5679附加了debugpy。
2. 发现代理： UI 从 /agentdev/entities中提取可用的代理/工作流。
3. 流式执行： 聊天输入会流向 /v1/responses，并通过 SSE 流传输事件，以实现实时可视化。
4. 启用代码导航： 双击工作流节点以在编辑器中打开相应的源文件。
5. 启用与本地代理聊天 并查看响应、命中调试断点等。

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

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

   • Windows （PowerShell）
   • Windows （命令提示符）
   • macOS/Linux （Bash）

   $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"
   

对托管代理进行身份验证

托管代理示例使用 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 Toolkit for Visual Studio Code 提供了一个实时执行流程图，显示您的工作流中的代理如何互动协作。 在项目中启用可观测性以使用此可视化效果。

将以下引用添加到 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 环境变量来更改可视化端口。 相应地更新程序中的 OTLP 终结点。

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

  $env:FOUNDRY_OTLP_PORT="4318"

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

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

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

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