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

In diesem Artikel erfahren Sie, wie Sie:

• Grundlegende Konzepte der Spurverfolgung
• Verfolgen und Beobachten von KI-Agenten in Foundry
• Erkunden neuer semantischer Konventionen mit Multi-Agent-Observability
• Integration in beliebte Agent-Frameworks
• Ansehen von Ablaufverfolgungen im Foundry-Portal und Azure Monitor
• Anzeigen von Agent-Threads im Agents-Playground

Es ist wichtig, die Gründe für die Ausführungen Ihres Agenten zu ermitteln, um Fehler zu beheben und zu debuggen. Es kann jedoch für komplexe Agenten aus vielen Gründen schwierig sein:

• Es kann eine hohe Anzahl von Schritten erforderlich sein, um eine Antwort zu generieren, was es schwierig macht, den Überblick zu behalten.
• Die Reihenfolge der Schritte kann je nach Eingabe der benutzenden Person variieren.
• Die Eingaben/Ausgaben in jeder Phase könnten lang sein und eine detailliertere Untersuchung verdienen.
• Jeder Schritt der Laufzeit eines Agenten kann auch eine Verschachtelung umfassen. Zum Beispiel könnte ein Agent ein Tool aufrufen, das einen anderen Prozess verwendet, der dann ein anderes Tool aufruft. Wenn Sie bei einer Agentenausführung der obersten Ebene eine seltsame oder falsche Ausgabe bemerken, kann es schwierig sein, genau zu bestimmen, an welcher Stelle der Ausführung das Problem aufgetreten ist.

Die Ablaufverfolgungsergebnisse lösen dies, indem Sie die Eingaben und Ausgaben der einzelnen Grundtypen anzeigen können, die an einer bestimmten Agentausführung beteiligt sind, die in der Reihenfolge angezeigt wird, in der sie aufgerufen wurden, wodurch das Verhalten Ihres KI-Agents leicht zu verstehen und zu debuggen ist.

Übersicht über die Schlüsselkonzepte der Nachverfolgung

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

Bewährte Methoden

• Verwenden Sie konsistente Span-Attribute.
• Korrelieren von IDs der Auswertungsdurchführung für die Analyse von Qualität und Leistung.
• Vertrauliche Inhalte bearbeiten; vermeiden Sie, geheime Informationen in Attributen zu speichern.

Erweitern von OpenTelemetry mit Multi-Agent-Observability

Microsoft verbessert die Mehr-Agent-Observierbarkeit durch die Einführung neuer semantischer Konventionen in OpenTelemetry, die gemeinsam mit Outshift, dem Inkubationsmodul von Cisco entwickelt wurde. Diese Ergänzungen – basierend auf OpenTelemetry und W3C Trace Context – richten standardisierte Methoden für die Ablaufverfolgung und Telemetrie innerhalb von Multi-Agent-Systemen ein, wodurch eine konsistente Protokollierung wichtiger Metriken für Qualität, Leistung, Sicherheit und Kosten ermöglicht wird. Dieser systematische Ansatz ermöglicht einen umfassenderen Einblick in Multi-Agent-Workflows, einschließlich Toolaufrufe und Zusammenarbeit. Diese Fortschritte wurden in Microsoft Foundry, Microsoft Agent Framework, Semantic Kernel und Azure AI-Pakete für LangChain, LangGraph und das OpenAI Agents SDK integriert, sodass Kunden einheitliche Observierbarkeit für agentische Systeme erhalten können, die mit einem dieser Frameworks mit Foundry erstellt wurden. Erfahren Sie mehr über Nachverfolgungsintegrationen.

Einrichten der Ablaufverfolgung im Microsoft Foundry SDK

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

pip install azure-ai-projects azure-identity

Zum Instrumentieren der Ablaufverfolgung müssen Sie die folgenden Instrumentierungsbibliotheken installieren:

pip install azure-monitor-opentelemetry opentelemetry-sdk

Um Traces in Foundry anzuzeigen, müssen Sie eine Application Insights-Ressource mit Ihrem Foundry-Projekt verbinden.

1. Navigieren Sie im linken Navigationsbereich des Foundry-Portals zu Tracing.
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). Denken Sie daran, dass dies personenbezogene Daten enthalten kann. Weitere Informationen finden Sie in der Azure Core Tracing OpenTelemetry-Clientbibliothek für Python.

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

Beginnen Sie zunächst mit der Instrumentierung Ihres Agents mit der OpenTelemetry-Ablaufverfolgung, indem Sie Ihr Azure KI-Projekt mit AIProjectClient authentifizieren und verbinden.

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, sodass Sie detaillierte Schritte zur Problembehandlung 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 dem Anzeigen von Ablaufverfolgungen im Foundry-Portal beginnen.

Lokales Protokollieren von Ablaufverfolgungen

Um eine Verbindung mit dem Aspire Dashboard oder einem anderen mit OpenTelemetry kompatiblen Back-End herzustellen, installieren Sie den OpenTelemetry Protocol (OTLP)-Exporter. Dadurch können Sie Ablaufverfolgungen in 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 als Nächstes die Ablaufverfolgung für die Konsolenausgabe:

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 obigen Code basierend auf dem Aspire-Dashboard, um die Ablaufverfolgung an einen lokalen OTLP-Viewer zu leiten.

Aktivieren Sie jetzt die Agenteninstrumentierung, und führen Sie Ihren Agenten 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: KI-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. In VS Code können Sie Spuren sofort anzeigen, ohne Cloudzugriff zu benötigen.

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. Ablaufverfolgungsanbieter einrichten: Initialisieren Sie einen Ablaufverfolgungsanbieter zum Verwalten und Erstellen von Spans.
2. Spans erstellen: Umschließen Sie den Code, den Sie nachverfolgen möchten, mit Spans. Jeder Bereich stellt eine Arbeitseinheit dar und kann geschachtelt werden, um eine Ablaufverfolgungsstruktur zu bilden.
3. Attribute hinzufügen: Spannen 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 Informationen zur erweiterten Verwendung finden Sie in der OpenTelemetry-Dokumentation.

Anfügen von Benutzerfeedback an Ablaufverfolgungen

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

Indem Sie Feedback-Traces mit den jeweiligen Chatanfrage-Traces über die Antwort-ID oder Thread-ID korrelieren, können Sie diese Traces im Foundry-Portal sehen und verwalten. Die Spezifikation von OpenTelemetry ermöglicht standardisierte und angereicherte Ablaufverfolgungsdaten, die im Foundry-Portal für Leistungsoptimierung und Erkenntnisse zur Benutzererfahrung analysiert werden können. Dieser Ansatz hilft Ihnen, die volle Leistungsfähigkeit von OpenTelemetry für einen verbesserten Einblick in Ihre Anwendungen zu nutzen.

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

Das Bewertungsereignis des Benutzers kann nur erfasst werden, wenn der Benutzer eine Reaktion auf die GenAI-Modellantwort bereitgestellt hat. Es sollte, wenn möglich, der GenAI-Bereich zugeordnet werden, der eine solche Antwort beschreibt.

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

Verwenden des Dienstnamens in Ablaufverfolgungsdaten

Um Ihren Dienst über eine eindeutige ID in Application Insights zu identifizieren, können Sie die OpenTelemetry-Eigenschaft für den Dienstnamen in Ihren Ablaufverfolgungsdaten verwenden. Dies 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.

Sie können die Dienstnameneigenschaft direkt in Ihrem Anwendungscode einrichten, indem Sie die Schritte unter Using multiple tracer providers with different Resource (Verwenden mehrerer Ablaufverfolgungsanbieter mit unterschiedlichen Ressourcen) ausführen. Alternativ können Sie die Umgebungsvariable OTEL_SERVICE_NAME vor der Bereitstellung Ihrer App festlegen. Weitere Informationen zur Verwendung des Dienstnamens finden Sie unter OTEL Environment Variables (OTEL-Umgebungsvariablen) und Service Resource Semantic Conventions (Semantische Konventionen für Dienstressourcen).

Wenn Sie Ablaufverfolgungsdaten für einen bestimmten Dienstnamen abfragen möchten, fragen Sie die cloud_roleName-Eigenschaft ab.

| where cloud_RoleName == "service_name"

Integrationen

Foundry erleichtert das Protokollieren von Ablaufverfolgungen mit minimalen Änderungen durch die Integration von Ablaufverfolgungen in Microsoft Agent Framework, Semantic Kernel, LangChain, LangGraph und OpenAI Agent SDK.

Ablaufverfolgungs-Agents, die auf dem Microsoft Agent Framework und Semantic Kernel basieren

Foundry verfügt über systemeigene Integrationen in Microsoft Agent Framework und semantischen Kernel. Agents, die auf diesen beiden Frameworks basieren, erhalten eine sofort einsetzbare Ablaufverfolgung in Foundry Observability.

• Erfahren Sie mehr über die Ablaufverfolgung und Beobachtbarkeit in Semantic Kernel und Microsoft Agent Framework.

Aktivierung von Tracing für Agenten, die auf LangChain und LangGraph basieren

Sie können das Tracing für LangChain aktivieren, das OpenTelemetry Standards gemäß opentelemetry-instrumentation-langchain folgt.

Sobald die erforderlichen Pakete installiert sind, können Sie ganz einfach mit der Instrumentablaufverfolgung in Ihrem Code beginnen.

Beispiel: LangChain v1-Agent mit Azure AI-Ablaufverfolgung

Verwenden Sie dieses End-to-End-Beispiel, um einen LangChain v1-Agenten mit dem Tracer langchain-azure-ai zu instrumentieren, der die neueste OpenTelemetry (OTel)-Spezifikation implementiert, sodass Sie umfangreiche Traces im Einblick anzeigen können.

Pakete installieren

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 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. .
• Azure-Zugangsdaten werden über DefaultAzureCredential aufgelöst (dies unterstützt Umgebungsvariablen, verwaltete Identität, VS Code-Anmeldung usw.).

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

Tracer-Konfiguration

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]

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

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

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

Mit langchain-azure-ai aktivierter Funktion werden alle LangChain v1-Vorgänge (LLM-Aufrufe, Toolaufrufe, Agentschritte) mithilfe der neuesten Semantikkonventionen von OpenTelemetry nachverfolgt und in Observability angezeigt, die mit Ihrer Application Insights-Ressource verknüpft sind.

Beispiel: LangGraph-Agent mit Azure AI-Ablaufverfolgung

Dieses Beispiel zeigt einen einfachen LangGraph-Agent, der mit langchain-azure-ai ausgestattet ist, um OpenTelemetry-kompatible Ablaufverfolgungen für Graph-Schritte, Toolaufrufe und Modellaufrufe auszugeben.

Pakete installieren

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

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

Tracer-Konfiguration

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]

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://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)

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 Spannen für Modellaufrufe, Toolaufrufe und Graph-Übergänge aus. Diese Traces fließen zu Application Insights und werden in Observability angezeigt.

Beispiel: LangChain 0.3-Setup mit Azure AI-Ablaufverfolgung

Dieses minimale Setup zeigt, wie Sie mithilfe von langchain-azure-ai und AzureChatOpenAI die Azure AI-Ablaufverfolgung in einer LangChain 0.3-Anwendung aktivieren können.

Pakete installieren

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

Konfigurieren der Umgebung

• APPLICATION_INSIGHTS_CONNECTION_STRING: Application Insights-Verbindungszeichenfolge für die Nachverfolgung.
• 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] zu Ihren Ketten, Tools oder Agenten hinzu, um sicherzustellen, dass LangChain 0.3-Vorgänge nachverfolgt werden und im Einblick sichtbar sind.

Ablaufverfolgung für auf dem OpenAI-Agents-SDK basierende Agenten aktivieren

Verwenden Sie diesen Code-Snippet, um die OpenTelemetry-Ablaufverfolgung für das OpenAI Agents SDK zu konfigurieren und das Framework zu instrumentieren. Wenn APPLICATION_INSIGHTS_CONNECTION_STRING gesetzt ist, wird er in Azure Monitor exportiert. Andernfalls fällt er auf die Konsole zurück.

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 Ablaufverfolgungen im Foundry-Portal

Navigieren Sie in Ihrem Projekt zu Ablaufverfolgung, um Ihre Ablaufverfolgungen nach Bedarf zu filtern.

Indem Sie eine Ablaufverfolgung auswählen, können Sie jedes Intervall durchlaufen und Probleme ermitteln und dabei beobachten, wie Ihre Anwendung reagiert. Auf diese Weise können Sie Probleme in Ihrer Anwendung debuggen und anheften.

Anzeigen von Ablaufverfolgungen in Azure Monitor

Wenn Sie Ablaufverfolgungen mithilfe des vorherigen Codeschnipsels protokolliert haben, können Sie Ihre Ablaufverfolgungen auch in Azure Monitor Application Insights anzeigen. Sie können Application Insights aus der Verwaltung der Datenquelle öffnen und die End-to-End-Transaktionsdetailansicht verwenden, um weiter zu untersuchen.

Weitere Informationen zum Senden von Azure KI Inference-Ablaufverfolgungen an Azure Monitor und zum Erstellen der Azure Monitor-Ressource finden Sie in der Dokumentation zu Azure Monitor OpenTelemetry.

Anzeigen von Threadergebnissen im Foundry-Agents-Playground

Mit der Agents-Umgebung im Foundry-Portal können Sie Ergebnisse für Threads und Ausführungen anzeigen, die Ihre Agents generieren. 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
• Ausführen von Informationen
• Sortierte Ausführungsschritte und Toolaufrufe
• Eingaben und Ausgaben zwischen Benutzer und Agent
• Verknüpfte Auswertungsmetriken (sofern aktiviert)

Verwandte Inhalte

• Python-Beispiele mit vollständig ausführbarem Python-Code für die Ablaufverfolgung mithilfe synchroner und asynchroner Clients
• Python-Beispiele für Tracing-Agenten mit Konsolen-Tracing und Azure Monitor
• JavaScript-Beispiele mit vollständig ausgeführtem JavaScript-Code für die Ablaufverfolgung mithilfe synchroner und asynchroner Clients
• C#-Beispiele mit vollständig ausgeführtem C#-Code für den Rückschluss mithilfe synchroner und asynchroner Methoden