LangChain- en LangGraph-apps traceren met Microsoft Foundry en Azure Monitor

Gebruik het integratiepakket langchain-azure-ai om OpenTelemetry-traceringen uit LangChain- en LangGraph-toepassingen te verzenden en deze in Azure-toepassing Insights op te slaan. In dit artikel configureert u AzureAIOpenTelemetryTracer, koppelt u deze aan uw runnable en inspecteert u traceringen in Azure Monitor.

De tracer verzendt spans voor agentuitvoering, modeloproepen, hulpprogramma-uitvoering en ophaalbewerkingen. U kunt deze gebruiken voor apps die volledig lokale, hybride stromen uitvoeren die Foundry Agent Service aanroepen of LangGraph-oplossingen met meerdere agents.

Voorwaarden

• Een Azure-abonnement. Maak er gratis een.
• Een Foundry-project.
• Een geïmplementeerd Azure OpenAI-chatmodel (bijvoorbeeld gpt-4.1).
• Python 3.10 of hoger.
• Azure CLI aangemeld (az login), zodat DefaultAzureCredential kan authenticeren.

Uw omgeving configureren

Vereiste pakketten installeren:

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

Stel de omgevingsvariabelen in die in dit artikel worden gebruikt:

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

Als u wilt bepalen of inhoud van berichten en hulpprogramma-aanroepen wordt vastgelegd in de trace, geeft enable_content_recording u deze door aan de AzureAIOpenTelemetryTracer constructor. Het opnemen van inhoud is standaard ingeschakeld.

De tracer maken

Maak één tracer-exemplaar en gebruik deze opnieuw in uw werkstroom.

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

Wat dit fragment doet: Hiermee configureert u een tracer waarmee de bijbehorende Application Insights-verbindingsreeks wordt opgehaald vanuit uw Foundry-projecteindpunt en tracering voor LangGraph-knooppunten mogelijk wordt. Gebruik agent_id de parameter om het kenmerk gen_ai.agent.id in te stellen bij het aanroepen van agents. De name parameter stelt de naam van de OpenTelemetry tracer in.

De tracer ondersteunt algemene besturingselementen voor productiewerkstromen:

• Geef connection_string door om een specifieke Application Insights-resource te targeten of configureer de omgevingsvariabele APPLICATION_INSIGHTS_CONNECTION_STRING.
• Stel trace_all_langgraph_nodes=True in om standaard alle knooppunten te traceren.
• Gebruik metagegevens van knooppunten, zoals otel_trace: True of otel_trace: False om specifieke knooppunten op te nemen of over te slaan.
• Gebruik message_keys en message_paths wanneer uw berichten zijn genest onder een aangepaste statusvorm, bijvoorbeeld chat_history.

Verwijzing:

• AzureAIOpenTelemetryTracer

Een agent traceren

Begin met een minimale LangChain-agent, zodat u tracering snel kunt verifiëren. Koppel voor LangGraph de tracer met with_config op de gecompileerde graf.

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.

Wat dit codefragment doet: Hiermee maakt u een eenvoudige LangGraph-agent, koppelt u de tracer en roept u de agent aan met een bericht.

Verwijzing:

• LangGraph
• OpenTelemetry

Een uitvoerbare LangChain traceren

Begin met een minimale LangChain-stroom, zodat u tracering snel kunt verifiëren.

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.

Wat dit codefragment doet: Voert een standaard LangChain-pijplijn uit en verzendt chatbereiken naar OpenTelemetry via AzureAIOpenTelemetryTracer.

Verwijzing:

• AzureAIChatCompletionsModel
• ChatPromptTemplate

Een LangGraph-grafiek traceren

Koppel voor LangGraph de tracer met with_config op de gecompileerde graf. Dit fragment hergebruikt model en tracer uit eerdere voorbeelden.

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

Vervolgens kunt u de grafiek op de gebruikelijke manier uitvoeren:

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.

Wat dit codefragment doet: Hiermee maakt u een eenvoudige LangGraph-app, markeert u het knooppunt voor tracering en voegt u model/tool-spans toe aan dezelfde tracering.

Verwijzing:

• LangGraph
• OpenTelemetry

Traceringsstructuur begrijpen

De tracer verzendt spanten die voldoen aan de semantische conventies van OpenTelemetry GenAI. Elk spantype gebruikt een specifieke gen_ai.operation.name waarde:

Spans bevatten ook deze belangrijke kenmerken:

• gen_ai.agent.name — De naam van de agent of het knooppunt.
• gen_ai.agent.id — Instellen vanaf de agent_id constructorparameter.
• gen_ai.agent.description — Een beschrijving van de agent.
• gen_ai.provider.name — De modelprovider (bijvoorbeeld openai, azure.ai.inference).
• gen_ai.request.model — De modelnaam die wordt gebruikt voor deductie.
• gen_ai.conversation.id — Thread- of sessie-ID, indien beschikbaar.
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Token telt van modelantwoorden.
• gen_ai.input.messages / gen_ai.output.messages — Berichtinhoud (wanneer inhoudsopname is ingeschakeld).

Hoe de tracer oplost gen_ai.agent.name

Het traceerprogramma zet de agentnaam om op basis van de eerste niet-lege waarde in deze volgorde:

1. agent_name in de metagegevens van het knooppunt.
2. langgraph_node in de metagegevens van het knooppunt (automatisch ingesteld door LangGraph).
3. agent_type in de metagegevens van het knooppunt.
4. Het name trefwoordargument uit de callback van LangChain.
5. langgraph_path (laatste element) als het bovenstaande algemene tijdelijke aanduidingen zijn.
6. De geserialiseerde keten-ID of klassenaam.
7. De name parameter van de AzureAIOpenTelemetryTracer constructor (terugvalstandaard).

Hoe de tracer oplost gen_ai.agent.id

De tracer zet de agent-id om vanuit:

1. agent_id in de metagegevens van het knooppunt (overschrijven per knooppunt).
2. De agent_id constructorparameter (standaard voor alle spanten).

Kenmerken aanpassen met metagegevens van knooppunten

U kunt LangGraph-metagegevens per knooppunt instellen met agent_name, agent_id, en agent_description. Elke metagegevenssleutel die begint met gen_ai. , wordt ook doorgestuurd als een spankenmerk.

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)

Wanneer u LangGraph gebruikt, kunt u ook metagegevens per knooppunt instellen in de grafiekdefinitie:

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

Verwijzing:

• OpenTelemetry GenAI-agent spans
• OpenTelemetry GenAI Spans

Traceringen weergeven in Azure Monitor

Traceringen worden verzonden naar Azure-toepassing Insights en kunnen worden opgevraagd met behulp van Azure Monitor:

1. Ga naar de Azure portal.

2. Navigeer naar Azure-toepassing Insights die u hebt geconfigureerd.

3. Gebruik de linkernavigatiebalk om Onderzoeken>Agents (Preview) te selecteren.

4. U ziet een dashboard met uitvoeringen van agents, modellen en hulpprogramma's. Gebruik deze weergave om inzicht te hebben in de algehele activiteit van uw agents.

5. Selecteer Traceringen bekijken met agentuitvoeringen. In het zijpaneel ziet u alle traces die zijn gegenereerd door agent-runs.

   

6. Selecteer een van de traces. U zou de details moeten zien.

   

Traces weergeven in de Foundry Control Plane

Als u uw LangGraph- of LangChain-oplossing hebt geïmplementeerd, kunt u die implementatie registreren in Foundry Control Plane om zichtbaarheid en governance te krijgen.

Registreer uw toepassing bij Foundry Control Plane om traceringen weer te geven in de Foundry-portal.

Volg deze stappen:

1. Zorg ervoor dat u voldoet aan de vereisten voor het gebruik van de aangepaste agentfunctie voor Foundry Control Plane:

   • Een in uw Foundry-resource geconfigureerde AI-gateway. Foundry gebruikt Azure API Management om agents als API's te registreren.

   • Een agent die u implementeert en beschikbaar maakt via een bereikbaar eindpunt. Het eindpunt kan een openbaar eindpunt of een eindpunt zijn dat bereikbaar is vanuit het netwerk waar u de Foundry-resource implementeert.

2. Zorg ervoor dat u waarneembaarheid hebt geconfigureerd in het project.

3. Wanneer u de klasse AzureAIOpenTelemetryTracerconfigureert, moet u het eindpunt van het project gebruiken waarop u de agent wilt registreren. Zorg ervoor dat u agent_id configureert.

4. Ga naar de Foundry-portal.

5. Selecteer Opereren in de werkbalk.

6. Selecteer agent registreren in het deelvenster Overzicht.

7. De registratiewizard wordt weergegeven. Voltooi eerst de details van de agent die u wilt registreren.

   • Agent-URL: het eindpunt (URL) waar uw agent wordt uitgevoerd en aanvragen ontvangt.
   • Protocol: het communicatieprotocol dat uw agent ondersteunt.
   • OpenTelemetry Agent-id: de agent_id parameter die u in de AzureAIOpenTelemetryTracer klasse hebt geconfigureerd.
   • Project: de project die u hebt geconfigureerd voor het ontvangen van traceringen in de klasse AzureAIOpenTelemetryTracer.
   • Agentnaam: de naam van de agent (deze kan hetzelfde zijn als agent_id).

8. Roep de agent aan om te controleren of deze wordt uitgevoerd.

9. Selecteer Opereren in de werkbalk.

10. Selecteer Assets in het linkerdeelvenster.

11. Selecteer de agent die u hebt gemaakt.

12. In de sectie Traceringen wordt één vermelding weergegeven voor elke HTTP-aanroep die is gedaan naar het eindpunt van de agent.

    Als u de details wilt bekijken, selecteert u een vermelding.

    

Problemen oplossen

• Als er geen traceringen worden weergegeven, controleert u of connection_string deze is geconfigureerd of dat uw projecteindpunt telemetriegegevens beschikbaar maakt.
• Als de berichtinhoud geredigeerd lijkt, stel enable_content_recording=True in de constructor AzureAIOpenTelemetryTracer in.
• Als sommige LangGraph-knooppunten ontbreken, kunt u metagegevens trace_all_langgraph_nodes=Truevan knooppunten instellen otel_trace: True of toevoegen.

Verwante inhoud

• Aan de slag met langchain-azure-ai
• LangGraph gebruiken met de Agent Service
• Traceringsintegraties instellen voor agentframeworks