在 Azure AI Foundry 中跟踪和观察 AI 代理（预览版）

在这篇文章中，你将学会如何：

• 了解关键跟踪概念
• 在 AI Foundry 中跟踪和观察 AI 代理
• 探索具有多代理可观测性的新语义约定
• 与常用代理框架集成
• 在 AI Foundry 门户和 Azure Monitor 中查看跟踪信息
• 在智能体操场中查看智能体线索

确定代理执行背后的原因对于故障排除和调试非常重要。 但是，由于多种原因，这对于复杂的代理而言可能很困难。这些原因包括：

• 生成响应所涉及的步骤可能很多，因此很难跟踪所有这些步骤。
• 步骤序列可能因用户输入而异。
• 每个阶段的输入/输出可能很长，需要进行更详细的检查。
• 代理运行时的每个步骤还可能涉及嵌套。 例如，代理可能会调用一个工具，后者又会使用另一个进程，然后该进程又调用另一个工具。 如果发现顶级代理运行的输出异常或不正确，则很难确切地确定是在执行中的哪个环节引入了问题。

跟踪结果可让你查看特定代理运行中涉及的每个基元的输入和输出，这些基元按调用顺序显示，从而轻松理解和调试 AI 代理的行为。

跟踪关键概念概述

下面是入门前关键概念的简要概述：

最佳做法

• 使用一致的跨度属性。
• 将评估运行标识符关联用于质量和性能分析。
• 修订敏感内容;避免将机密存储在属性中。

扩展 OpenTelemetry 以实现多代理可观测性

Microsoft 正在通过与 Cisco 的孵化引擎 Outshift 协作，向 OpenTelemetry 引入新的语义约定，从而增强多代理可观测性。 这些新增功能（基于 OpenTelemetry 和 W3C 跟踪上下文）在多代理系统中建立跟踪和遥测的标准化做法，从而促进对质量、性能、安全性和成本的关键指标进行一致的日志记录。 这种系统方法可更全面地了解多代理工作流，包括工具调用和协作。 这些进步已集成到 Azure AI Foundry、Microsoft Agent Framework、Semantic Kernel 和适用于 LangChain、LangGraph 和 OpenAI Agents SDK 的 Azure AI 包中，使客户能够通过 Azure AI Foundry 获取使用这些框架构建的代理系统的统一可观测性。 详细了解 跟踪集成。

在 Azure AI Foundry SDK 中设置跟踪

若要使用 Azure AI Foundry 聊天完成或生成代理，请安装：

pip install azure-ai-projects azure-identity

若要检测跟踪，需要安装以下检测库：

pip install azure-monitor-opentelemetry opentelemetry-sdk

若要查看 Azure AI Foundry 中的跟踪，需要将 Application Insights 资源连接到 Azure AI Foundry 项目。

1. 在 Azure AI Foundry 门户的左侧导航窗格中导航到“跟踪”。
2. 如果还没有 Application Insights 资源，请创建新的 Application Insights 资源。
3. 将资源连接到 AI Foundry 项目。

检测代码中的跟踪

若要跟踪聊天消息的内容，请将 AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED 环境变量设置为 true（不区分大小写）。 请记住，这可能包含个人数据。 若要了解详细信息，请参阅适用于 Python 的 Azure Core Tracing OpenTelemetry 客户端库。

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true" # False by default

让我们开始使用 OpenTelemetry 跟踪来检测代理，首先使用 AIProjectClient 进行身份验证并连接到 Azure AI 项目。

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=os.environ["PROJECT_ENDPOINT"],
)

接下来，从连接到项目的 Application Insights 资源中检索连接字符串，并设置 OTLP 导出程序以将遥测数据发送到 Azure Monitor。

from azure.monitor.opentelemetry import configure_azure_monitor

connection_string = project_client.telemetry.get_application_insights_connection_string()
configure_azure_monitor(connection_string=connection_string) #enable telemetry collection

现在，跟踪在 Azure AI 项目中创建和执行代理和用户消息的代码，以便查看故障排除或监视的详细步骤。

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.threads.create()
    message = project_client.agents.messages.create(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)

运行代理后，可以在 Azure AI Foundry 门户中开始查看跟踪。

本地日志跟踪

若要连接到 Aspire 仪表板 或其他与 OpenTelemetry 兼容的后端，请安装 OpenTelemetry 协议 （OTLP） 导出程序。 这样，便可以将跟踪打印到控制台或使用本地查看器（如 Aspire 仪表板）。

pip install azure-core-tracing-opentelemetry opentelemetry-exporter-otlp opentelemetry-sdk

接下来，配置控制台输出的跟踪：

from azure.core.settings import settings
settings.tracing_implementation = "opentelemetry"

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

# Setup tracing to console
span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

或者根据 Aspire 仪表板修改上述代码，以跟踪到本地 OTLP 查看器。

现在启用代理检测并运行代理：

from azure.ai.agents.telemetry import AIAgentsInstrumentor
AIAgentsInstrumentor().instrument()

# Start tracing
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.threads.create()
    message = project_client.agents.messages.create(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)

替代方法：适用于 VS Code 的 AI 工具包

AI 工具包提供了一种在 VS Code 中本地跟踪的简单方法。 它使用本地 OTLP 兼容的收集器，因此非常适合开发和调试。

该工具包通过 OpenTelemetry 支持 Azure AI Foundry 代理服务、OpenAI、人类和 LangChain 等 AI 框架。 可以在 VS Code 中即时查看跟踪，而无需云访问。

有关详细的设置说明和特定于 SDK 的代码示例，请参阅 AI 工具包中的跟踪。

跟踪自定义函数

若要跟踪自定义函数，请使用 OpenTelemetry SDK 检测代码。

1. 设置跟踪提供程序：初始化跟踪提供程序以管理和创建范围。
2. 创建范围：用范围包装要跟踪的代码。 每个跨度表示一个工作单元，可以嵌套以形成跟踪树。
3. 添加属性：使用属性扩充范围，以便为跟踪数据提供更多上下文。
4. 配置导出程序：将跟踪数据发送到后端进行分析和可视化。

下面是跟踪自定义函数的示例：

from opentelemetry import trace
from opentelemetry.trace import SpanKind

# Initialize tracer
tracer = trace.get_tracer(__name__)

def custom_function():
    with tracer.start_as_current_span("custom_function") as span:
        span.set_attribute("custom_attribute", "value")
        # Your function logic here
        print("Executing custom function")

custom_function()

有关详细说明和高级用法，请参阅 OpenTelemetry 文档。

将用户反馈附加到跟踪记录

为了在 Azure AI Foundry 门户中将用户反馈附加到跟踪并进行可视化，您可以使用 OpenTelemetry 的语义约定为您的应用程序进行仪器化，以实现跟踪功能和记录用户反馈。

通过使用响应 ID 或线程 ID 将反馈跟踪与其各自的聊天请求跟踪相关联，可以在 Azure AI Foundry 门户中查看和管理这些跟踪。 OpenTelemetry 的规范允许标准化和扩充的跟踪数据，可以在 Azure AI Foundry 门户中进行分析，以便优化性能和用户体验见解。 这种方法可帮助你充分利用 OpenTelemetry 的强大功能，增强应用程序的可观测性。

若要记录用户反馈，请遵循以下格式：

仅当用户向 GenAI 模型响应提供响应时，才能捕获用户反馈评估事件。 在可能的情况下，应该将其挂载到描述此类响应的 GenAI 跨度。

用户反馈事件正文具有以下结构：

在跟踪数据中使用服务名称

若要通过 Application Insights 中的唯一 ID 标识你的服务，可以在跟踪数据中使用服务名称 OpenTelemetry 属性。 如果要将数据从多个应用程序记录到同一 Application Insights 资源，并且想要区分它们，这非常有用。

例如，假设你有两个应用程序： App-1 和 App-2，其中跟踪配置为将数据记录到同一 Application Insights 资源。 也许你希望设置 App-1，以便按“相关性”进行持续评估，并设置 App-2，以便按“相关性”进行持续评估。 在 AI Foundry 门户中监视应用程序时，可以使用服务名称按 Application 进行筛选。

若要设置服务名称属性，可以按照步骤直接在应用程序代码中执行此操作，请参阅对不同资源使用多个跟踪提供程序。 或者，可以在部署应用之前设置环境变量 OTEL_SERVICE_NAME 。 若要详细了解如何使用服务名称，请参阅 OTEL 环境变量和服务资源语义约定。

若要查询给定服务名称的跟踪数据，请查询 cloud_roleName 属性。

| where cloud_RoleName == "service_name"

集成

Azure AI Foundry 通过使用我们与 Microsoft Agent Framework、Semantic Kernel、LangChain、LangGraph 和 OpenAI Agent SDK 的跟踪集成，只需最少的更改即可轻松记录日志。

在 Microsoft代理框架和语义内核上构建的跟踪代理

Azure AI Foundry 与 Microsoft Agent Framework 和 Semantic Kernel 实现了原生集成。 基于这两个框架构建的智能体在 Azure AI Foundry 可观测性服务中可实现开箱即用的跟踪。

• 详细了解 语义内核 和 Microsoft Agent Framework 中的跟踪和可观测性。

为在 LangChain 和 LangGraph 上生成的代理启用跟踪

你可以根据 opentelemetry-instrumentation-langchain 为遵循 OpenTelemetry 标准的 LangChain 启用跟踪。

安装必要的程序包后，可以轻松开始检测代码中的跟踪。

示例：使用 Azure AI 跟踪的 LangChain v1 代理

使用此端到端示例使用 langchain-azure-ai 跟踪器检测 LangChain v1 代理，该代理实现了最新的 OpenTelemetry （OTel） 规范，以便可以在 Azure AI Foundry Observability 中查看丰富的跟踪。

安装软件包

pip install \
  langchain-azure-ai \
  langchain \
  langgraph \
  langchain-openai \
  azure-identity \
  python-dotenv \
  rich

配置环境

• APPLICATION_INSIGHTS_CONNECTION_STRING：用于跟踪的 Azure Monitor Application Insights 连接字符串。
• AZURE_OPENAI_ENDPOINT：Azure OpenAI 终结点 URL。
• AZURE_OPENAI_CHAT_DEPLOYMENT：聊天模型部署名称。
• AZURE_OPENAI_VERSION：API 版本，例如 2024-08-01-preview。
• Azure 凭据通过 DefaultAzureCredential 解析（支持环境变量、托管标识、VS Code 登录等）。

可以将这些 .env 内容存储在用于本地开发的文件中。

跟踪器设置

from dotenv import load_dotenv
import os
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Weather information agent",
    id="weather_info_agent_771929",
)

tracers = [azure_tracer]

模型设置 （Azure OpenAI）

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
)

定义工具和提示

from dataclasses import dataclass
from langchain_core.tools import tool

system_prompt = """You are an expert weather forecaster, who speaks in puns.

You have access to two tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location.
If you can tell from the question that they mean wherever they are,
use the get_user_location tool to find their location."""

# Mock user locations keyed by user id (string)
USER_LOCATION = {
    "1": "Florida",
    "2": "SF",
}


@dataclass
class UserContext:
    user_id: str


@tool
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

使用运行时上下文并定义用户信息工具

from langgraph.runtime import get_runtime
from langchain_core.runnables import RunnableConfig

@tool
def get_user_info(config: RunnableConfig) -> str:
    """Retrieve user information based on user ID."""
    runtime = get_runtime(UserContext)
    user_id = runtime.context.user_id
    return USER_LOCATION[user_id]

创建智能体

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from dataclasses import dataclass


@dataclass
class WeatherResponse:
    conditions: str
    punny_response: str


checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    prompt=system_prompt,
    tools=[get_user_info, get_weather],
    response_format=WeatherResponse,
    checkpointer=checkpointer,
)

带跟踪功能运行智能体

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
    context = UserContext(user_id="1")

    r1 = agent.invoke(
        {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
        config=config,
        context=context,
    )
    print(r1.get("structured_response"))

    r2 = agent.invoke(
        {"messages": [{"role": "user", "content": "Thanks"}]},
        config=config,
        context=context,
    )
    print(r2.get("structured_response"))


if __name__ == "__main__":
    main()

启用langchain-azure-ai后，所有 LangChain v1 操作（LLM 调用、工具调用、代理步骤）均使用最新的 OpenTelemetry 语义约定进行跟踪，并显示在链接到 Application Insights 资源的 Azure AI Foundry Observability 中。

示例：使用 Azure AI 跟踪的 LangGraph 代理

此示例展示了一个简单的 LangGraph 智能体，它已集成 langchain-azure-ai，针对图形步骤、工具调用和模型调用生成符合 OpenTelemetry 标准的跟踪。

安装软件包

pip install \
  langchain-azure-ai \
  langgraph==1.0.0a4 \
  langchain==1.0.0a10 \
  langchain-openai \
  azure-identity \
  python-dotenv

配置环境

• APPLICATION_INSIGHTS_CONNECTION_STRING：用于跟踪的 Azure Monitor Application Insights 连接字符串。
• AZURE_OPENAI_ENDPOINT：Azure OpenAI 终结点 URL。
• AZURE_OPENAI_CHAT_DEPLOYMENT：聊天模型部署名称。
• AZURE_OPENAI_VERSION：API 版本，例如 2024-08-01-preview。

可以将这些 .env 内容存储在用于本地开发的文件中。

跟踪器设置

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=os.getenv("OTEL_RECORD_CONTENT", "true").lower() == "true",
    name="Music Player Agent",
)

Tools

from langchain_core.tools import tool

@tool
def play_song_on_spotify(song: str):
    """Play a song on Spotify"""
    # Integrate with Spotify API here.
    return f"Successfully played {song} on Spotify!"


@tool
def play_song_on_apple(song: str):
    """Play a song on Apple Music"""
    # Integrate with Apple Music API here.
    return f"Successfully played {song} on Apple Music!"


tools = [play_song_on_apple, play_song_on_spotify]

模型设置 （Azure OpenAI）

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
).bind_tools(tools, parallel_tool_calls=False)

生成 LangGraph 工作流

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver

tool_node = ToolNode(tools)

def should_continue(state: MessagesState):
    messages = state["messages"]
    last_message = messages[-1]
    return "continue" if getattr(last_message, "tool_calls", None) else "end"


def call_model(state: MessagesState):
    messages = state["messages"]
    response = model.invoke(messages)
    return {"messages": [response]}


workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)

workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",
        "end": END,
    },
)
workflow.add_edge("action", "agent")

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

带跟踪功能运行

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
input_message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
    event["messages"][-1].pretty_print()

启用 langchain-azure-ai 后，LangGraph 执行会针对模型调用、工具调用和图形转换，生成符合 OpenTelemetry 的跟踪跨度。 这些跟踪传输到 Application Insights 并在 Azure AI Foundry 可观测性服务中显示。

示例：用 Azure AI 追踪配置 LangChain 0.3

此最小设置演示了如何在 LangChain 0.3 应用程序中使用 langchain-azure-ai 跟踪器和 AzureChatOpenAI 来启用 Azure AI 跟踪。

安装软件包

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  langchain-azure-ai \
  python-dotenv

配置环境

• APPLICATION_INSIGHTS_CONNECTION_STRING：用于跟踪的 Application Insights 连接字符串。
• AZURE_OPENAI_ENDPOINT：Azure OpenAI 端点 URL。
• AZURE_OPENAI_CHAT_DEPLOYMENT：聊天模型部署名称。
• AZURE_OPENAI_VERSION：API 版本，例如 2024-08-01-preview。
• AZURE_OPENAI_API_KEY：Azure OpenAI API 密钥。

跟踪器和模型配置

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Tracer: emits spans conforming to updated OTel spec
azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Trip Planner Orchestrator",
    id="trip_planner_orchestrator_v3",
)
tracers = [azure_tracer]

# Model: Azure OpenAI with callbacks for tracing
llm = AzureChatOpenAI(
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    temperature=0.2,
    callbacks=tracers,
)

将 callbacks=[azure_tracer] 附加到链、工具或智能体，确保在 Azure AI Foundry 可观测性服务中跟踪和呈现 LangChain 0.3 操作。

为基于 OpenAI 智能体 SDK 构建的智能体启用跟踪

使用此代码片段为 OpenAI 代理 SDK 配置 OpenTelemetry 跟踪并为框架添加监测。 如果 APPLICATION_INSIGHTS_CONNECTION_STRING 已设置，它将导出到 Azure Monitor;否则，它会回退到控制台。

import os
from opentelemetry import trace
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

# Configure tracer provider + exporter
resource = Resource.create({
    "service.name": os.getenv("OTEL_SERVICE_NAME", "openai-agents-app"),
})
provider = TracerProvider(resource=resource)

conn = os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING")
if conn:
    from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
    provider.add_span_processor(
        BatchSpanProcessor(AzureMonitorTraceExporter.from_connection_string(conn))
    )
else:
    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

trace.set_tracer_provider(provider)

# Instrument the OpenAI Agents SDK
OpenAIAgentsInstrumentor().instrument(tracer_provider=trace.get_tracer_provider())

# Example: create a session span around your agent run
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_session[openai.agents]"):
    # ... run your agent here
    pass

在 Azure AI Foundry 门户中查看跟踪

在项目中转到“跟踪”，根据需要筛选跟踪。

通过选择跟踪，您可以逐步查看每个跨度并在观察应用程序响应的过程中识别问题。 这有助于调试和查明应用程序中的问题。

在 Azure Monitor 中查看跟踪

如果使用前面的代码片段记录了跟踪，就可以在 Azure Monitor Application Insights 中查看跟踪了。 可以从 “管理数据源 ”打开 Application Insights，并使用 端到端事务详细信息视图 进一步调查。

有关如何将 Azure AI 推理跟踪发送到 Azure Monitor 并创建 Azure Monitor 资源的详细信息，请参阅 Azure Monitor OpenTelemetry 文档。

在 Azure AI Foundry 代理游乐场中查看线程结果

借助 Azure AI Foundry 门户中的 Agents 演练场，可以查看你的代理生成的线程和运行结果。 若要查看线程结果，请选择活动线程中的 线程日志 。 还可以选择“指标”，以跨 AI 质量和风险和安全性的多个维度自动评估模型的性能。

选择 “线程日志”后，请查看：

• 线程详细信息
• 运行信息
• 有序的运行步骤及工具调用
• 用户和代理之间的输入和输出
• 关联评估指标（如果已启用）

相关内容

• Python 示例，包含完全可运行的 Python 代码，以便使用同步和异步客户端进行跟踪。
• 使用控制台跟踪和 Azure Monitor 跟踪代理的 Python 示例
• JavaScript 示例 包含完全可运行的 JavaScript 代码，以便使用同步和异步客户端进行跟踪。
• C# 示例，包含完全可运行的 C# 代码，以便使用同步和异步方法进行推理。