Konfigurieren der Ablaufverfolgung für KI-Agent-Frameworks (Vorschau)

Wichtig

In diesem Artikel markierte Elemente (Vorschau) befinden sich derzeit in der öffentlichen Vorschau. Diese Vorschau wird ohne Vereinbarung auf Serviceebene bereitgestellt und wird für Produktionsworkloads nicht empfohlen. Bestimmte Features werden möglicherweise nicht unterstützt oder weisen eingeschränkte Funktionen auf. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Hinweis

Tracing ist allgemein nur für Prompt Agents verfügbar. Gehostete Agenten, Workflow-Agenten und externe Agenten sind als Vorschau verfügbar.

Wenn sich KI-Agenten in der Produktion unerwartet verhalten, verschafft Ihnen die Ablaufverfolgung die nötige Einsicht, um die Ursache schnell zu identifizieren. Das Tracing erfasst detaillierte Telemetriedaten, einschließlich LLM-Aufrufe, Toolaufrufe und Agent-Entscheidungsflüsse, sodass Sie Probleme debuggen, Latenz überwachen und das Verhalten von Agenten bei verschiedenen Anforderungen nachvollziehen können.

Microsoft Foundry bietet Ablaufverfolgungsintegrationen für beliebte Agent-Frameworks, die minimale Codeänderungen erfordern. In diesem Artikel erfahren Sie, wie Sie:

Konfigurieren der automatischen Ablaufverfolgung für Microsoft Agent Framework und semantischen Kernel
Richten Sie die Microsoft OpenTelemetry-Distribution für LangChain und LangGraph ein
Instrumentieren des OpenAI Agents SDK mit OpenTelemetry
Überprüfen, ob Spuren im Foundry-Portal angezeigt werden
Beheben häufig auftretende Ablaufverfolgungsprobleme

Voraussetzungen

Ein Foundry-Projekt. Weitere Informationen finden Sie unter Create a Foundry project.
Verfolgung, die mit einer Ressource von Azure Monitor Application Insights verbunden ist. Zum Einrichten siehe Einrichten der Ablaufverfolgung in Microsoft Foundry.
Mitwirkender oder höherrangiger Mitarbeiter der Application Insights-Ressource für die Trace-Erfassung.
Zugriff auf die verbundene Application Insights-Ressource zum Anzeigen von Ablaufverfolgungen. Bei protokollbasierten Abfragen benötigen Sie möglicherweise auch Zugriff auf den zugeordneten Log Analytics Arbeitsbereich.
Python 3.10 oder höher (erforderlich für alle Codebeispiele in diesem Artikel).
Das microsoft-opentelemetry Paket (erforderlich für LangChain- und LangGraph-Beispiele).
Wenn Sie LangChain oder LangGraph verwenden, benötigen Sie eine Python-Umgebung mit installiertem pip.

Bestätigen, dass Sie Telemetrie anzeigen können

Um Trace-Daten anzuzeigen, stellen Sie sicher, dass Ihr Konto Zugriff auf die verbundene Application Insights-Ressource hat.

Öffnen Sie im Azure-Portal die Application Insights-Ressource, die mit Ihrem Foundry-Projekt verbunden ist.
Wählen Sie access control (IAM) aus.
Weisen Sie Ihrem Benutzer oder Ihrer Gruppe eine entsprechende Rolle zu.

Wenn Sie protokollbasierte Abfragen verwenden, gewähren Sie zunächst die Rolle Log Analytics Reader.

Sicherheit und Datenschutz

Die Ablaufverfolgung kann vertrauliche Informationen erfassen (z. B. Benutzereingaben, Modellausgaben und Tool-Argumente und -Ergebnisse).

Aktivieren Sie die Inhaltsaufzeichnung während der Entwicklung und beim Debuggen, um vollständige Anforderungs- und Antwortdaten anzuzeigen. Deaktivieren Sie die Inhaltsaufzeichnung in Produktionsumgebungen, um vertrauliche Daten zu schützen. In den Beispielen in diesem Artikel wird die Inhaltsaufzeichnung durch die Umgebungsvariablen OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, OTEL_SEMCONV_STABILITY_OPT_IN und AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING gesteuert.
Speichern Sie keine geheimen Schlüssel, Anmeldeinformationen oder Token in Eingabeaufforderungen oder Toolargumenten.

Weitere Anleitungen finden Sie unter "Sicherheit und Datenschutz".

Hinweis

Trace-Daten, die in Application Insights gespeichert sind, unterliegen den Datenaufbewahrungseinstellungen Ihres Arbeitsbereichs und den Preisen von Azure Monitor. Berücksichtigen Sie bei der Kostenverwaltung die Anpassung der Samplingraten oder Aufbewahrungszeiträume in der Produktion. Sehen Sie Azure Monitor pricing und Konfigurieren Sie Datenaufbewahrung und Archivierung.

Konfigurieren der Ablaufverfolgung für Microsoft Agent Framework und Semantischer Kernel

Microsoft Foundry verfügt über systemeigene Integrationen sowohl mit Microsoft Agent Framework als auch mit dem semantischen Kernel. Agenten, die mit einem der beiden Frameworks erstellt wurden, geben automatisch Tracing-Informationen aus, wenn das Tracing für Ihr Foundry-Projekt aktiviert ist – es sind weder zusätzlicher Code noch zusätzliche Pakete erforderlich.

So überprüfen Sie, ob die Ablaufverfolgung funktioniert:

Führen Sie Ihren Agent mindestens einmal aus.
Wechseln Sie im Gießereiportal zu Observability>Traces.
Prüfen Sie, ob eine neue Ablaufverfolgung mit Spans für die Operationen Ihres Agenten angezeigt wird.

Ablaufverfolgungen werden in der Regel innerhalb von 2 bis 5 Minuten nach der Agent-Ausführung angezeigt. Weitere Informationen zur erweiterten Konfiguration finden Sie in der frameworkspezifischen Dokumentation:

Konfigurieren Sie die Nachverfolgung mit den OpenInference-Instrumentierungsbibliotheken

Microsoft Foundry unterstützt OpenInference-Instrumentierungsbibliotheken zur Ablaufverfolgung von KI-Agenten. Diese openinference-* Pakete bieten eine automatische Instrumentierung für eine vielzahl von Frameworks und können verwendet werden, um sowohl gehostete Agents (Agents, die für Foundry bereitgestellt wurden) als auch Nicht-Foundry-Agents (Agents, die außerhalb von Foundry gehostet werden) nachzuverfolgen.

Durchsuchen Sie verfügbare Instrumentierungspakete auf PyPI. Informationen zu LangChain finden Sie unter dem LangChain-Beispiel der Microsoft OpenTelemetry-Distro, in dem gezeigt wird, wie Sie den Export an Azure Monitor und die automatische LangChain-Instrumentierung mit use_microsoft_opentelemetry aktivieren.

Die wichtigste Anforderung ist das Korrelieren von OpenInference-Ablaufverfolgungen mit einem bestimmten Agent. Wie Sie dies erreichen, hängt davon ab, wo Ihr Agent ausgeführt wird:

Gehostete Agents (bereitgestellt in Foundry)

Wenn Sie einen Agent mithilfe eines der gehosteten Agentserverpakete für Foundry bereitstellen, wird die Ablaufverfolgungskorrelation automatisch verarbeitet. Das Serverpaket:

Konfiguriert den Azure Monitor-Export für OpenTelemetry-Spans.
Reichert alle Spans mit Attributen für Projekt, Agentenname, Agentenversion und Agenten-ID an, sodass die Foundry-Benutzeroberfläche sie abfragen und anzeigen kann.

Es ist keine zusätzliche Konfiguration erforderlich. Installieren Sie das passende openinference-* Instrumentierungspaket für Ihr Framework, dann werden Traces automatisch im Foundry-Portal angezeigt.

LangChain-Agents, die außerhalb von Foundry gehostet werden

Wenn Ihr Agent nicht mit einem serverseitig gehosteten Agent-Serverpaket von Foundry bereitgestellt wird, konfigurieren Sie den Azure-Monitor-Export und die LangChain-Instrumentierung mit der Microsoft OpenTelemetry-Distribution. Die Distribution kann den Azure Monitor Exporter aktivieren und Agent-Identitätsattribute zu LangChain-Spans hinzufügen:

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "weather_info_agent_771929",
            "agent_name": "Weather information agent",
        },
    },
)

Legen Sie diesen Wert APPLICATIONINSIGHTS_CONNECTION_STRING auf die Application Insights-Ressource fest, die mit Ihrem Foundry-Projekt verbunden ist. Um Prompt- und Vervollständigungsinhalte während der Entwicklung zu erfassen, legen Sie OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT, OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental und AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true fest.

Ablaufverfolgung für LangChain und LangGraph konfigurieren

Hinweis

Die Ablaufverfolgungsintegration für LangChain und LangGraph ist derzeit nur in Python verfügbar.

Verwenden Sie die Microsoft OpenTelemetry-Distribution, um OpenTelemetry-kompatible Spans für LangChain- und LangGraph-Vorgänge auszugeben. Diese Ablaufverfolgungen werden in der Ansicht Einblick>Ablaufverfolgungen im Foundry-Portal angezeigt.

Beispiel: LangChain v1-Agent mit Azure KI-Ablaufverfolgung

Verwenden Sie dieses End-to-End-Beispiel, um einen LangChain v1-Agenten mit der Microsoft OpenTelemetry-Distribution zu instrumentieren. Die Distro ermöglicht die automatische Instrumentierung von LangChain mit den neuesten semantischen Konventionen von OpenTelemetry (OTel), sodass Sie umfangreiche Traces in der Foundry-Observability-Ansicht anzeigen können.

LangChain v1: Installieren von Paketen

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

LangChain v1: Konfigurieren der Umgebung

APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Monitor Application Insights-Verbindungszeichenfolge für die Nachverfolgung.
AZURE_OPENAI_ENDPOINT: Ihre Azure OpenAI-Endpunkt-URL.
AZURE_OPENAI_CHAT_DEPLOYMENT: Der Bereitstellungsname des Chatmodells.
AZURE_OPENAI_VERSION: API-Version, z. B 2024-08-01-preview. .
Das SDK löst Azure Anmeldeinformationen mithilfe von DefaultAzureCredential auf, die Umgebungsvariablen, verwaltete Identität und VS Code-Anmeldung unterstützt.

Speichern Sie diese Werte in einer .env Datei für die lokale Entwicklung.

LangChain v1: Tracer-Setup

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "weather_info_agent_771929",
            "agent_name": "Weather information agent",
        },
    },
)

LangChain v1: Modellsetup (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,
)

LangChain v1: Definieren von Tools und Eingabeaufforderungen

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}!"

LangChain v1: Verwenden des Laufzeitkontexts und Definieren eines Benutzerinformationstools

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]

LangChain v1: Erstellen des Agents

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,
)

LangChain v1: Ausführen des Agents mit Ablaufverfolgung

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}}
    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()

Wenn die Microsoft OpenTelemetry-Distribution aktiviert ist, geben alle LangChain-v1-Vorgänge (LLM-Aufrufe, Toolaufrufe, Agent-Schritte) OpenTelemetry-Spans gemäß den neuesten semantischen Konventionen aus. Diese Traces werden in der Ansicht Observability>Traces im Foundry-Portal angezeigt und mit Ihrer Application Insights-Ressource verknüpft.

Tipp

Nachdem Sie den Agenten ausgeführt haben, warten Sie einige Minuten, bis Traces angezeigt werden. Falls keine Spuren angezeigt werden, überprüfen Sie, ob Ihre Application Insights-Verbindungszeichenfolge korrekt ist, und lesen Sie den Abschnitt Häufig auftretende Probleme beheben.

Überprüfen Sie Ihre LangChain v1-Nachverfolgungen

Nach dem Ausführen des Agenten:

Warten Sie 2 bis 5 Minuten, bis die Traces übertragen werden.
Wechseln Sie im Gießereiportal zu Observability>Traces.
Suchen Sie nach einem Trace mit dem von Ihnen angegebenen Namen (z. B. "Wetterinformationsagent").
Erweitern Sie die Ablaufverfolgung, um Die Spannweiten für LLM-Aufrufe, Toolaufrufe und Agentschritte anzuzeigen.

Wenn keine Ablaufverfolgungen angezeigt werden, überprüfen Sie den Abschnitt Häufig auftretende Probleme beheben.

Beispiel: LangGraph-Agent mit Azure AI-Ablaufverfolgung

Dieses Beispiel zeigt einen einfachen LangGraph-Agenten, der mit der Microsoft OpenTelemetry-Distro instrumentiert wurde, um OpenTelemetry-konforme Traces für Graph-Schritte, Toolaufrufe und Modellaufrufe auszugeben.

LangGraph: Installieren von Paketen

pip install \
  microsoft-opentelemetry \
  "langgraph>=1.0.0" \
  "langchain>=1.0.0" \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: Konfigurieren der Umgebung

APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Monitor Application Insights-Verbindungszeichenfolge für die Nachverfolgung.
AZURE_OPENAI_ENDPOINT: Ihre Azure OpenAI-Endpunkt-URL.
AZURE_OPENAI_CHAT_DEPLOYMENT: Der Bereitstellungsname des Chatmodells.
AZURE_OPENAI_VERSION: API-Version, z. B 2024-08-01-preview. .

Speichern Sie diese Werte in einer .env Datei für die lokale Entwicklung.

LangGraph-Tracer-Einrichtung

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_name": "Music Player Agent",
        },
    },
)

LangGraph: 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]

LangGraph: Modellsetup (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)

Erstellen des LangGraph-Workflows

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)

LangGraph: Ausführen mit Ablaufverfolgung

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}}
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()

Wenn die Microsoft OpenTelemetry-Distribution aktiviert ist, sendet Ihre LangGraph-Ausführung OpenTelemetry-konforme Spans für Modellaufrufe, Tool-Aufrufe und Graphübergänge. Diese Traces fließen zu Application Insights und erscheinen in der Einblick>Ablaufverfolgung-Ansicht im Foundry-Portal.

Tipp

Jeder Diagrammknoten und jeder Randübergang erstellt eine separate Spanne, wodurch der Entscheidungsfluss des Agents leicht zu visualisieren ist.

Überprüfen Sie Ihre LangGraph-Ablaufverfolgungen

Nach dem Ausführen des Agenten:

Warten Sie 2 bis 5 Minuten, bis die Traces übertragen werden.
Wechseln Sie im Gießereiportal zu Observability>Traces.
Suchen Sie nach einer Spur mit dem von Ihnen angegebenen Namen (z. B. "Music Player Agent").
Erweitern Sie die Ablaufverfolgung, um Spannweiten für Diagrammknoten, Toolaufrufe und Modellaufrufe anzuzeigen.

Wenn keine Ablaufverfolgungen angezeigt werden, überprüfen Sie den Abschnitt Häufig auftretende Probleme beheben.

Beispiel: LangChain-Version 0.3-Setup mit Azure AI-Nachverfolgung

Dieses minimale Setup zeigt, wie sich Azure AI Tracing in einer LangChain-0.3-Anwendung mithilfe der Microsoft OpenTelemetry-Distribution und AzureChatOpenAI aktivieren lässt.

LangChain 0.3: Installieren von Paketen

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  microsoft-opentelemetry \
  python-dotenv

LangChain 0.3: Konfigurieren der Umgebung

APPLICATIONINSIGHTS_CONNECTION_STRING: Application Insights-Verbindungszeichenfolge für das Tracing. Um diesen Wert zu finden, öffnen Sie Ihre Application Insights-Ressource im Azure-Portal, wählen Sie Overview aus, und kopieren Sie die Verbindenzeichenfolge.
AZURE_OPENAI_ENDPOINT: Azure OpenAI-Endpunkt-URL.
AZURE_OPENAI_CHAT_DEPLOYMENT: Bereitstellungsname des Chatmodells.
AZURE_OPENAI_VERSION: API-Version, z. B 2024-08-01-preview. .
AZURE_OPENAI_API_KEY: Azure OpenAI-API-Schlüssel.

Hinweis

In diesem Beispiel wird die API-Schlüsselauthentifizierung aus Gründen der Einfachheit verwendet. Für Produktionsworkloads verwenden Sie DefaultAzureCredential mit get_bearer_token_provider, wie in den LangChain v1- und LangGraph-Beispielen gezeigt.

LangChain 0.3: Tracer und Modellsetup

import os
from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Enable Azure Monitor export and LangChain auto-instrumentation
use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "trip_planner_orchestrator_v3",
            "agent_name": "Trip Planner Orchestrator",
        },
    },
)

# Model: Azure OpenAI
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,
)

Nach der Initialisierung der Distro werden LangChain-0.3-Operationen automatisch global instrumentiert. Nach dem Ausführen Ihrer Kette oder Ihres Agenten erscheinen die Ablaufverfolgungen innerhalb von 2-5 Minuten in der Einblick>Ablaufverfolgungen-Ansicht im Foundry-Portal.

Konfigurieren der Ablaufverfolgung für OpenAI Agents SDK

Das OpenAI Agents SDK unterstützt die OpenTelemetry-Instrumentierung. Verwenden Sie den folgenden Codeausschnitt, um Tracing und Exportspannen für Azure Monitor zu konfigurieren. Wenn APPLICATION_INSIGHTS_CONNECTION_STRING nicht gesetzt ist, greift der Exporter auf die Konsole für das lokale Debuggen zurück.

Installieren Sie vor dem Ausführen des Beispiels die erforderlichen Pakete:

pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter

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

Überprüfen Sie die Ablaufverfolgungen im Foundry-Portal

Melden Sie sich bei Microsoft Foundry an. Stellen Sie sicher, dass die Umschaltfläche "Neue Gießerei " aktiviert ist. Diese Schritte beziehen sich auf Foundry (neu).
Bestätigen Sie, dass die Ablaufverfolgung für Ihr Projekt eingeschaltet ist. Wenn erforderlich, folgen Sie der Anleitung zur Einrichtung der Verfolgung in Microsoft Foundry.
Führen Sie Ihren Agent mindestens einmal aus.
Wechseln Sie im Gießereiportal zu Observability>Traces.
Prüfen Sie, ob eine neue Ablaufverfolgung mit Spans für die Operationen Ihres Agenten angezeigt wird.

Ablaufverfolgungen werden in der Regel innerhalb von 2 bis 5 Minuten nach der Agent-Ausführung angezeigt. Wenn Ablaufverfolgungen nach diesem Zeitpunkt immer noch nicht angezeigt werden, lesen Sie die Problembehandlung häufig auftretender Probleme.

Behandeln häufiger Probleme

Angelegenheit	Ursache	Auflösung
In Foundry werden keine Ablaufverfolgungen angezeigt.	Die Ablaufverfolgung ist nicht verbunden, es gibt keinen aktuellen Datenverkehr, oder die Erfassung ist verzögert.	Bestätigen Sie die Application Insights-Verbindung, generieren Sie neuen Datenverkehr, und aktualisieren Sie nach 2 bis 5 Minuten.
Es werden keine LangChain- oder LangGraph-Spans angezeigt.	Die Microsoft OpenTelemetry-Distro ist nicht initialisiert, oder die LangChain-Instrumentierung ist nicht aktiviert.	Stellen Sie sicher, dass Sie `use_microsoft_opentelemetry(...)` mit `"langchain": {"enabled": True}` aufrufen, bevor Sie Ihren Agenten ausführen.
LangChain-Abschnitte erscheinen, aber Werkzeugaufrufe fehlen.	Werkzeuge sind entweder nicht an das Modell gebunden oder der Werkzeugknoten ist nicht konfiguriert.	Stellen Sie sicher, dass Tools an `bind_tools()` auf dem Modell übergeben und Toolknoten zu Ihrem Graph hinzugefügt werden.
Ablaufverfolgungen werden angezeigt, sind jedoch unvollständig oder weisen fehlende Abschnitte auf.	Die Aufzeichnung von Inhalten ist deaktiviert, die Aktivierung der GenAI-Semantikkonvention ist nicht festgelegt, oder einige Vorgänge sind nicht instrumentiert.	Legen Sie für LangChain und LangGraph `OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT`, `OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental` und `AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true` während der Entwicklung fest. Fügen Sie für benutzerdefinierte Vorgänge manuelle Spans mithilfe des OpenTelemetry SDK hinzu.
Beim Abfragen der Telemetrie werden Autorisierungsfehler angezeigt.	Fehlende RBAC-Berechtigungen für Application Insights oder Log Analytics	Bestätigen Sie den Zugriff in access control (IAM) für die verbundenen Ressourcen. Weisen Sie für Protokollabfragen die Rolle Log Analytics Reader zu.
Sensible Inhalte werden in Ablaufverfolgungen angezeigt.	Die Inhaltsaufzeichnung ist aktiviert, und Eingabeaufforderungen, Toolargumente oder Ausgaben umfassen vertrauliche Daten.	Deaktivieren Sie die Aufzeichnung von Inhalten in der Produktion und entfernen Sie vertrauliche Daten, bevor sie in die Telemetrie eingehen.

Lernen Sie kerne Konzepte und Architektur in der Übersicht über die Agent-Ablaufverfolgung kennen.
Wenn Sie die Ablaufverfolgung noch nicht aktiviert haben, lesen Sie Ablaufverfolgung in Microsoft Foundry einrichten.
Visualisieren Sie die Agent-Zustands- und Leistungsmetriken mit dem Agent Monitoring Dashboard.
Erkunden Sie die umfassenderen Observability-Funktionen unter Observability in generativer AI.

Feedback

War diese Seite hilfreich?

Last updated on 2026-06-03

Konfigurieren der Ablaufverfolgung für KI-Agent-Frameworks (Vorschau)

Voraussetzungen

Bestätigen, dass Sie Telemetrie anzeigen können

Sicherheit und Datenschutz

Konfigurieren der Ablaufverfolgung für Microsoft Agent Framework und Semantischer Kernel

Konfigurieren Sie die Nachverfolgung mit den OpenInference-Instrumentierungsbibliotheken

Gehostete Agents (bereitgestellt in Foundry)

LangChain-Agents, die außerhalb von Foundry gehostet werden

Ablaufverfolgung für LangChain und LangGraph konfigurieren

Beispiel: LangChain v1-Agent mit Azure KI-Ablaufverfolgung

LangChain v1: Installieren von Paketen

LangChain v1: Konfigurieren der Umgebung

LangChain v1: Tracer-Setup

LangChain v1: Modellsetup (Azure OpenAI)

LangChain v1: Definieren von Tools und Eingabeaufforderungen

LangChain v1: Verwenden des Laufzeitkontexts und Definieren eines Benutzerinformationstools

LangChain v1: Erstellen des Agents

LangChain v1: Ausführen des Agents mit Ablaufverfolgung

Überprüfen Sie Ihre LangChain v1-Nachverfolgungen

Beispiel: LangGraph-Agent mit Azure AI-Ablaufverfolgung

LangGraph: Installieren von Paketen

LangGraph: Konfigurieren der Umgebung

LangGraph-Tracer-Einrichtung

LangGraph: Tools

LangGraph: Modellsetup (Azure OpenAI)

Erstellen des LangGraph-Workflows

LangGraph: Ausführen mit Ablaufverfolgung

Überprüfen Sie Ihre LangGraph-Ablaufverfolgungen

Beispiel: LangChain-Version 0.3-Setup mit Azure AI-Nachverfolgung

LangChain 0.3: Installieren von Paketen

LangChain 0.3: Konfigurieren der Umgebung

LangChain 0.3: Tracer und Modellsetup

Konfigurieren der Ablaufverfolgung für OpenAI Agents SDK

Überprüfen Sie die Ablaufverfolgungen im Foundry-Portal

Behandeln häufiger Probleme

Verwandte Inhalte

Feedback

Zusätzliche Ressourcen