Tracciare le app LangChain e LangGraph con Microsoft Foundry e Azure Monitor

Usare il pacchetto di integrazione langchain-azure-ai per generare tracce OpenTelemetry dalle applicazioni LangChain e LangGraph e inserirle in Azure Application Insights. Questo articolo illustra come configurare AzureAIOpenTelemetryTracer, collegarlo all'eseguibile ed esaminare le tracce in Azure Monitor.

Il tracer emette span per l'esecuzione dell'agente, le chiamate al modello, l'esecuzione della strumentazione e le operazioni di recupero. È possibile usarlo per le app che vengono eseguite completamente localmente, i flussi ibridi che chiamano il servizio agente Foundry o le soluzioni LangGraph multiagente.

Prerequisiti

• Sottoscrizione Azure. Creane uno gratis.
• Un progetto Fonderia.
• Un Azure modello di chat OpenAI distribuito, ad esempio gpt-4.1.
• Python 3.10 o versione successiva.
• Interfaccia della riga di comando di Azure connessa (az login) in modo che DefaultAzureCredential possa eseguire l'autenticazione.

Configurare il tuo ambiente

Installare i pacchetti necessari:

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

Impostare le variabili di ambiente usate in questo articolo:

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

Per controllare se il contenuto dei messaggi e delle chiamate agli strumenti viene registrato nella traccia, passare enable_content_recording al costruttore AzureAIOpenTelemetryTracer. La registrazione del contenuto è abilitata per impostazione predefinita.

Creare il tracer

Crea un'istanza di tracciatore e riutilizzala nel flusso di lavoro.

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

Cosa fa questo frammento di codice: Configura un tracer che risolve la stringa di connessione associata di Application Insights dall'endpoint del progetto Foundry e abilita il tracciamento per i nodi LangGraph. Usare agent_id il parametro per impostare l'attributo gen_ai.agent.id quando si richiamano gli agenti. Il name parametro imposta il nome di traccia OpenTelemetry.

Il tracciatore supporta i controlli comuni per i flussi di lavoro di produzione.

• Passare connection_string per definire come destinazione una risorsa Application Insights specifica o configurando la variabile di ambiente APPLICATION_INSIGHTS_CONNECTION_STRING.
• Impostare trace_all_langgraph_nodes=True per tracciare tutti i nodi per impostazione predefinita.
• Usare metadati del nodo come otel_trace: True o otel_trace: False per includere o ignorare nodi specifici.
• Usare message_keys e message_paths quando i messaggi sono annidati in una forma di stato personalizzata, ad esempio chat_history.

Riferimento:

• AzureAIOpenTelemetryTracer

Tracciare un agente

Iniziare con un agente LangChain minimo in modo da poter verificare rapidamente la traccia. Per LangGraph, allegare il tracciatore con with_config sul grafico compilato.

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.

Cosa fa questo frammento di codice: Crea un semplice agente LangGraph, collega il tracciatore e invia un messaggio all'agente.

Riferimento:

• LangGraph
• OpenTelemetry

Tracciare un elemento LangChain eseguibile

Iniziare con un flusso LangChain minimo in modo da poter verificare rapidamente la traccia.

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.

Cosa fa questo frammento di codice: Esegue una pipeline LangChain standard e invia intervalli di chat a OpenTelemetry tramite AzureAIOpenTelemetryTracer.

Riferimento:

• AzureAIChatCompletionsModel
• ChatPromptTemplate

Tracciare un grafico LangGraph

Per LangGraph, allegare il tracciatore con with_config sul grafico compilato. Questo frammento di codice riutilizza model e tracer da esempi precedenti.

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

È quindi possibile eseguire il grafico come di consueto:

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.

Funzione di questo frammento: crea una semplice app LangGraph, contrassegna il nodo per la traccia ed emette invoke_agent e genera span per il modello/strumento nella stessa traccia.

Riferimento:

• LangGraph
• OpenTelemetry

Comprendere la struttura della traccia

La traccia genera span che seguono le convenzioni semantiche di OpenTelemetry GenAI. Ogni tipo di intervallo usa un valore specifico gen_ai.operation.name :

Gli intervalli contengono anche questi attributi chiave:

• gen_ai.agent.name : nome dell'agente o del nodo.
• gen_ai.agent.id — Impostato dal parametro del costruttore agent_id.
• gen_ai.agent.description — Descrizione dell'agente.
• gen_ai.provider.name — Provider di modelli (ad esempio, openai, azure.ai.inference).
• gen_ai.request.model — Nome del modello utilizzato per l'inferenza.
• gen_ai.conversation.id — Identificatore di thread o sessione, se disponibile.
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Conteggi dei token dalle risposte del modello.
• gen_ai.input.messages / gen_ai.output.messages — Contenuto del messaggio (quando la registrazione del contenuto è abilitata).

Come funziona il tracer gen_ai.agent.name

Il tracer risolve il nome dell'agente dal primo valore non vuoto in questo ordine:

1. agent_name nei metadati del nodo.
2. langgraph_node nei metadati del nodo (impostati automaticamente da LangGraph).
3. agent_type nei metadati del nodo.
4. L'argomento della parola chiave name dal callback LangChain.
5. langgraph_path (ultimo elemento) se i segnaposto precedenti sono generici.
6. ID della catena serializzata o nome della classe.
7. Parametro name del costruttore AzureAIOpenTelemetryTracer (impostazione predefinita di fallback).

Come funziona il tracer gen_ai.agent.id

Il tracer risolve l'ID agente da:

1. agent_id nei metadati del nodo (override per nodo).
2. Parametro agent_id del costruttore (impostazione predefinita per tutti gli intervalli).

Personalizzare gli attributi con i metadati del nodo

È possibile impostare agent_name, agent_ide agent_description per nodo usando i metadati LangGraph. Qualsiasi chiave di metadati che inizia con gen_ai. viene inoltrata anche come attributo span.

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)

Quando si usa LangGraph, è anche possibile impostare i metadati per ogni nodo nella definizione del grafo:

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

Riferimento:

• Span degli agenti OpenTelemetry GenAI
• Span OpenTelemetry GenAI

Visualizzare le tracce in Azure Monitor

Le tracce vengono inviate a Azure Application Insights e possono essere sottoposte a query usando Azure Monitor:

1. Passare al portale Azure.

2. Passare alla risorsa Azure Application Insights configurata.

3. Usando la barra di navigazione a sinistra, selezionare Analizza>Agenti (Anteprima).

4. Viene visualizzato un dashboard che mostra le esecuzioni di agenti, modelli ed strumenti. Usare questa visualizzazione per comprendere l'attività complessiva degli agenti.

5. Selezionare Visualizzare le tracce con le esecuzioni degli agenti. Il pannello laterale mostra tutte le tracce generate dalle esecuzioni dell'agente.

   Screenshot che mostra la sezione Agents (Preview) in Azure Monitor che visualizza più esecuzioni.

6. Selezionare una delle tracce. Verranno visualizzati i dettagli.

   

Visualizzare le tracce nel piano di controllo di Foundry

Se è stata distribuita la soluzione LangGraph o LangChain, è possibile registrare tale distribuzione in Foundry Control Plane per ottenere visibilità e governance.

Registra la tua applicazione nel Foundry Control Plane per visualizzare le tracce nel portale Foundry.

Segui questi passaggi:

1. Assicuratevi di soddisfare i requisiti per usare la funzionalità agente custom del piano di controllo Foundry.

   • Un gateway di intelligenza artificiale configurato nella risorsa Foundry. Foundry usa Azure API Management per registrare gli agenti come API.

   • Agente distribuito ed esposto tramite un endpoint raggiungibile. L'endpoint può essere un endpoint pubblico o un endpoint raggiungibile dalla rete in cui si distribuisce la risorsa Foundry.

2. Assicurarsi di avere configurato l'osservabilità nel progetto.

3. Quando si configura la classe AzureAIOpenTelemetryTracer, assicurarsi di usare l'endpoint del progetto in cui si vuole registrare l'agente. Assicurarsi di configurare agent_id.

4. Passare al portale Foundry.

5. Sulla barra degli strumenti selezionare Opera.

6. Nella sezione Panoramica, selezionare Registra agente.

7. Verrà visualizzata la procedura guidata di registrazione. Prima di tutto, completare i dettagli sull'agente da registrare.

   • URL agente: l'endpoint (URL) dove l'agente opera e riceve le richieste.
   • Protocollo: protocollo di comunicazione supportato dall'agente.
   • OpenTelemetry Agent ID(ID agente OpenTelemetry): agent_id parametro configurato nella AzureAIOpenTelemetryTracer classe .
   • Progetto: progetto configurato per ricevere tracce nella AzureAIOpenTelemetryTracer classe .
   • Nome agente: nome dell'agente (può essere uguale agent_ida ).

8. Richiamare l'agente per assicurarsi che sia in esecuzione.

9. Sulla barra degli strumenti selezionare Opera.

10. Nel riquadro sinistro selezionare Asset.

11. Selezionare l'agente creato.

12. La sezione Analisi mostra una voce per ogni chiamata HTTP all'endpoint dell'agente.

    Per visualizzare i dettagli, selezionare una voce.

    

Troubleshoot

• Se non vengono visualizzate tracce, verificare che sia connection_string configurato o che l'endpoint del progetto esponga i dati di telemetria.
• Se il contenuto del messaggio appare oscurato, impostare enable_content_recording=True nel costruttore AzureAIOpenTelemetryTracer.
• Se mancano alcuni nodi LangGraph, impostare trace_all_langgraph_nodes=True o aggiungere i metadati otel_trace: Truedel nodo .

Contenuti correlati

• Introduzione a langchain-azure-ai
• Usare LangGraph con il servizio Agent
• Configurare le integrazioni di traccia per i framework agente