你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。
重要
本文中标记为（预览）的项目目前以公共预览版提供。 此预览版在没有服务级别协议的情况下提供，不建议将其用于生产工作负荷。 某些功能可能不受支持，或者可能具有受限功能。 有关详细信息，请参阅 Microsoft Azure 预览版的使用条款。
注意
跟踪仅对提示智能体正式发布。 托管代理、工作流代理和外部代理目前均为预览版。
Microsoft Foundry 提供监视和跟踪 AI 代理的可观测性平台。 它在代理运行期间捕获关键详细信息，例如输入、输出、工具使用情况、重试、延迟和成本。 了解代理执行背后的原因对于故障排除和调试非常重要。 但是，由于多种原因，了解复杂的代理带来了挑战：
- 生成响应所涉及的步骤可能很多，因此很难跟踪所有这些步骤。
- 步骤序列可能因用户输入而异。
- 每个阶段的输入/输出可能很长，值得进行更详细的检查。
- 代理运行时的每个步骤也可能涉及嵌套。 例如，代理可能会调用一个工具，该工具使用另一个进程，然后调用另一个工具。 如果发现顶级代理运行的异常或不正确的输出，则很难确切地确定在执行中引入问题的位置。
跟踪结果可让你查看特定代理运行中涉及的每个基元的输入和输出，这些基元按调用顺序显示，从而轻松理解和调试 AI 代理的行为。
先决条件
若要使用端到端跟踪，需要：
- 启用了跟踪的 Foundry 项目。 若要设置它，请参阅 如何在 Microsoft Foundry 中设置跟踪。
- 访问连接到项目的 Application Insights 资源。 有关背景信息，请参阅 Azure Monitor Application Insights。
- Log Analytics 阅读者角色，用于查看 Foundry 中的跟踪、洞察和可视化。
注意
跟踪将遥测数据存储在 Azure Monitor Application Insights 中，可能根据数据量和保留设置产生费用。 有关定价详细信息，请参阅 Application Insights 定价。
Foundry 中的 OpenTelemetry
OpenTelemetry （OTel） 提供用于收集和路由遥测数据的标准化协议。 Foundry 使用 OpenTelemetry 语义约定，以确保在受支持的工具和集成之间实现一致的跟踪。
跟踪关键概念
下面是入门前关键概念的简要概述：
| 关键概念 | 描述 |
|---|---|
| 跟踪 | 跟踪通过记录事件和状态变化（函数调用、值和系统事件）来捕获请求或工作流在应用程序中的历程。 请参阅 OpenTelemetry 跟踪。 |
| 跨度 | 跨度是跟踪的基本构件，表示跟踪中的单个操作。 每个范围捕获开始和结束时间、属性，并且可以嵌套以显示分层关系，使你能够看到完整的调用堆栈和操作序列。 |
| 属性 | 属性是附加到跟踪和跨度的键值对，提供上下文元数据，如函数参数、返回值或自定义批注。 这些扩充跟踪数据，使其更具信息性，并可用于分析。 |
| 语义约定 | OpenTelemetry 定义语义约定，以标准化跟踪数据属性的名称和格式，以便更轻松地跨工具和平台进行解释和分析。 若要了解详细信息，请参阅 OpenTelemetry 的语义约定。 |
| 跟踪导出器 | 跟踪导出程序将跟踪数据发送到后端系统进行存储和分析。 在 Foundry 中，跟踪存储在 Azure Monitor Application Insights 中。 若要了解如何启用和查看跟踪，请参阅如何在 Microsoft Foundry 中设置跟踪。 |
Foundry 中跟踪的工作原理
跟踪有助于回答“此响应来自何处？”和“哪个步骤引入了错误或延迟峰值？”
从较高层面讲，跟踪会捕获：
- 用户输入和代理输出。
- 工具用法，包括工具调用和结果。
- 令牌消耗
- 持续时间和延迟等时间信号。
为项目启用跟踪后，可以在 Foundry 门户和 Azure Monitor Application Insights 中检查跟踪。 有关分步设置和查看选项，请参阅 如何在 Microsoft Foundry 中设置跟踪。
利用多代理可观测性扩展 OpenTelemetry
Microsoft与 Cisco Outshift 协作为多代理系统引入了新的语义约定，这些约定基于 OpenTelemetry 和 W3C 跟踪上下文。 这些约定标准化了多代理者工作流程中的遥测过程，以便能够一致地记录关于质量、性能、安全性和成本的指标日志，其中包括工具调用和协作。
这些增强功能已集成到以下项中：
- 铸造
- Microsoft代理框架
- LangChain
- LangGraph
- OpenAI 代理 SDK
若要了解详细信息，请参阅 跟踪集成。
下表描述了多代理可观测性的语义约定。 跨度捕获离散操作，子跨度显示父范围中的嵌套操作，属性提供元数据，并在执行期间标记重大事件。
| 类型 | 上下文/父范围 | 名称/属性/事件 | 目的 |
|---|---|---|---|
| 跨度 | — | 执行任务 | 捕获任务计划和事件传播的过程，提供有关任务如何分解和分派的深刻见解。 |
| 子范围 | invoke_agent | 代理之间的互动 | 跟踪代理之间的通信。 |
| 子范围 | invoke_agent | agent.state.management | 有效的上下文、短期或长期内存管理。 |
| 子范围 | invoke_agent | agent_planning | 记录代理的内部规划步骤。 |
| 子范围 | invoke_agent | 代理编排 | 捕获智能体到智能体编排。 |
| 属性 | invoke_agent | 工具定义 | 描述工具的用途或配置。 |
| 属性 | invoke_agent | llm_spans | 记录模型调用范围。 |
| 属性 | execute_tool | tool.call.arguments | 记录在工具调用期间传递的参数。 |
| 属性 | execute_tool | tool.call.results | 记录工具返回的结果。 |
| 事件 | — | 评估 (name, error.type, label) | 启用对智能体性能和决策的结构化评估。 |
最佳做法
- 使用一致的跨度属性：在所有代理和工具中应用相同的属性名称和格式，以简化查询和分析。
- 关联评估运行 ID：将跟踪数据与评估运行进行匹配，以在统一界面中分析质量和性能。
- 编辑敏感内容：在数据到达遥测之前，从提示、工具参数和跨度属性中删除或屏蔽个人数据、机密信息和凭据。
安全和隐私
跟踪可以捕获敏感信息（例如用户输入、模型输出以及工具参数和结果）。 使用以下做法来降低风险：
- 不要在提示、工具参数或跨属性中存储机密、凭据或令牌。
- 在遥测中显示个人数据之前，请对个人数据和其他敏感内容进行修订或最小化。
- 将跟踪数据视为生产遥测数据，并应用用于日志和指标的相同访问控制和保留策略。
故障 排除
如果跟踪未出现在 Foundry 门户或 Application Insights 中：
- 验证 Foundry 项目是否已连接到 Application Insights 资源。
- 检查帐户是否具有查询遥测所需的权限。
- 确保你的智能体代码包含必要的检测。 有关特定于框架的设置，请参阅 追踪集成。
提示
在所有支持 Foundry 的区域中都提供跟踪功能。 跟踪数据的保留和采样遵循 Application Insights 的配置。 有关详细信息，请参阅 Azure Monitor Logs 中的 Data 保留和存档。