在 Microsoft Foundry 中为 AI 智能体设置跟踪

#在 Microsoft Foundry 中为 AI 智能体设置跟踪

重要

本文中标为预览（preview）的项目目前处于预览。该预览不提供服务级别协议，Microsoft 不建议将其用于生产工作负载。某些功能可能不受支持，或能力受限。

注意

跟踪（tracing）对提示智能体和托管智能体已正式发布。工作流和外部智能体处于预览。

使用跟踪来调试 AI 智能体，并在生产中监控它们的行为。跟踪捕获详细遥测，包括延迟、异常、提示内容和检索操作，以便你更快地发现问题并修复。

推荐的起点是服务端跟踪（server-side tracing）。把 Application Insights 资源连接到项目后，Foundry 会自动启用它。不需要改代码，启用后几分钟内即可看到跟踪。服务端跟踪适用于托管在 Foundry 中的任何智能体。当你需要看到自己的应用代码，例如跟踪围绕一次智能体调用的自定义逻辑时，可以把客户端埋点作为第二步加上。

Microsoft Foundry Skill 可以帮助选择服务端或客户端跟踪，并排查缺失的遥测。

前提条件

• 一个 Foundry 项目。

• 一个用于存储跟踪的 Azure Monitor Application Insights 资源（新建一个，或连接已有的）。

• 对连接到你项目的 Application Insights 资源的访问权限。

• 在已连接的 Application Insights 资源上具备 Log Analytics Reader 角色（查询遥测所必需）。如果底层 Log Analytics 表受到保护，还要分配 Privileged Monitoring Data Reader 角色。

把 Application Insights 连接到 Foundry 项目

Foundry 使用 OpenTelemetry 语义约定，把跟踪存储在 Application Insights 中。

1. 登录 Microsoft Foundry。确认 New Foundry 开关已打开。这些步骤针对的是 Foundry (new)。

2. 打开你的 Foundry 项目。

3. 在左侧导航中选择 Agents。

4. 在顶部选择 Traces。

5. 在右侧选择 Connect，以创建或连接一个 Application Insights 资源。

• 要连接已有资源，选择该资源，然后选择 Connect。

• 要创建新资源，选择 Create new，然后完成向导。

连接成功后会出现确认消息。

使用项目详细信息中的连接路径

如果看不到消息栏或 Connect 按钮，用下面这种替代方式启用 Azure Monitor Application Insights。

1. 在右上角导航中选择 Manage，然后选择 Project details。

2. 选择 Connected resources 选项卡，然后选择 Add connection。

3. 在 Choose a connection 中选择 Application Insights。

若要使用 Entra 身份验证的跟踪接入，请参阅 为 Foundry 智能体跟踪接入配置 Microsoft Entra 身份验证（预览）。

连接该资源之后，项目就可以使用跟踪。

重要

确认你拥有查询遥测所需的权限。

• 对于基于日志的查询，先分配 Log Analytics Reader 角色。如果底层 Log Analytics 表受到保护，还要分配 Privileged Monitoring Data Reader 角色。

• 要了解如何分配角色，请参阅 使用 Azure 门户分配 Azure 角色。

• 要大规模管理访问，使用 Microsoft Entra 组。

为 AI 智能体埋点

选择与你构建和运行智能体的方式相匹配的做法。

Foundry 门户中的服务端跟踪

从服务端跟踪开始。Foundry 会为常见的智能体和工作流场景记录跟踪，无需改动你的代码。

• Foundry 会在 Foundry 门户中，为提示智能体（Prompt agents）、托管智能体（Host agents）和工作流自动记录服务端跟踪。在 Foundry 项目中启用跟踪之后，你可以访问过去 90 天的开箱跟踪。

• Foundry 也支持与主流智能体框架的简便集成。

使用 Microsoft Foundry SDK 的客户端跟踪

按以下步骤安装 OpenTelemetry 和 Azure SDK 跟踪插件：

• Python

• C#

pip install azure-ai-projects azure-identity opentelemetry-sdk azure-core-tracing-opentelemetry

参考：azure-ai-projects，azure-core-tracing-opentelemetry

dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.Identity
dotnet add package Azure.Monitor.OpenTelemetry.Exporter
dotnet add package OpenTelemetry.Exporter.Console

在创建项目客户端或运行智能体操作之前，启用 GenAI 跟踪：

using Azure.AI.Projects;
using Azure.Identity;

AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true);

var projectEndpoint = Environment.GetEnvironmentVariable(
   "FOUNDRY_PROJECT_ENDPOINT");
AIProjectClient projectClient = new(
   endpoint: new Uri(projectEndpoint!),
   tokenProvider: new DefaultAzureCredential());

参考：AIProjectClient，DefaultAzureCredential

重要

要在应用中使用项目的端点，需要配置 Microsoft Entra ID。如果不配置 Microsoft Entra ID，就使用 Application Insights 连接字符串。

运行智能体之后，可以在 Foundry 门户中查看并分析跟踪。

要把跟踪导出到 Azure Monitor 或控制台的端到端 Python 和 .NET 示例，请参阅 配置客户端跟踪。

使用 Visual Studio Code 的 Microsoft Foundry Toolkit 在本地跟踪

适用于 Visual Studio Code 的 Microsoft Foundry Toolkit 扩展，让你通过本地兼容 OTLP 的收集器在 VS Code 中本地跟踪。这种方式适合开发和调试。

该工具包通过 OpenTelemetry 支持 Foundry Agent Service、OpenAI、Anthropic 和 LangChain 等 AI 框架。你可以在 VS Code 中立刻看到跟踪，而不需要云访问。

详细安装说明和特定 SDK 的代码示例，请参阅 Foundry Toolkit 中的跟踪。

查看并分析跟踪

在 Foundry 门户中查看跟踪

在 Foundry 项目中，进入智能体或工作流的 Traces 选项卡。你可以搜索、筛选或排序最近 90 天已接入的跟踪。

选择一条跟踪，逐步查看每个跨度（span），发现问题，并观察应用如何响应。这个过程帮助你调试并定位应用中的问题。

在 Azure Monitor 中查看跟踪

跟踪会发送到 Azure Monitor Application Insights，因此你可以在那里查看。

关于如何把跟踪发送到 Azure Monitor 以及如何创建 Azure Monitor 资源的更多信息，请参阅 Azure Monitor OpenTelemetry 文档。

查看对话结果

对话（Conversation） 是用户与智能体之间端到端对话历史的持久上下文。在 Foundry 门户中，你可以在 Traces 页面上，连同跟踪一起开箱查看智能体运行的 Conversation 结果。

按响应 ID（Response ID）或映射到该对话的跟踪 ID（Trace ID）搜索。然后选择一个 Conversation ID 以查看：

• 对话历史详情

• 一次运行中的响应信息和 token

• 有序的动作、运行步骤和工具调用

• 用户与智能体之间的输入和输出

核验跟踪是否生效

1. 确认项目已连接到 Application Insights。如有需要，按 把 Application Insights 连接到 Foundry 项目 中的步骤操作。

2. 至少运行一次智能体或工作流（例如使用门户或你的应用）。

3. 在 Foundry 项目中打开 Traces 视图，确认出现一条新跟踪。

跟踪正常时，你会看到最近跟踪的列表，带有时间戳、持续时间和状态指示。选择一条跟踪以查看其跨度详情。

如果看不到新跟踪，等待几分钟并刷新，然后参阅故障排除。

安全与隐私

跟踪可能捕获敏感信息，例如用户输入、模型输出，以及工具参数和结果。用这些做法降低风险：

• 不要把机密、凭证或 token 放进提示、工具参数或跨度属性。

• 在个人数据和其他敏感内容进入遥测之前进行脱敏或最小化。

• 把跟踪数据当作生产遥测，并应用你用于日志和指标的同一套访问控制与保留策略。

更多指导请参阅 安全与隐私。

数据保留与成本

Foundry 把跟踪存储在连接到项目的 Application Insights 资源中。数据保留和计费遵循你的 Application Insights 与 Log Analytics 配置。

故障排除

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/observability/how-to/trace-agent-setup