Tracez les applications LangChain et LangGraph avec Microsoft Foundry et Azure Monitor

Utilisez le package d’intégration langchain-azure-ai pour émettre des traces OpenTelemetry à partir des applications LangChain et LangGraph et les envoyer vers Azure Application Insights. Dans cet article, vous allez configurer AzureAIOpenTelemetryTracer, l’attacher à votre runnable et inspecter les traces dans Azure Monitor.

Le traceur émet des intervalles pour l’exécution d’agents, les appels de modèles, l’exécution d’outils et les opérations de récupération. Vous pouvez l’utiliser pour les applications qui exécutent des flux entièrement locaux, hybrides qui appellent le service Foundry Agent ou des solutions LangGraph multi-agents.

Conditions préalables

• Un abonnement Azure. Créez-en un gratuitement.
• Un projet Foundry.
• Modèle de conversation OpenAI déployé Azure (par exemple, gpt-4.1).
• Python 3.10 ou version ultérieure.
• Azure CLI connecté (az login) afin que DefaultAzureCredential puisse s’authentifier.

Configurer votre environnement

Installez les packages requis :

pip install -U "langchain-azure-ai[opentelemetry]" azure-identity

Définissez les variables d’environnement utilisées dans cet article :

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"
os.environ["APPLICATION_INSIGHTS_CONNECTION_STRING"] = "InstrumentationKey=0ab1c2d3..."

Pour contrôler si le contenu des messages et des appels d’outil est enregistré dans la trace, passez enable_content_recording au AzureAIOpenTelemetryTracer constructeur. L’enregistrement de contenu est activé par défaut.

Créer le traceur

Créez une instance de suivi et réutilisez-la dans votre flux de travail.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

tracer = AzureAIOpenTelemetryTracer(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	name="langchain-tracing-sample",
	agent_id="support-bot",
	trace_all_langgraph_nodes=True,
)

Ce que cet extrait fait : Configure un traceur qui résout la chaîne de connexion Application Insights associée depuis le point de terminaison de votre projet Foundry et active la traçabilité pour les nœuds LangGraph. Utilisez agent_id le paramètre pour définir l’attribut gen_ai.agent.id lors de l’appel d’agents. Le name paramètre définit le nom du traceur OpenTelemetry.

Le traceur prend en charge les contrôles courants pour les flux de travail de production :

• Pour cibler une ressource spécifique d'Application Insights, passez connection_string ou configurez la variable d'environnement APPLICATION_INSIGHTS_CONNECTION_STRING.
• Définir trace_all_langgraph_nodes=True pour tracer tous les nœuds par défaut.
• Utilisez des métadonnées de nœud comme otel_trace: True ou otel_trace: False pour inclure ou ignorer des nœuds spécifiques.
• Utilisez message_keys et message_paths lorsque vos messages sont imbriqués sous une forme d’état personnalisée, par exemple chat_history.

Référence:

• AzureAIOpenTelemetryTracer

Tracer un agent

Commencez par un agent LangChain minimal pour vérifier rapidement le suivi. Pour LangGraph, attachez le traceur avec with_config sur le graphique compilé.

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
).with_config(
    {"callbacks": [tracer]}
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()

================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

Ce que fait cet extrait de code : Crée un agent LangGraph simple, attachez le traceur et appelle l’agent avec un message.

Référence:

• LangGraph
• OpenTelemetry

Tracer un runnable LangChain

Commencez par un flux LangChain minimal pour vous permettre de vérifier rapidement le suivi.

import os

from azure.identity import DefaultAzureCredential
from langchain_core.prompts import ChatPromptTemplate
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
	endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
)

prompt = ChatPromptTemplate.from_template(
	"You are concise. Answer in one sentence: {question}"
)
chain = prompt | model

response = chain.invoke(
	{"question": "What does OpenTelemetry help me do?"},
	config={"callbacks": [tracer]},
)

print(response.content)

OpenTelemetry helps you observe requests, latency, dependencies, and failures across your AI workflow.

Ce que fait cet extrait de code : Exécute un pipeline LangChain standard et envoie des étendues de conversation à OpenTelemetry via AzureAIOpenTelemetryTracer.

Référence:

• AzureAIChatCompletionsModel
• ChatPromptTemplate

Tracer un graphique LangGraph

Pour LangGraph, attachez le traceur avec with_config sur le graphique compilé. Cet extrait de code réutilise model et tracer à partir d’exemples précédents.

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver
from langchain_core.tools import tool
from langchain_azure_ai.utils.agents import pretty_print

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

tool_node = ToolNode([play_song_on_apple, play_song_on_spotify])
model_with_tools = model.bind_tools([play_song_on_apple, play_song_on_spotify])

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_with_tools.invoke(messages)
    return {"messages": [response]}

memory = MemorySaver()
workflow = (
    StateGraph(MessagesState)
    .add_node("agent", call_model)
    .add_node("action", tool_node)
    .add_edge(START, "agent")
    .add_conditional_edges(
        "agent",
        should_continue,
        {
            "continue": "action",
            "end": END,
        },
    )
    .add_edge("action", "agent")
    .compile(checkpointer=memory)
)

Ensuite, vous pouvez exécuter le graphique comme d’habitude :

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [tracer]}
message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

result = workflow.invoke({"messages": [message]}, config)
pretty_print(result)

================================ Human Message =================================

Can you play Taylor Swift's most popular song?
================================== Ai Message ==================================
Tool Calls:
  play_song_on_spotify (call_xxx)
 Call ID: call_xxx
  Args:
    song: Anti-Hero
================================= Tool Message =================================
Name: play_song_on_spotify

Successfully played Anti-Hero on Spotify!
================================== Ai Message ==================================

I played Taylor Swift's popular song "Anti-Hero" on Spotify.

Ce que fait cet extrait : crée une application LangGraph simple, marque le nœud pour le traçage et émet les spans invoke_agent ainsi que les spans de modèle/outils dans la même trace.

Référence:

• LangGraph
• OpenTelemetry

Comprendre la structure de trace

Le traceur émet des traces qui suivent les conventions sémantiques OpenTelemetry GenAI. Chaque type d’intervalle utilise une valeur particulière gen_ai.operation.name :

Les spans incluent également les attributs clés suivants :

• gen_ai.agent.name — Nom de l’agent ou du nœud.
• gen_ai.agent.id — Défini à partir du paramètre du agent_id constructeur.
• gen_ai.agent.description — Description de l’agent.
• gen_ai.provider.name — Fournisseur de modèles (par exemple, openai, azure.ai.inference).
• gen_ai.request.model — Nom du modèle utilisé pour l’inférence.
• gen_ai.conversation.id — Identificateur de thread ou de session, lorsqu’il est disponible.
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Nombre de tokens provenant des réponses du modèle.
• gen_ai.input.messages / gen_ai.output.messages — Contenu du message (lorsque l’enregistrement de contenu est activé).

Comment le traceur résout gen_ai.agent.name

Le traceur résout le nom de l’agent à partir de la première valeur non vide dans cet ordre :

1. agent_name dans les métadonnées du nœud.
2. langgraph_node dans les métadonnées du nœud (définies automatiquement par LangGraph).
3. agent_type dans les métadonnées du nœud.
4. Argument de mot clé name du callback LangChain.
5. langgraph_path (dernier élément) si les éléments ci-dessus sont des espaces réservés génériques.
6. ID de chaîne sérialisé ou nom de classe.
7. Le paramètre name du constructeur AzureAIOpenTelemetryTracer (valeur par défaut de secours).

Comment le traceur résout gen_ai.agent.id

Le traceur détermine l’ID de l’agent à partir de :

1. agent_id dans les métadonnées du nœud (remplacement par nœud).
2. Paramètre agent_id de constructeur (par défaut pour toutes les étendues).

Personnaliser des attributs avec des métadonnées de nœud

Vous pouvez définir agent_name, agent_idet agent_description par nœud à l’aide des métadonnées LangGraph. Toute clé de métadonnées commençant par gen_ai. est également transférée en tant qu’attribut d’étendue.

config = {
    "callbacks": [tracer],
    "metadata": {
        "agent_name": "support-bot",
        "agent_id": "support-bot-v2",
        "agent_description": "Handles customer support requests",
        "thread_id": "session-abc-123",
    },
}
result = graph.invoke({"messages": [message]}, config)

Lorsque vous utilisez LangGraph, vous pouvez également définir des métadonnées par nœud dans la définition de graphique :

workflow = StateGraph(MessagesState)
workflow.add_node(
    "planner",
    planner_fn,
    metadata={
        "agent_name": "PlannerAgent",
        "agent_id": "planner-v1",
        "otel_agent_span": True,
    },
)

Référence:

• Étendues de l’agent OpenTelemetry GenAI
• OpenTelemetry GenAI Spans

Afficher les traces dans Azure Monitor

Les traces sont envoyées à Azure Application Insights et peuvent être interrogées à l’aide de Azure Monitor :

1. Accédez au portail Azure.

2. Accédez au Azure Application Insights que vous avez configuré.

3. À l’aide de la barre de navigation de gauche, sélectionnez Examiner>Agents (préversion).

4. Vous voyez un tableau de bord montrant les exécutions d’agents, de modèles et d’outils. Utilisez cette vue pour comprendre l’activité globale de vos agents.

5. Sélectionnez Afficher les traces avec les exécutions d’agent. Le panneau latéral affiche toutes les traces générées par les exécutions de l’agent.

   

6. Sélectionnez l’une des traces. Vous devriez voir les détails.

   

Afficher les traces dans le plan de contrôle Foundry

Si vous avez déployé votre solution LangGraph ou LangChain, vous pouvez inscrire ce déploiement dans Foundry Control Plane pour obtenir une visibilité et une gouvernance.

Inscrivez votre application dans Le plan de contrôle Foundry pour afficher les traces dans le portail Foundry.

Procédez comme suit :

1. Vérifiez que vous répondez aux exigences pour utiliser la fonctionnalité d’agent personnalisé du Plan de Contrôle Foundry :

   • La passerelle d'IA configurée dans votre ressource Foundry. Foundry utilise Gestion des API Azure pour inscrire des agents en tant qu’API.

   • Agent que vous déployez et exposez via un point de terminaison accessible. Le point de terminaison peut être un point de terminaison public ou un point de terminaison accessible à partir du réseau où vous déployez la ressource Foundry.

2. Vérifiez que vous disposez d’une observabilité configurée dans le projet.

3. Lors de la configuration de la classe AzureAIOpenTelemetryTracer, veillez à utiliser le point de terminaison du projet auquel vous souhaitez que l’agent soit inscrit. Vérifiez que vous configurez agent_id.

4. Accédez au portail Foundry.

5. Dans la barre d’outils, sélectionnez Utiliser.

6. Dans le volet Vue d’ensemble , sélectionnez Inscrire l’agent.

7. L’Assistant de Configuration s’affiche. Tout d’abord, renseignez les détails sur l’agent que vous souhaitez inscrire.

   • URL de l’agent : point de terminaison (URL) où votre agent s’exécute et reçoit des demandes.
   • Protocole : protocole de communication pris en charge par votre agent.
   • ID de l’agent OpenTelemetry : agent_id paramètre que vous avez configuré dans la AzureAIOpenTelemetryTracer classe.
   • Project : project que vous avez configuré pour recevoir des traces dans la classe AzureAIOpenTelemetryTracer.
   • Nom de l’agent : nom de l’agent (il peut être identique à agent_id).

8. Appelez l’agent afin de vous assurer qu’il possède des exécutions.

9. Dans la barre d’outils, sélectionnez Utiliser.

10. Dans le volet gauche, sélectionnez Ressources.

11. Sélectionnez l’agent que vous avez créé.

12. La section Traces affiche une entrée pour chaque appel HTTP effectué au point de terminaison de l’agent.

    Pour afficher les détails, sélectionnez une entrée.

    

Dépanner

• Si aucune trace n’apparaît, vérifiez que soit connection_string est configuré, soit que votre point de terminaison de projet expose les données de télémétrie.
• Si le contenu du message apparaît masqué, définissez enable_content_recording=True dans le constructeur AzureAIOpenTelemetryTracer.
• Si certains nœuds LangGraph sont manquants, définissez trace_all_langgraph_nodes=True ou ajoutez des métadonnées otel_trace: Truede nœud.

Contenu connexe

• Bien démarrer avec langchain-azure-ai
• Utiliser LangGraph avec le Service d’Agent
• Configurer des intégrations de suivi pour les infrastructures d’agent