Tracering configureren voor AI-agentframeworks (preview)

Wanneer AI-agents zich onverwacht gedragen in productie, biedt tracering u de zichtbaarheid om snel de hoofdoorzaak te identificeren. Tracering legt gedetailleerde telemetrie vast, waaronder LLM-aanroepen, aanroepen van hulpprogramma's en beslissingsstromen van agents, zodat u problemen kunt opsporen, latentie kunt bewaken en het gedrag van agents tussen aanvragen kunt begrijpen.

Microsoft Foundry biedt traceringsintegraties voor populaire agentframeworks waarvoor minimale codewijzigingen zijn vereist. In dit artikel leert u het volgende:

• Automatische tracering configureren voor Microsoft Agent Framework
• De langchain-azure-ai tracer instellen voor LangChain en LangGraph
• Instrumenteer de OpenAI Agents SDK met OpenTelemetry
• Controleer of de traceringen worden weergegeven in het Foundry-portal
• Veelvoorkomende traceringsproblemen oplossen

Voorwaarden

• Een Foundry-project met tracering die verbonden is met Azure Monitor Application Insights.
• Inzender of hogere rol voor de Application Insights-resource voor traceringsopname.
• Toegang tot de verbonden Application Insights-resource voor het weergeven van traceringen. Voor query's op basis van logboeken hebt u mogelijk ook toegang nodig tot de bijbehorende Log Analytics werkruimte.
• Python 3.10 of hoger (vereist voor alle codevoorbeelden in dit artikel).
• De langchain-azure-ai pakketversie 0.1.0 of hoger (vereist voor LangChain- en LangGraph-voorbeelden).
• Als u LangChain of LangGraph gebruikt, is er een Python-omgeving met pip geïnstalleerd.

Bevestigen dat u telemetrie kunt bekijken

Als u traceringsgegevens wilt weergeven, moet u ervoor zorgen dat uw account toegang heeft tot de verbonden Application Insights-resource.

1. Open in de Azure-portal de Application Insights-resource die is verbonden met uw Foundry-project.

2. Selecteer Toegangsbeheer (IAM).

3. Wijs een geschikte rol toe aan uw gebruiker of groep.

   Als u query's op basis van logboeken gebruikt, geeft u eerst de rol Log Analytics Lezer.

Beveiliging en privacy

Tracering kan gevoelige informatie vastleggen (bijvoorbeeld gebruikersinvoer, modeluitvoer en hulpprogrammaargumenten en resultaten).

• Schakel inhoudsopname in tijdens de ontwikkeling en foutopsporing om volledige aanvraag- en antwoordgegevens weer te geven. Schakel inhoudsopname uit in productieomgevingen om gevoelige gegevens te beveiligen. In de voorbeelden in dit artikel wordt inhoudsopname beheerd door instellingen zoals enable_content_recording en OTEL_RECORD_CONTENT.
• Sla geen geheimen, inloggegevens of tokens op in prompts of toolargumenten.

Zie Beveiliging en privacy voor meer informatie.

Tracering configureren voor Microsoft Agent Framework

Microsoft Foundry heeft systeemeigen integraties met zowel Microsoft Agent Framework. Agents die zijn gebouwd met een framework verzenden automatisch traceringen wanneer tracering is ingeschakeld voor uw Foundry-project. Er zijn geen extra code of pakketten vereist.

Controleren of tracering werkt:

1. Voer uw agent minstens één keer uit.
2. Ga in de Foundry-portal naar Observability>Traces.
3. Controleer of er een nieuwe trace verschijnt met reikwijdtes voor de taken van uw agent.

Traceringen worden doorgaans binnen 2-5 minuten na de uitvoering van de agent weergegeven. Zie de frameworkspecifieke documentatie voor geavanceerde configuratie:

• Microsoft Agent Framework-werkstromen : waarneembaarheid

Tracering configureren voor LangChain en LangGraph

Gebruik het langchain-azure-ai package om OpenTelemetry-compatibele spans te genereren voor LangChain- en LangGraph-bewerkingen. Deze traceringen worden weergegeven in de weergave Observability>Traces in de Foundry-portal.

• Semantische openTelemetry-conventies voor generatieve AI
• langchain-azure-ai-pakket in PyPI

Voorbeeld: LangChain v1-agent met Azure AI-tracering

Gebruik dit end-to-end-sample om een LangChain v1 preview-agent te instrumenteren met behulp van de langchain-azure-ai tracer. Met deze tracer worden de nieuwste Semantische conventies van OpenTelemetry (OTel) geïmplementeerd, zodat u uitgebreide traceringen kunt bekijken in de weergave Waarneembaarheid van Foundry.

LangChain v1: Pakketten installeren

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

LangChain v1: omgeving configureren

• APPLICATION_INSIGHTS_CONNECTION_STRING: Azure Monitor Application Insights-connectionstring voor tracering.
• AZURE_OPENAI_ENDPOINT: de EINDPUNT-URL van uw Azure OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: de naam van de implementatie van het chatmodel.
• AZURE_OPENAI_VERSION: API-versie, bijvoorbeeld 2024-08-01-preview.
• De SDK lost Azure referenties op met behulp van DefaultAzureCredential, die ondersteuning biedt voor omgevingsvariabelen, beheerde identiteit en VS Code-aanmelding.

Sla deze waarden op in een .env bestand voor lokale ontwikkeling.

LangChain v1: Tracer-installatie

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: Model setup (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,
)

LangChain v1: Hulpmiddelen en prompts definiëren

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: Runtime-context gebruiken en een hulpprogramma voor gebruikersgegevens definiëren

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: De agent maken

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: De agent uitvoeren met tracering

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

Met langchain-azure-ai ingeschakeld verzenden alle LangChain v1-bewerkingen (LLM-aanroepen, aanroepen van hulpprogramma's, agentstappen) OpenTelemetry spans met behulp van de nieuwste semantische conventies. Deze traceringen worden weergegeven in de weergaveWaarneembaarheidstraceringen> in de Foundry-portal en zijn gekoppeld aan uw Application Insights-resource.

Uw LangChain v1-traceringen controleren

Nadat de agent is uitgevoerd:

1. Wacht 2-5 minuten totdat traces zijn doorgekomen.
2. Ga in de Foundry-portal naar Observability>Traces.
3. Zoek naar een tracering met de naam die u hebt opgegeven (bijvoorbeeld 'Weerinformatieagent').
4. Vouw de tracering uit om reeksen voor LLM-oproepen, hulpprogramma-aanroepen en agentstappen te bekijken.

Als u geen traceringen ziet, raadpleegt u de sectie Veelvoorkomende problemen oplossen .

Voorbeeld: LangGraph-agent met Azure AI-tracering

In dit voorbeeld ziet u een eenvoudige LangGraph-agent die is geïnstrueerd om langchain-azure-ai openTelemetry-compatibele traceringen te verzenden voor grafiekstappen, hulpprogrammaaanroepen en modelaanroepen.

LangGraph: Pakketten installeren

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

LangGraph: omgeving configureren

• APPLICATION_INSIGHTS_CONNECTION_STRING: Azure Monitor Application Insights-connectionstring voor tracering.
• AZURE_OPENAI_ENDPOINT: de EINDPUNT-URL van uw Azure OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: de naam van de implementatie van het chatmodel.
• AZURE_OPENAI_VERSION: API-versie, bijvoorbeeld 2024-08-01-preview.

Sla deze waarden op in een .env bestand voor lokale ontwikkeling.

LangGraph tracer configureren

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: Gereedschappen

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

De Werkstroom LangGraph bouwen

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: Uitvoeren met tracering

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

Als langchain-azure-ai deze optie is ingeschakeld, verzendt uw LangGraph-uitvoering openTelemetry-compatibele reeksen voor modelaanroepen, hulpprogrammaaanroepen en grafiekovergangen. Deze traces stromen naar Application Insights en verschijnen in de weergave Observability>Traces in de Foundry-portal.

Verifieer uw LangGraph-traceringen

Nadat de agent is uitgevoerd:

1. Wacht 2-5 minuten totdat traces zijn doorgekomen.
2. Ga in de Foundry-portal naar Observability>Traces.
3. Zoek naar een tracering met de naam die u hebt opgegeven (bijvoorbeeld 'Music Player Agent').
4. Vouw de tracering uit om reeksen voor grafiekknooppunten, hulpprogramma-aanroepen en modeloproepen weer te geven.

Als u geen traceringen ziet, raadpleegt u de sectie Veelvoorkomende problemen oplossen .

Voorbeeld: LangChain 0.3 instellen met Azure AI-tracering

Deze minimale installatie laat zien hoe u Azure AI-tracering inschakelt in een LangChain 0.3-toepassing met behulp van de langchain-azure-ai tracer en AzureChatOpenAI.

LangChain 0.3: Pakketten installeren

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

LangChain 0.3: Omgeving configureren

• APPLICATION_INSIGHTS_CONNECTION_STRING: Application Insights-verbindingsreeks voor tracering. Als u deze waarde wilt vinden, opent u de Application Insights-resource in de Azure-portal, selecteert u Overview en kopieert u de Connection String.
• AZURE_OPENAI_ENDPOINT: Azure OpenAI-eindpunt-URL.
• AZURE_OPENAI_CHAT_DEPLOYMENT: Naam van implementatie van chatmodel.
• AZURE_OPENAI_VERSION: API-versie, bijvoorbeeld 2024-08-01-preview.
• AZURE_OPENAI_API_KEY: Azure OpenAI API-sleutel.

LangChain 0.3: Tracer en modelinstallatie

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

Koppel callbacks=[azure_tracer] aan uw ketens, hulpprogramma's of agenten om ervoor te zorgen dat de LangChain 0.3-bewerkingen worden gevolgd. Nadat u uw keten of agent hebt uitgevoerd, worden traceringen binnen 2-5 minuten weergegeven in de Observability>Traces weergave in de Foundry-portal.

Tracering configureren voor OpenAI Agents SDK

De OpenAI Agents SDK ondersteunt Instrumentatie van OpenTelemetry. Gebruik het volgende fragment om tracerings- en exportbereiken te configureren voor Azure Monitor. Als APPLICATION_INSIGHTS_CONNECTION_STRING niet is ingesteld, valt de exporter terug op de console voor lokale foutopsporing.

Voordat u het voorbeeld uitvoert, installeert u de vereiste pakketten:

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

Traceringen verifiëren in de Foundry-portal

1. Meld u aan bij Microsoft Foundry. Zorg ervoor dat de wisselknop New Foundry is ingeschakeld. Deze stappen verwijzen naar Foundry (nieuw).
2. Bevestig dat tracering is verbonden voor uw project. Volg indien nodig het instellen van tracering in Microsoft Foundry.
3. Voer uw agent minstens één keer uit.
4. Ga in de Foundry-portal naar Observability>Traces.
5. Controleer of er een nieuwe trace verschijnt met reikwijdtes voor de taken van uw agent.

Traceringen worden doorgaans binnen 2-5 minuten na de uitvoering van de agent weergegeven. Als traceringsresultaten na deze tijd nog steeds niet worden weergegeven, raadpleegt u Problemen met Veelvoorkomende Problemen Oplossen.

Veelvoorkomende problemen oplossen

Volgende stappen

• Leer de belangrijkste concepten en architectuur in het overzicht van agenttracering.
• Als u tracering nog niet hebt ingeschakeld, raadpleegt u Opsporing instellen in Microsoft Foundry.
• Visualiseer metrische gegevens over de status en prestaties van de agent met het dashboard Voor agentbewaking.
• Verken de bredere waarneembaarheidsmogelijkheden in Waarneembaarheid in generatieve AI.