Configurer le traçage pour les cadres d’agents IA (préversion)

Lorsque les agents IA se comportent de façon inattendue en production, le suivi vous donne la visibilité pour identifier rapidement la cause racine. Le suivi capture des données de télémétrie détaillées, notamment les appels LLM, les appels d’outils et les flux de décision de l’agent, afin de pouvoir déboguer des problèmes, surveiller la latence et comprendre le comportement de l’agent entre les requêtes.

Microsoft Foundry fournit des intégrations de suivi pour les infrastructures d’agent populaires qui nécessitent des modifications de code minimales. Dans cet article, vous allez apprendre à :

• Configurer le suivi automatique pour Microsoft Agent Framework
• Configurer le langchain-azure-ai traceur pour LangChain et LangGraph
• Instrumenter le Kit de développement logiciel (SDK) Des agents OpenAI avec OpenTelemetry
• Vérifier que les traces apparaissent dans le portail Foundry
• Résoudre les problèmes de suivi courants

Conditions préalables

• Un projet Foundry avec tracing connecté à Azure Monitor Application Insights.
• Rôle de contributeur ou d'un niveau supérieur sur la ressource Application Insights pour l’ingestion de traces.
• Accès à la ressource Application Insights connectée pour afficher les traces. Pour les requêtes basées sur des logs, vous devrez peut-être également accéder à l'espace de travail Log Analytics associé.
• Python 3.10 ou version ultérieure (obligatoire pour tous les exemples de code de cet article).
• Package langchain-azure-ai version 0.1.0 ou ultérieure (obligatoire pour les exemples LangChain et LangGraph).
• Si vous utilisez LangChain ou LangGraph, un environnement Python avec pip installé.

Vérifiez que vous pouvez afficher les données de télémétrie

Pour afficher les données de trace, vérifiez que votre compte a accès à la ressource Application Insights connectée.

1. Dans le portail Azure, ouvrez la ressource Application Insights connectée à votre projet Foundry.

2. Sélectionnez Contrôle d’accès (IAM).

3. Attribuez un rôle approprié à votre utilisateur ou groupe.

   Si vous utilisez des requêtes basées sur des journaux, commencez par accorder le rôle de lecteur pour l'analyse des journaux Log Analytics.

Sécurité et confidentialité

Le suivi peut capturer des informations sensibles (par exemple, des entrées utilisateur, des sorties de modèle et des arguments et des résultats d’outils).

• Activez l’enregistrement de contenu pendant le développement et le débogage pour afficher les données de requête et de réponse complètes. Désactivez l’enregistrement de contenu dans les environnements de production pour protéger les données sensibles. Dans les exemples de cet article, l’enregistrement de contenu est contrôlé par les paramètres tels que enable_content_recording et OTEL_RECORD_CONTENT.
• Ne stockez pas les secrets, les informations d’identification ou les jetons dans des requêtes ou des arguments d’outil.

Pour plus d’informations, consultez Sécurité et confidentialité.

Configurer le suivi pour Microsoft Agent Framework

Microsoft Foundry a des intégrations natives avec Microsoft Agent Framework. Les agents créés avec l’infrastructure émettent automatiquement des traces lorsque le suivi est activé pour votre projet Foundry. Aucun code ou packages supplémentaire n’est nécessaire.

Pour vérifier que le suivi fonctionne :

1. Exécutez votre agent au moins une fois.
2. Dans le portail Foundry, accédez à Observabilité>Traces.
3. Vérifiez qu’une nouvelle trace s’affiche avec des étendues pour les opérations de votre agent.

Les traces apparaissent généralement dans un délai de 2 à 5 minutes après l’exécution de l’agent. Pour une configuration avancée, consultez la documentation spécifique à l’infrastructure :

• Flux de travail Microsoft Agent Framework – Observabilité

Configurer le suivi pour LangChain et LangGraph

Utilisez le langchain-azure-ai package pour émettre des étendues compatibles OpenTelemetry pour les opérations LangChain et LangGraph. Ces traces apparaissent dans la vueTraces> dans le portail Foundry.

• Conventions sémantiques OpenTelemetry pour l’IA générative
• package langchain-azure-ai sur PyPI

Exemple : Agent v1 LangChain avec traçage Azure IA

Utilisez cet exemple de bout en bout pour configurer un agent LangChain v1 (version préliminaire) à l’aide du traceur langchain-azure-ai. Ce traceur implémente les dernières conventions sémantiques OpenTelemetry (OTel), ce qui vous permet d’afficher des traces enrichies dans la vue d’observabilité Foundry.

LangChain v1 : Installer des packages

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

LangChain v1 : Configurer l’environnement

• APPLICATION_INSIGHTS_CONNECTION_STRING : Chaîne de connexion Azure Monitor Application Insights pour le suivi.
• AZURE_OPENAI_ENDPOINT : URL de point de terminaison OpenAI de votre Azure.
• AZURE_OPENAI_CHAT_DEPLOYMENT: nom du déploiement du modèle de conversation.
• AZURE_OPENAI_VERSION: version de l’API, par exemple 2024-08-01-preview.
• Le SDK résout les informations d'identification Azure à l’aide de DefaultAzureCredential, qui prend en charge les variables d'environnement, l'identité managée et la connexion à VS Code.

Stockez ces valeurs dans un .env fichier pour le développement local.

LangChain v1 : Configuration du traceur

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 : Configuration du modèle (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 : Définir des outils et des incitations

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 : Utiliser le contexte d’exécution et définir un outil d’informations utilisateur

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 : Créer l’agent

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 : Exécuter l'agent avec le traçage

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

Avec langchain-azure-ai activé, toutes les opérations LangChain v1 (appels LLM, appels d’outils, étapes de l’agent) émettent des étendues OpenTelemetry à l’aide des conventions sémantiques les plus récentes. Cestraces apparaissent dans la vue Traces > dans le portail Foundry et sont liées à votre ressource Application Insights.

Vérifiez vos traces LangChain v1

Après avoir exécuté l’agent :

1. Attendez 2 à 5 minutes pour que les traces se propagent.
2. Dans le portail Foundry, accédez à Observabilité>Traces.
3. Recherchez une trace portant le nom que vous avez spécifié (par exemple, « Agent d’informations météorologiques »).
4. Développez la trace pour afficher des plages pour les appels LLM, les invocations d’outils et les étapes d'agent.

Si vous ne voyez pas de traces, consultez la section Résoudre les problèmes courants .

Exemple de : Agent LangGraph avec suivi Azure AI

Cet exemple montre un agent LangGraph simple instrumenté avec langchain-azure-ai pour émettre des traces conformes à OpenTelemetry pour les étapes de graphe, les appels d’outils et les appels de modèle.

LangGraph : Installer des packages

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

LangGraph : Configurer l’environnement

• APPLICATION_INSIGHTS_CONNECTION_STRING : Chaîne de connexion Azure Monitor Application Insights pour le suivi.
• AZURE_OPENAI_ENDPOINT : URL de point de terminaison OpenAI de votre Azure.
• AZURE_OPENAI_CHAT_DEPLOYMENT: nom du déploiement du modèle de conversation.
• AZURE_OPENAI_VERSION: version de l’API, par exemple 2024-08-01-preview.

Stockez ces valeurs dans un .env fichier pour le développement local.

Configuration du traceur LangGraph

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

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 : Configuration du modèle (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)

Générer le flux de travail LangGraph

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 : Exécuter avec le tracé

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

Avec langchain-azure-ai activé, votre exécution LangGraph émet des étendues compatibles OpenTelemetry pour les appels de modèle, les appels d’outils et les transitions de graphique. Ces traces sont envoyées vers Application Insights et apparaissent dans la vue d'Observabilité>Traces dans le portail Foundry.

Vérifiez vos traces LangGraph

Après avoir exécuté l’agent :

1. Attendez 2 à 5 minutes pour que les traces se propagent.
2. Dans le portail Foundry, accédez à Observabilité>Traces.
3. Recherchez une trace portant le nom que vous avez spécifié (par exemple, « Agent de lecteur de musique »).
4. Développez la trace pour afficher des plages pour les nœuds de graphe, les appels d’outils et les appels de modèle.

Si vous ne voyez pas de traces, consultez la section Résoudre les problèmes courants .

Exemple : Configuration de LangChain 0.3 avec le tracing de l'IA Azure

Cette configuration minimale montre comment activer le tracing Azure AI dans une application LangChain 0.3 à l’aide du tracer langchain-azure-ai et AzureChatOpenAI.

LangChain 0.3 : Installer des packages

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

LangChain 0.3 : Configurer l’environnement

• APPLICATION_INSIGHTS_CONNECTION_STRING : Chaîne de connexion Application Insights pour le suivi des données. Pour trouver cette valeur, ouvrez votre ressource Application Insights dans le portail Azure, sélectionnez Overview et copiez la chaîne de connexion .
• AZURE_OPENAI_ENDPOINT : URL de point de terminaison OpenAI Azure.
• AZURE_OPENAI_CHAT_DEPLOYMENT: Nom du déploiement du modèle de conversation.
• AZURE_OPENAI_VERSION: version de l’API, par exemple 2024-08-01-preview.
• AZURE_OPENAI_API_KEY : clé API Azure OpenAI.

LangChain 0.3 : Traçage et configuration du modèle

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

Attachez callbacks=[azure_tracer] à vos chaînes, outils ou agents pour vous assurer que les opérations de LangChain 0.3 sont tracées. Après avoir exécuté votre chaîne ou agent, lestraces apparaissent dans la vue Traces > dans le portail Foundry dans un délai de 2 à 5 minutes.

Configurer le traçage pour le Kit de développement logiciel (SDK) OpenAI Agents

Le Kit de développement logiciel (SDK) Des agents OpenAI prend en charge l’instrumentation OpenTelemetry. Utilisez l’extrait de code suivant pour configurer les étendues de suivi et d’exportation pour Azure Monitor. Si APPLICATION_INSIGHTS_CONNECTION_STRING n'est pas défini, l'exportateur revient à la console pour le débogage local.

Avant d’exécuter l’exemple, installez les packages requis :

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

Vérifier les traces dans le portail Foundry

1. Connectez-vous à Microsoft Foundry. Vérifiez que le commutateur New Foundry est activé. Ces étapes font référence à Foundry (nouveau).
2. Vérifiez que le suivi est connecté pour votre projet. Si nécessaire, suivez Configurer le suivi dans Microsoft Foundry.
3. Exécutez votre agent au moins une fois.
4. Dans le portail Foundry, accédez à Observabilité>Traces.
5. Vérifiez qu’une nouvelle trace s’affiche avec des étendues pour les opérations de votre agent.

Les traces apparaissent généralement dans un délai de 2 à 5 minutes après l’exécution de l’agent. Si les traces n’apparaissent toujours pas après cette période, consultez Résoudre les problèmes courants.

Résoudre les problèmes courants

Étapes suivantes

• Découvrez les concepts de base et l’architecture dans la vue d’ensemble du suivi de l’agent.
• Si vous n'avez pas encore activé le suivi, consultez Set up tracing in Microsoft Foundry.
• Visualisez les métriques d’intégrité et de performances de l’agent avec le tableau de bord surveillance de l’agent.
• Explorez les fonctionnalités d’observabilité plus larges dans l’observabilité dans l’IA générative.