Traccia le app LangChain e LangGraph con Microsoft Foundry e Monitoraggio di Azure

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

Il tracer emette span per l'esecuzione dell'agente, le invocazioni del modello, l'esecuzione degli strumenti e le operazioni di recupero. È possibile utilizzarlo per le app che funzionano completamente in locale, per flussi ibridi che chiamano il Foundry Agent Service o per soluzioni LangGraph multi-agente.

Prerequisiti

• Sottoscrizione Azure. Crearne uno gratuitamente.
• Progetto Foundry.
• 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 connesso (az login) così che DefaultAzureCredential possa eseguire l'autenticazione.

Configurare l'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 tracciatore

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 di Application Insights associata all'endpoint del progetto Foundry e abilita il tracing 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 controlli comuni per i flussi di lavoro di produzione.

• Passare connection_string per indirizzare una risorsa specifica di Application Insights o configurare 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 tracciante con with_config al 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 snippet: Crea un semplice agente LangGraph, collega il tracer e richiama l'agente con un messaggio.

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 tracciante con with_config al 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.

Cosa fa questo frammento di codice: Crea un'app semplice LangGraph, contrassegna il nodo per la tracciatura e emette invoke_agent e gli intervalli modello/strumento nella stessa traccia.

Riferimento:

• LangGraph
• OpenTelemetry

Comprendere la struttura di traccia

Il tracciatore emette intervalli 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 agent_id costruttore.
• 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 viene risolto il tracer gen_ai.agent.name

Il tracciante 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. Argomento name della parola chiave del callback LangChain.
5. langgraph_path (ultimo elemento) se i segnaposto precedenti sono generici.
6. ID della catena serializzata o nome della classe.
7. Il parametro name dal costruttore AzureAIOpenTelemetryTracer (valore predefinito di riserva).

Come viene risolto il tracer gen_ai.agent.id

Il tracciante risolve l'ID dell'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:

• Intervalli dell'agente OpenTelemetry GenAI
• Intervalli OpenTelemetry GenAI

Visualizza le tracce in Monitoraggio di Azure

Le tracce vengono inviate a applicazione Azure Insights e possono essere sottoposte a query usando Monitoraggio di Azure:

1. Passare al portale Azure.

2. Naviga a l'applicazione Azure 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 Visualizza tracce con esecuzioni dell'agente. Il pannello laterale mostra tutte le tracce generate dalle esecuzioni dell'agente.

   

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

   

Visualizzare le tracce nel piano di controllo Foundry

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

Registra l'applicazione nel piano di controllo Foundry per visualizzare le tracce nel portale Foundry.

Seguire questa procedura:

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

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

   • Un agente che viene 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. Nel pannello 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) in cui viene eseguito l'agente e riceve le richieste.
   • Protocollo: protocollo di comunicazione supportato dall'agente.
   • OpenTelemetry Agent ID(ID agente OpenTelemetry): agent_id parametro configurato nella AzureAIOpenTelemetryTracer classe .
   • Project: Il progetto configurato per ricevere tracce nella classe AzureAIOpenTelemetryTracer.
   • 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 Tracce mostra una voce per ogni chiamata HTTP effettuata all'endpoint dell'agente.

    Per visualizzare i dettagli, selezionare una voce.

    

Risoluzione dei problemi

• 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 censurato, 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 .

Contenuto correlato

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