Konfigurera spårning för AI-agentramverk (förhandsversion)

När AI-agenter beter sig oväntat i produktion ger tracing dig insyn för att snabbt identifiera grundorsaken. Spårning samlar in detaljerad telemetri – inklusive LLM-anrop, verktygsanrop och agentbeslutsflöden – så att du kan felsöka problem, övervaka svarstider och förstå agentbeteendet mellan begäranden.

Microsoft Foundry tillhandahåller spårningsintegreringar för populära agentramverk som kräver minimala kodändringar. I den här artikeln lär du dig att:

• Konfigurera automatisk spårning för Microsoft Agent Framework och semantisk kernel
• Konfigurera Microsoft OpenTelemetry-distribution för LangChain och LangGraph
• Instrumentera OpenAI Agents SDK med OpenTelemetry
• Kontrollera att spårningar visas i Foundry-portalen
• Felsöka vanliga spårningsproblem

Microsoft Foundry Skill kan hjälpa dig att konfigurera ramverksinstrumentation och verifiera spårningar i Foundry.

Förutsättningar

• Ett gjuteri-projekt. Mer information finns i Skapa ett Foundry-projekt.
• Spårning som är ansluten till en Azure Monitor Application Insights-resurs. Information om hur du konfigurerar det finns i Konfigurera spårning i Microsoft Foundry.
• Bidragsgivare eller högre nivå på Application Insights-resursen för spårdataintag.
• Åtkomst till den anslutna Application Insights-resursen för visning av spårningar. För loggbaserade frågor kan du också behöva åtkomst till den associerade Log Analytics arbetsytan.
• Python 3.10 eller senare (krävs för alla kodexempel i den här artikeln).
• Paketet microsoft-opentelemetry (krävs för LangChain- och LangGraph-exempel).
• Om du använder LangChain eller LangGraph, en Python miljö med pip installerat.

Bekräfta att du kan visa telemetri

Om du vill visa spårningsdata kontrollerar du att ditt konto har åtkomst till den anslutna Application Insights-resursen.

1. I Azure portalen öppnar du Application Insights-resursen som är ansluten till ditt Foundry-projekt.

2. Välj Åtkomstkontroll (IAM).

3. Tilldela en lämplig roll till din användare eller grupp.

   Om du använder loggbaserade frågor börjar du med att bevilja rollen Log Analytics Reader. Om de underliggande Log Analytics tabellerna är skyddade beviljar du även rollen Privilegierad övervakningsdataläsare.

Säkerhet och sekretess

Spårning kan samla in känslig information (till exempel användarindata, modellutdata och verktygsargument och resultat).

• Aktivera innehållsinspelning under utveckling och felsökning för att se fullständiga begärande- och svarsdata. Inaktivera innehållsinspelning i produktionsmiljöer för att skydda känsliga data. I exemplen i den här artikeln styrs innehållsinspelningen av miljövariablerna OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT, OTEL_SEMCONV_STABILITY_OPT_INoch AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING.
• Lagra inte hemligheter, autentiseringsuppgifter eller token i prompter eller verktygsargument.

Mer information finns i Säkerhet och sekretess.

Konfigurera spårning för Microsoft Agent Framework och semantisk kernel

Microsoft Foundry har interna integreringar med både Microsoft Agent Framework och Semantic Kernel. Agenter som skapats med antingen ramverket genererar automatiskt spårning när spårning är aktiverat för ditt Foundry-projekt – ingen ytterligare kod eller paket krävs.

Så här kontrollerar du att spårningen fungerar:

1. Kör din agent minst en gång.
2. I Foundry-portalen går du till Observability>Spår.
3. Bekräfta att en ny spårning visas med intervall för agentens åtgärder.

Spår visas vanligtvis inom 2–5 minuter efter agentens körning. Avancerad konfiguration finns i den ramverksspecifika dokumentationen:

• Microsoft Agent Framework-arbetsflöden – observerbarhet
• Semantisk kernelobservabilitet

Konfigurera spårning med OpenInference-instrumentationsbibliotek

Microsoft Foundry stöder OpenInference instrumentationsbibliotek för spårning av AI-agenter. Dessa openinference-* paket tillhandahåller automatisk instrumentering för en mängd olika ramverk och kan användas för att spåra både värdbaserade agenter (agenter som distribuerats till Foundry) och icke-Foundry-agenter (agenter som finns utanför Foundry).

Bläddra bland tillgängliga instrumentationspaket på PyPI. För LangChain, se exemplet Microsoft OpenTelemetry distro LangChain, som visar hur du aktiverar Azure Monitor export och automatisk LangChain-instrumentering med use_microsoft_opentelemetry.

Det viktigaste kravet är att korrelera OpenInference-spårningar till en specifik agent. Hur du uppnår detta beror på var din agent körs:

Värdhanterade agenter (distribuerade i Foundry)

När du distribuerar en agent till Foundry med något av de värdbaserade agentserverpaketen hanteras spårningskorrelation automatiskt. Serverpaketet:

• Konfigurerar Azure Monitor export för OpenTelemetry-intervall.
• Utökar alla intervall med attribut för projekt, agentnamn, agentversion och agent-ID så att foundry-användargränssnittet kan fråga och visa dem.

Ingen ytterligare konfiguration krävs. Installera det relevanta openinference-* instrumentationspaketet för ramverket och spårningar visas automatiskt i Foundry-portalen.

Microsoft Agent Framework-agenter som finns utanför Foundry

Om din Microsoft Agent Framework-agent inte distribueras med ett Foundry-värdbaserat agentserverpaket konfigurerar du Azure Monitor export- och agentramverksinstrumentation med Microsoft OpenTelemetry-distribution. Distributionen kan aktivera Azure Monitor-exportören och lägga till agentidentitetsattribut i intervall:

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    azure_monitor_connection_string="...",
    sampling_ratio=1.0,
    enable_sensitive_data=True,
    instrumentation_options={
        "agent-framework": {
            "enabled": True,
            "agent_id": "ms-imagination-agent",
            "agent_name": "ms-imagination-agent",
        },
    },
)

Ange azure_monitor_connection_string till Application Insights-resursen som är ansluten till ditt Foundry-projekt. Om du vill samla in prompt- och slutförandeinnehåll under utvecklingen anger du enable_sensitive_data=True.

LangChain-agenter som finns utanför Foundry

Om agenten inte har distribuerats med ett värdbaserat agentserverpaket för Foundry, konfigurerar du Azure Monitor-export och LangChain-instrumentation med Microsoft OpenTelemetry-distributionen. Distributionen kan aktivera Azure Monitor-exportören och lägga till agentidentitetsattribut i LangChain-intervall:

from microsoft.opentelemetry import use_microsoft_opentelemetry

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

Ange APPLICATIONINSIGHTS_CONNECTION_STRING till Application Insights-resursen som är ansluten till ditt Foundry-projekt. Om du vill samla in prompt- och slutförandeinnehåll under utvecklingen anger du OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT, OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimentaloch AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true.

Konfigurera spårning för LangChain och LangGraph

Använd Microsoft OpenTelemetry distro för att generera OpenTelemetry-kompatibla intervall för LangChain- och LangGraph-åtgärder. Dessa spårningar visas i vynObserverbarhetsspårningar> i Foundry-portalen.

• OpenTelemetry-semantiska konventioner för generativ AI
• Microsoft OpenTelemetry-distribution LangChain-exempel

Exempel: LangChain v1-agent med Azure AI-spårning

Använd det här exemplet från slutpunkt till slutpunkt för att instrumentera en LangChain v1-agent (förhandsversion) med hjälp av Microsoft OpenTelemetry-distribution. Distributionen möjliggör automatisk instrumentering av LangChain med de senaste semantiska konventionerna för OpenTelemetry (OTel), så att du kan visa detaljerade spår i Foundrys observabilitetsvy.

LangChain v1: Installera paket

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

LangChain v1: Konfigurera miljö

• APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Monitor Application Insights anslutningssträng för spårning.
• AZURE_OPENAI_ENDPOINT: Din Azure OpenAI-slutpunkts-URL.
• AZURE_OPENAI_CHAT_DEPLOYMENT: Namnet på chattmodellens implementering.
• AZURE_OPENAI_VERSION: API-version, till exempel 2024-08-01-preview.
• SDK:t löser Azure autentiseringsuppgifter med hjälp av DefaultAzureCredential, som stöder miljövariabler, hanterad identitet och VS Code-inloggning.

Lagra dessa värden i en .env fil för lokal utveckling.

LangChain v1: Tracer-konfiguration

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

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

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

LangChain v1: Definiera verktyg och uppmaning

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: Använd körningskontext och definiera ett användarinformationsverktyg

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: Skapa agenten

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: Kör agenten med spårning

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}}
    context = UserContext(user_id="1")

    r1 = agent.invoke(
        {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
        config=config,
        context=context,
    )
    print(r1.get("structured_response"))

    r2 = agent.invoke(
        {"messages": [{"role": "user", "content": "Thanks"}]},
        config=config,
        context=context,
    )
    print(r2.get("structured_response"))


if __name__ == "__main__":
    main()

Med Microsoft OpenTelemetry-distribution aktiverad genererar alla LangChain v1-åtgärder (LLM-anrop, verktygsanrop, agentsteg) OpenTelemetry-intervall med hjälp av de senaste semantiska konventionerna. Dessa spårningar visas i vyn Observability>Traces i Foundry-portalen och är länkade till Application Insights-resursen.

Verifiera dina LangChain v1-spårningar

När agenten har körts:

1. Vänta 2–5 minuter innan spårningar sprids.
2. I Foundry-portalen går du till Observability>Spår.
3. Leta efter en spårning med det namn som du angav (till exempel "Väderinformationsagent").
4. Expandera spårningen för att se intervall för LLM-anrop, verktygsanrop och agentsteg.

Om du inte ser några spår, kontrollera avsnittet Felsöka vanliga problem .

Exempel: LangGraph-agent med Azure AI-spårning

Det här exemplet visar en enkel LangGraph-agent som instrumenterats med Microsoft OpenTelemetry-distribution för att generera OpenTelemetry-kompatibla spårningar för grafsteg, verktygsanrop och modellanrop.

LangGraph: Installera paket

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

LangGraph: Konfigurera miljö

• APPLICATIONINSIGHTS_CONNECTION_STRING: Azure Monitor Application Insights anslutningssträng för spårning.
• AZURE_OPENAI_ENDPOINT: Din Azure OpenAI-slutpunkts-URL.
• AZURE_OPENAI_CHAT_DEPLOYMENT: Namnet på chattmodellens implementering.
• AZURE_OPENAI_VERSION: API-version, till exempel 2024-08-01-preview.

Lagra dessa värden i en .env fil för lokal utveckling.

Konfiguration av LangGraph-spårning

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

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

LangGraph: Verktyg

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

Skapa LangGraph-arbetsflödet

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: Kör med spårning

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}}
input_message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
    event["messages"][-1].pretty_print()

Med Microsoft OpenTelemetry-distribution aktiverat genererar LangGraph-körningen OpenTelemetry-kompatibla intervall för modellanrop, verktygsanrop och grafövergångar. Dessa spårningar flödar till Application Insights och visas i vyn Observability>Traces i Foundry-portalen.

Verifiera dina LangGraph-spårningar

När agenten har körts:

1. Vänta 2–5 minuter innan spårningar sprids.
2. I Foundry-portalen går du till Observability>Spår.
3. Leta efter en spårning med det namn som du angav (till exempel "Music Player Agent").
4. Expandera spårningen för att se intervall för grafnoder, verktygsanrop och modellanrop.

Om du inte ser några spår, kontrollera avsnittet Felsöka vanliga problem .

Exempel: Konfiguration av LangChain 0.3 med Azure AI-spårning

Den här minimala konfigurationen visar hur du aktiverar Azure AI-spårning i ett LangChain 0.3-program med hjälp av Microsoft OpenTelemetry-distribution och AzureChatOpenAI.

LangChain 0.3: Installera paket

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

LangChain 0.3: Konfigurera miljön

• APPLICATIONINSIGHTS_CONNECTION_STRING: Application Insights reťazec pripojenia för spårning. Om du vill hitta det här värdet öppnar du Application Insights-resursen i Azure-portalen, väljer Overview och kopierar Anslutningssträng.
• AZURE_OPENAI_ENDPOINT: Azure OpenAI-slutpunkts-URL.
• AZURE_OPENAI_CHAT_DEPLOYMENT: Namn på distribution av chattmodell.
• AZURE_OPENAI_VERSION: API-version, till exempel 2024-08-01-preview.
• AZURE_OPENAI_API_KEY: Azure OpenAI API-nyckel.

LangChain 0.3: Tracer och modellkonfiguration

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

load_dotenv(override=True)

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

# Model: Azure OpenAI
llm = AzureChatOpenAI(
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    temperature=0.2,
)

När distributionen initieras instrumenteras LangChain 0.3-åtgärder automatiskt globalt. När du har kört din kedja eller agent visas spårningar i vyn Observability>Traces i Foundry-portalen inom 2–5 minuter.

Konfigurera spårning för OpenAI Agents SDK

OpenAI Agents SDK stöder OpenTelemetry-instrumentation. Använd följande kodfragment för att konfigurera spårning och exportera spans till Azure Monitor. Om APPLICATION_INSIGHTS_CONNECTION_STRING inte har angetts återgår exportören till konsolen för lokal felsökning.

Innan du kör exemplet installerar du de paket som krävs:

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

Verifiera spårningar i Foundry-portalen

1. Logga in på Microsoft Foundry. Kontrollera att växlingsknappen New Foundry är aktiverad. De här stegen hänvisar till Foundry (ny).
2. Bekräfta att spårningen är ansluten till ditt projekt. Om det behövs följer du Ställ in spårning i Microsoft Foundry.
3. Kör din agent minst en gång.
4. I Foundry-portalen går du till Observability>Spår.
5. Bekräfta att en ny spårning visas med intervall för agentens åtgärder.

Spår visas vanligtvis inom 2–5 minuter efter agentens körning. Om spårningar fortfarande inte visas efter den här tiden kan du läsa Felsöka vanliga problem.

Felsöka vanliga problem

Relaterat innehåll

• Lär dig grundläggande begrepp och arkitektur i översikten över agentspårning.
• Om du inte har aktiverat spårning ännu kan du läsa Set up tracing in Microsoft Foundry.
• Visualisera agentens hälso- och prestandamått med instrumentpanelen för agentövervakning.
• Utforska de bredare observerbarhetsfunktionerna inom observerbarhet i generativ AI.