Verfolgen und Beobachten von KI-Agents in Microsoft Foundry (Vorschau) (klassisch)

Gilt nur für:klassisches Foundry Portal. Dieser Artikel ist für das neue Foundry-Portal nicht verfügbar. Erfahren Sie mehr über das neue Portal.

In diesem Artikel erfahren Sie, wie Sie:

• Grundlegende Konzepte der Nachverfolgung.
• Verfolgen und beobachten Sie KI-Agenten in Foundry.
• Erkunden Sie neue semantische Konventionen mit mehrstufiger Observierbarkeit.
• Integration in beliebte Agent-Frameworks.
• Ablaufverfolgungen im Foundry-Portal und Azure Monitor anzeigen.
• Anzeigen von Agentthreads im Agents-Playground.

Die Ermittlung der Gründe für die Ausführung Ihres Agents ist wichtig für die Fehlerbehebung und das Debugging. Es kann jedoch für komplexe Agenten aus vielen Gründen schwierig sein:

• Es könnte eine hohe Anzahl von Schritten zur Erstellung einer Antwort geben, was es schwierig macht, alle nachzuverfolgen.
• Die Reihenfolge der Schritte kann je nach Benutzereingabe variieren.
• Die Eingaben und Ausgaben in jeder Phase können lang sein und eine detailliertere Inspektion verdienen.
• Jeder Schritt der Laufzeit eines Agenten kann auch Verschachtelungen umfassen. Beispielsweise kann ein Agent ein Tool aufrufen, das einen anderen Prozess verwendet, der dann ein anderes Tool aufruft. Wenn Ihnen eine seltsame oder falsche Ausgabe bei der Ausführung eines Top-Level-Agenten auffällt, kann es schwierig sein, genau zu bestimmen, wo in der Ausführung das Problem eingeführt wurde.

Mithilfe von Ablaufverfolgungsergebnissen lässt sich dieses Problem lösen, indem die Ein- und Ausgaben jedes an einem bestimmten Agentendurchlauf beteiligten Primitives angezeigt werden können. Die Ergebnisse werden in der Reihenfolge angezeigt, in der die Grundtypen aufgerufen werden, wodurch das Verhalten Ihres KI-Agents leicht zu verstehen und zu debuggen ist.

Übersicht über die Schlüsselkonzepte des Tracing

Hier ist eine kurze Übersicht über die wichtigsten Konzepte vor den ersten Schritten:

Bewährte Methoden

• Verwenden Sie konsistente Span-Attribute.
• Korrelieren von Auswertungsausführungs-IDs für die Qualitäts- und Leistungsanalyse.
• Vertrauliche Inhalte redigieren. Vermeiden Sie das Speichern geheimer Schlüssel in Attributen.

Erweitern von OpenTelemetry mit Multi-Agent-Observability

Microsoft verbessert die Mehr-Agent-Observierbarkeit durch die Einführung neuer semantischer Konventionen für OpenTelemetry, die gemeinsam mit outshift, ciscos Inkubationsmodul entwickelt wurde. Diese Ergänzungen, basierend auf OpenTelemetry und W3C Trace Context, etablieren standardisierte Verfahren für Tracing und Telemetrie in Multi-Agenten-Systemen. Sie erleichtern die konsistente Protokollierung wichtiger Metriken für Qualität, Leistung, Sicherheit und Kosten. Dieser systematische Ansatz ermöglicht einen umfassenderen Einblick in Multi-Agent-Workflows, einschließlich Toolaufrufe und Zusammenarbeit. Microsoft diese Fortschritte in Microsoft Foundry, Microsoft Agent Framework, Semantischer Kernel und Azure AI-Pakete für LangChain, LangGraph und das OpenAI Agents SDK integriert. Mithilfe von Foundry können Kunden einheitliche Observability für agentische Systeme erhalten, die mit einem dieser Frameworks erstellt wurden. Erfahren Sie mehr über Tracing-Integrationen.

Einrichten der Ablaufverfolgung im Microsoft Foundry SDK

Installieren Sie für Chat-Vervollständigungen oder das Erstellen von Agenten mit Foundry:

pip install azure-ai-projects azure-identity

Um die Ablaufverfolgung vorzubereiten, installieren Sie die folgenden Instrumentierungsbibliotheken:

pip install azure-monitor-opentelemetry opentelemetry-sdk

Um Ablaufverfolgungen in Foundry anzuzeigen, verbinden Sie eine Application Insights-Ressource mit Ihrem Foundry-Projekt.

1. Gehen Sie im linken Navigationsbereich des Foundry-Portals zu Ablaufverfolgung.
2. Erstellen Sie eine neue Application Insights-Ressource, wenn Sie noch nicht über eine Ressource verfügen.
3. Verbinden Sie die Ressource mit Ihrem Foundry-Projekt.

Instrumentablaufverfolgung in Ihrem Code

Um den Inhalt von Chatnachrichten nachzuverfolgen, legen Sie die AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED Umgebungsvariable auf "true" fest (Groß-/Kleinschreibung wird nicht beachtet). Dieser Inhalt kann personenbezogene Daten enthalten. Weitere Informationen finden Sie unter Azure Core Tracing OpenTelemetry-Clientbibliothek für Python.

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

Beginnen wir mit der Instrumentierung unseres Agenten zur OpenTelemetry-Ablaufverfolgung, indem wir uns zunächst bei Ihrem Azure AI-Projekt authentifizieren und verbinden, indem wir AIProjectClient verwenden.

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

Rufen Sie als Nächstes die Verbindungszeichenfolge aus der Application Insights-Ressource ab, die mit Ihrem Projekt verbunden ist, und richten Sie die OTLP-Exporter ein, um Telemetrie an Azure Monitor zu senden.

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

Verfolgen Sie nun Ihren Code, in dem Sie Ihren Agent und Ihre Benutzernachricht in Ihrem Azure-AI-Projekt erstellen und ausführen, damit Sie detaillierte Schritte zur Fehlerbehebung oder Überwachung sehen können.

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)

Nachdem Sie Ihren Agent ausgeführt haben, können Sie mit der Anzeige von Ablaufverfolgungen im Foundry-Portal beginnen.

Ablaufverfolgungen lokal protokollieren

Um eine Verbindung mit dem Aspire Dashboard oder einem anderen mit OpenTelemetry kompatiblen Back-End herzustellen, installieren Sie den OpenTelemetry Protocol (OTLP)-Exporter. Mithilfe dieses Exporters können Sie Ablaufverfolgungen auf der Konsole drucken oder einen lokalen Viewer wie das Aspire Dashboard verwenden.

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

Konfigurieren Sie die Ablaufverfolgung für die Konsolenausgabe als nächsten Schritt:

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)

Oder ändern Sie den vorherigen Code, basierend auf das Aspire Dashboard, um ihn in einem lokalen OTLP-Betrachter darzustellen.

Aktivieren Sie jetzt die Instrumentierung des Agenten und führen Sie Ihren Agent aus.

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)

Alternative: AI Toolkit für VS Code

Das AI-Toolkit bietet Ihnen eine einfache Möglichkeit, lokal in VS Code nachzuverfolgen. Es verwendet einen lokalen OTLP-kompatiblen Sammler, sodass er ideal für Entwicklung und Debugging geeignet ist.

Das Toolkit unterstützt KI-Frameworks wie Foundry Agents Service, OpenAI, Anthropic und LangChain über OpenTelemetry. Sie können Traces sofort in VS Code sehen, ohne auf die Cloud zugreifen zu müssen.

Ausführliche Einrichtungsanweisungen und SDK-spezifische Codebeispiele finden Sie unter "Tracing in AI Toolkit".

Nachverfolgen benutzerdefinierter Funktionen

Verwenden Sie zum Nachverfolgen Ihrer benutzerdefinierten Funktionen das OpenTelemetry SDK, um Ihren Code zu instrumentieren.

1. Richten Sie einen Tracer-Anbieter ein: Initialisieren Sie einen Tracer-Anbieter, um Spans zu verwalten und zu erstellen.
2. Erstellen Sie Spans: Umschließen Sie den Code, den Sie nachverfolgen möchten, mit Spans. Jede Spanne stellt eine Arbeitseinheit dar, und Sie können Spannen verschachteln, um einen Trace-Baum zu bilden.
3. Attribute hinzufügen: Spans mit Attributen anreichern, um mehr Kontext für die Ablaufverfolgungsdaten bereitzustellen.
4. Konfigurieren eines Exporters: Senden Sie die Ablaufverfolgungsdaten an ein Back-End zur Analyse und Visualisierung.

Hier ist ein Beispiel für die Ablaufverfolgung einer benutzerdefinierten Funktion:

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

Ausführliche Anweisungen und erweiterte Verwendung finden Sie in der OpenTelemetry-Dokumentation.

Benutzerfeedback an Traces anfügen

Um Benutzerfeedback an Ablaufverfolgungen anzufügen und sie im Foundry-Portal zu visualisieren, instrumentieren Sie Ihre Anwendung, um das Ablaufverfolgungs- und Protokollieren von Benutzerfeedback mithilfe der semantischen Konventionen von OpenTelemetry zu ermöglichen.

Indem Sie Feedbackablaufverfolgungen mit ihren jeweiligen Chatanfrageablaufverfolgungen mithilfe der Antwort-ID oder Thread-ID korrelieren, können Sie diese Ablaufverfolgungen im Foundry-Portal anzeigen und verwalten. Die Spezifikation von OpenTelemetry ermöglicht standardisierte und angereicherte Ablaufverfolgungsdaten, die Sie im Foundry-Portal auf Leistungsoptimierung und Einblicke in die Benutzererfahrung analysieren können. Dieser Ansatz hilft Ihnen, die volle Leistungsfähigkeit von OpenTelemetry für eine verbesserte Observierbarkeit in Ihren Anwendungen zu nutzen.

Gehen Sie wie folgt vor, um Das Feedback des Benutzers zu protokollieren:

Das Benutzerfeedback-Auswertungsereignis wird nur erfasst, wenn der Benutzer eine Reaktion auf die GenAI-Modellantwort bereitstellt. Wenn möglich, ordnen Sie dieses Ereignis dem GenAI-Bereich zu, der die jeweilige Antwort beschreibt.

Der Textkörper des Benutzerfeedbackereignisses weist die folgende Struktur auf:

Verwendung des Dienstnamens in Trace-Daten

Um Ihren Dienst über eine eindeutige ID in Application Insights zu identifizieren, verwenden Sie die OpenTelemetry-Eigenschaft des Dienstnamens in Ihren Ablaufverfolgungsdaten. Diese Eigenschaft ist nützlich, wenn Sie Daten aus mehreren Anwendungen in derselben Application Insights-Ressource protokollieren und zwischen diesen unterscheiden möchten.

Angenommen, Sie haben zwei Anwendungen: App-1 und App-2, wobei die Ablaufverfolgung so konfiguriert ist, dass Daten in derselben Application Insights-Ressource protokolliert werden. Vielleicht möchten Sie App-1 so einrichten, dass sie kontinuierlich von Relevanz und App-2 ausgewertet wird, um kontinuierlich von Relevanz ausgewertet zu werden. Sie können den Dienstnamen verwenden, um nach Application zu filtern, wenn Sie Ihre Anwendung im Foundry-Portal überwachen.

Um die Dienstnameneigenschaft einzurichten, fügen Sie sie direkt in Ihrem Anwendungscode hinzu, indem Sie die Schritte im Abschnitt Verwendung mehrerer Tracer-Anbieter mit unterschiedlichen Ressourcen ausführen. Alternativ können Sie die Umgebungsvariable OTEL_SERVICE_NAME festlegen, bevor Sie Ihre App bereitstellen. Weitere Informationen zum Arbeiten mit dem Dienstnamen finden Sie unter OTEL Environment Variables and Service Resource Semantic Conventions.

Um Ablaufverfolgungsdaten zu einem bestimmten Dienstnamen abzufragen, fragen Sie die Eigenschaft cloud_roleName ab.

| where cloud_RoleName == "service_name"

Integrationen

Foundry erleichtert das Protokollieren von Traces und erfordert dabei nur minimale Änderungen durch seine Tracing-Integrationen mit Microsoft Agent Framework, Semantischer Kernel, LangChain, LangGraph und OpenAI Agent SDK.

Ablaufverfolgungsagenten, die auf dem Microsoft Agent Framework und Semantischer Kernel basieren

Foundry verfügt über systemeigene Integrationen mit Microsoft Agent Framework und Semantischer Kernel. Agents, die auf diesen beiden Frameworks basieren, erhalten ab Werk Tracing zur Überwachungsfähigkeit.

• Erfahren Sie mehr über die Ablaufverfolgung und Observierbarkeit in Semantischer Kernel und Microsoft Agent Framework.

Aktivieren der Ablaufverfolgung für Agents, die auf LangChain und LangGraph basieren

Sie können die Ablaufverfolgung für LangChain aktivieren, die den OpenTelemetry-Standards entspricht, gemäß opentelemetry-instrumentation-langchain.

Nachdem Sie die erforderlichen Pakete installiert haben, können Sie die Ablaufverfolgung ganz einfach in Ihren Code einfügen.

Beispiel: LangChain v1-Agent mit Azure AI-Ablaufverfolgung

Verwenden Sie dieses End-to-End-Beispiel, um einen LangChain v1-Agent mithilfe des langchain-azure-ai Tracers zu instrumentieren. Es implementiert die neueste OpenTelemetry (OTel)-Spezifikation, sodass Sie umfangreiche Traces in Observability anzeigen können.

Installieren von Paketen

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

Konfigurieren der Umgebung

• APPLICATION_INSIGHTS_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. .
• Azure Anmeldeinformationen werden über DefaultAzureCredential aufgelöst (unterstützt Umgebungsvariablen, verwaltete Identität, VS Code-Anmeldung und vieles mehr).

Sie können diese Werte in einer .env Datei für die lokale Entwicklung speichern.

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]

Modelleinrichtung (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.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,
)

Tools und Eingabeaufforderungen definieren

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

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]

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

Starten Sie den Agenten 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 Sie aktivieren langchain-azure-ai, werden alle LangChain v1-Vorgänge (LLM-Aufrufe, Toolaufrufe, Agentschritte) mithilfe der neuesten OpenTelemetry-Semantikkonventionen nachverfolgt. Sie wird in Observability angezeigt, die mit Ihrer Application Insights-Ressource verknüpft ist.

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 für Diagrammschritte, Toolaufrufe und Modellaufrufe auszugeben.

Installieren von Paketen

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

Konfigurieren der Umgebung

• APPLICATION_INSIGHTS_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. .

Sie können diese Werte in einer .env Datei für die lokale Entwicklung speichern.

Tracer-Einrichtung

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

Werkzeuge

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]

Modellkonfiguration (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://ai.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)

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

Durch das Aktivieren von langchain-azure-ai gibt Ihre LangGraph-Ausführung OpenTelemetry-kompatible Spans für Modellaufrufe, Toolaufrufe und Diagrammübergänge aus. Diese Ablaufverfolgungen fließen zu Application Insights und erscheinen in Observability.

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

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

Installieren von Paketen

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

Konfigurieren der Umgebung

• APPLICATION_INSIGHTS_CONNECTION_STRING: Application Insights-Verbindungszeichenfolge zur Ablaufverfolgung.
• 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.

Tracer- und Modellkonfiguration

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

Fügen Sie callbacks=[azure_tracer] an Ihre Ketten, Tools oder Agents an, um sicherzustellen, dass LangChain 0.3-Vorgänge nachverfolgt und in Observability sichtbar sind.

Tracing aktivieren für Agents, die auf dem OpenAI Agents SDK basieren.

Installieren Sie die erforderlichen Pakete:

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

Verwenden Sie diesen Codeausschnitt, um das OpenTelemetry-Tracing für das OpenAI Agents SDK zu konfigurieren und das Framework zu instrumentieren. Sie wird in Azure Monitor exportiert, wenn APPLICATION_INSIGHTS_CONNECTION_STRING festgelegt ist. Andernfalls wird sie auf die Konsole zurückgesetzt.

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

Anzeigen von Traces im Foundry-Portal

Navigieren Sie in Ihrem Projekt zu Tracing, um Ihre Ablaufverfolgungen nach Belieben zu filtern.

Indem Sie eine Tracierung auswählen, können Sie jeden Abschnitt durchlaufen und Probleme identifizieren, während Sie beobachten, wie Ihre Anwendung reagiert. Dieser Prozess hilft Ihnen beim Debuggen und Anheften von Problemen in Ihrer Anwendung.

Anzeigen von Ablaufverfolgungen in Azure Monitor

Wenn Sie Ablaufverfolgungen mithilfe des vorherigen Codeausschnitts protokolliert haben, können Sie Ihre Ablaufverfolgungen jetzt in Azure Monitor Application Insights ansehen. Sie können Application Insights aus der Datenquelle verwalten öffnen und die Detailansicht der End-to-End-Transaktion verwenden, um weitere Untersuchungen durchzuführen.

Weitere Informationen darüber, wie Sie Azure AI Inferenzspuren an Azure Monitor senden und eine Azure Monitor Ressource erstellen, finden Sie in der Dokumentation Azure Monitor OpenTelemetry.

Anzeigen von Thread-Ergebnissen im Foundry Agents Playground

Mit dem Agents-Playground im Foundry-Portal können Sie Ergebnisse für Threads und Runs anzeigen, die Ihre Agents produzieren. Um Threadergebnisse anzuzeigen, wählen Sie Threadprotokolle in einem aktiven Thread aus. Optional können Sie auch Metriken auswählen, um automatische Auswertungen der Leistung des Modells in mehreren Dimensionen von KI-Qualität und Risiko und Sicherheit zu ermöglichen.

Überprüfen Sie nach der Auswahl von Threadprotokollen Folgendes:

• Threaddetails
• Laufinformationen
• Sortierte Ausführungsschritte und Toolaufrufe
• Eingaben und Ausgaben zwischen Benutzer und Agent
• Verknüpfte Auswertungsmetriken (sofern aktiviert)

Verwandte Inhalte

• Python samples, die vollständig ausführbaren Python-Code zum Tracing enthalten, indem synchroner und asynchroner Clients verwendet werden.
• Python-Beispiele für Tracing-Agents mit Konsole und Azure Monitor
• JavaScript-Beispiele mit funktionsfähigem JavaScript-Code für die Nachverfolgung unter Verwendung von synchronen und asynchronen Clients.
• C#-Beispiele enthalten vollständig ausgeführten C#-Code für die Ableitung mithilfe synchroner und asynchroner Methoden.