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

Wenn sich KI-Agenten in der Produktion unerwartet verhalten, bietet Ihnen die Ablaufverfolgung Einblick, um schnell die Ursache zu identifizieren. Die Protokollierung erfasst detaillierte Telemetrie, einschließlich LLM-Aufrufe, Werkzeugaufrufe und Entscheidungsflüsse der Agenten, sodass Sie Probleme debuggen, Latenz überwachen und das Verhalten der Agenten über Anfragen hinweg verstehen können.

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

• Konfigurieren der automatischen Ablaufverfolgung für Microsoft Agent Framework und semantischen Kernel
• Einrichten des langchain-azure-ai Tracers für LangChain und LangGraph
• Instrumentieren des OpenAI Agents SDK mit OpenTelemetry
• Überprüfen Sie, ob Traces im Foundry-Portal angezeigt werden
• Behandeln allgemeiner Probleme bei der Ablaufverfolgung

Voraussetzungen

• Ein Foundry-Projekt mit Tracing verbunden mit Application Insights.
• 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 access zum zugeordneten Log Analytics-Arbeitsbereich.
• Python 3.10 oder höher (erforderlich für alle Codebeispiele in diesem Artikel).
• Die langchain-azure-ai Paketversion 0.1.0 oder höher (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 Ablaufverfolgungsdaten anzuzeigen, stellen Sie sicher, dass Ihr Konto Zugriff auf die verbundene Application Insights-Ressource hat.

1. Öffnen Sie im Azure portal die Application Insights-Ressource, die mit Ihrer Foundry-project verbunden ist.

2. Wählen Sie Access control (IAM) aus.

3. 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 sowie Toolargumente 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 Einstellungen wie enable_content_recording und OTEL_RECORD_CONTENT gesteuert.
• Speichern Sie keine geheimen Schlüssel, Anmeldeinformationen oder Token in Eingabeaufforderungen oder Toolargumenten.

Weitere Anleitungen finden Sie unter "Sicherheit und Datenschutz".

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

Microsoft Foundry verfügt über systemeigene Integrationen sowohl mit Microsoft Agent Framework als auch mit dem semantischen Kernel. Agents, die mit einem der beiden Frameworks erstellt wurden, geben automatisch Ablaufverfolgungen aus, wenn das Tracing für Ihr Foundry-Projekt aktiviert ist – es sind keine zusätzlichen Codes oder Paketen erforderlich.

So stellen Sie sicher, dass die Ablaufverfolgung funktioniert:

1. Führen Sie Ihren Agent mindestens einmal aus.
2. Wechseln Sie im Gießereiportal zu Observability>Traces.
3. 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 Ausführung des Agents angezeigt. Weitere Informationen zur erweiterten Konfiguration finden Sie in der frameworkspezifischen Dokumentation:

• Microsoft Agent Framework-Workflows – Observability
• Semantische Kernel-Beobachtbarkeit

Konfigurieren der Ablaufverfolgung für LangChain und LangGraph

Verwenden Sie das langchain-azure-ai-Paket, um OpenTelemetry-kompatible Spans für LangChain- und LangGraph-Vorgänge auszugeben. Diese Ablaufverfolgungen werden in der Ansicht Einblick>Ablaufverfolgungen im Foundry-Portal angezeigt.

• OpenTelemetry-Semantikkonventionen für generative KI
• langchain-azure-ai-Paket auf PyPI

Beispiel: LangChain v1-Agent mit Azure-AI-Ablaufverfolgung

Verwenden Sie dieses End-to-End-Beispiel, um einen LangChain v1 -Agent (Vorschau) mithilfe des langchain-azure-ai Tracers zu instrumentieren. Dieser Tracer implementiert die neuesten Semantikkonventionen von OpenTelemetry (OTel), sodass Sie detaillierte Traces in der Foundry Observability-Ansicht anzeigen können.

LangChain v1: Installieren von Paketen

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

LangChain v1: Konfigurieren der Umgebung

• APPLICATION_INSIGHTS_CONNECTION_STRING: Azure Monitor Application Insights Connection String 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
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]

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 Prompts

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"}, "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()

Wenn langchain-azure-ai aktiviert ist, emittieren alle LangChain v1-Vorgänge (LLM-Aufrufe, Toolaufrufe, Agentschritte) OpenTelemetry-Spannen unter Verwendung der neuesten semantischen Konventionen. Diese Ablaufverfolgungen werden in der Ansicht Einblick>Nachverfolgungen im Foundry-Portal angezeigt und sind mit Ihrer Application Insights-Ressource verknüpft.

Überprüfen Sie Ihre LangChain v1-Ablaufverfolgungen

Nach dem Ausführen des Agenten:

1. Warten Sie 2 bis 5 Minuten, bis die Spuren sich verbreiten.
2. Wechseln Sie im Gießereiportal zu Observability>Traces.
3. Suchen Sie nach einem Trace mit dem von Ihnen angegebenen Namen (z. B. "Wetterinformationsagent").
4. 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 langchain-azure-ai instrumentiert ist, um OpenTelemetry-kompatible Tracing-Informationen für Graph-Schritte, Werkzeugaufrufe und Modellaufrufe zu erzeugen.

LangGraph: Installieren von Paketen

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

LangGraph: Konfigurieren der Umgebung

• APPLICATION_INSIGHTS_CONNECTION_STRING: Azure Monitor Application Insights-Verbindungszeichenfolge für die Ablaufverfolgung.
• 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.

Einrichtung von LangGraph-Traceurs

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

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"}, "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()

Wenn langchain-azure-ai aktiviert ist, gibt Ihre LangGraph-Ausführung OpenTelemetry-kompatible Spanne für Modellaufrufe, Toolaufrufe und Diagrammübergänge aus. Diese Traces fließen zu Application Insights und erscheinen in der Einblick>Ablaufverfolgung-Ansicht im Foundry-Portal.

Überprüfen Sie Ihre LangGraph-Ablaufverfolgungen

Nach dem Ausführen des Agenten:

1. Warten Sie 2 bis 5 Minuten, bis die Spuren sich verbreiten.
2. Wechseln Sie im Gießereiportal zu Observability>Traces.
3. Suchen Sie nach einem Trace mit dem von Ihnen angegebenen Namen (z. B. "Music Player Agent").
4. 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 0.3-Setup mit Azure AI-Ablaufverfolgung

In diesem minimalen Setup wird gezeigt, wie Sie Azure AI-Tracing in einer LangChain 0.3-Anwendung mithilfe des langchain-azure-ai Tracers und AzureChatOpenAI aktivieren.

LangChain 0.3: Installieren von Paketen

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

LangChain 0.3: Konfigurieren der Umgebung

• APPLICATION_INSIGHTS_CONNECTION_STRING: Application Insights-Verbindungszeichenfolge für die Ablaufverfolgung. Um diesen Wert zu finden, öffnen Sie Ihre Application Insights-Ressource im Azure portal, wählen Sie Overview aus, und kopieren Sie die Connection String.
• 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.

LangChain 0.3: Tracer und Modellsetup

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

Befestigen Sie callbacks=[azure_tracer] an Ihren Ketten, Werkzeugen oder Agenten, um sicherzustellen, dass LangChain 0.3-Operationen nachverfolgt werden. 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 zu konfigurieren und Spans an Azure Monitor zu exportieren. Wenn APPLICATION_INSIGHTS_CONNECTION_STRING nicht gesetzt ist, greift der Exporter auf die Konsole für lokales Debugging 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

1. 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).
2. Bestätigen Sie, dass die Ablaufverfolgung für Ihr Projekt aktiviert ist. Wenn nötig, folgen Sie den Anweisungen unter Einrichten der Ablaufverfolgung in Microsoft Foundry.
3. Führen Sie Ihren Agent mindestens einmal aus.
4. Wechseln Sie im Gießereiportal zu Observability>Traces.
5. 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 Ausführung des Agents angezeigt. Wenn Ablaufverfolgungen nach diesem Zeitpunkt immer noch nicht angezeigt werden, lesen Sie die Problembehandlung häufig auftretender Probleme.

Häufige Probleme beheben

Nächste Schritte

• Lernen Sie kerne Konzepte und Architektur in der Übersicht über die Agent-Ablaufverfolgung kennen.
• Wenn Sie die Ablaufverfolgung noch nicht aktiviert haben, lesen Sie das Einrichten der Ablaufverfolgung in Microsoft Foundry.
• Visualisieren Sie die Agentengesundheits- und Leistungsmetriken mit dem Agent Monitoring Dashboard.
• Erkunden Sie die umfassenderen Observability-Funktionen in observability in generative AI.