Trasování aplikací LangChain a LangGraph pomocí Microsoft Foundry a Azure Monitor

Pomocí integračního balíčku langchain-azure-ai emitujte trasování OpenTelemetry z aplikací LangChain a LangGraph a odesílejte je do Aplikace Azure Insights. V tomto článku nakonfigurujete AzureAIOpenTelemetryTracer, připojíte ho ke spustitelnému programu a zkontrolujete trasování v Azure Monitor.

Tracer generuje span pro spouštění agenta, volání modelu, spouštění nástrojů a načítací operace. Můžete ho použít pro aplikace, které spouštějí plně místní, hybridní toky, které volají službu Foundry Agent Service nebo řešení LangGraph s více agenty.

Požadavky

  • Předplatné Azure. Vytvořte si ho zdarma.
  • Projekt Foundry.
  • Nasazený model chatu OpenAI Azure (například gpt-4.1).
  • Python 3.10 nebo novější.
  • Azure CLI je přihlášený (az login), takže se DefaultAzureCredential může ověřit.

Konfigurace prostředí

Instalace požadovaných balíčků:

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

Nastavte proměnné prostředí použité v tomto článku:

import os

# Option 1: Project endpoint (recommended)
os.environ["FOUNDRY_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..."

Pokud chcete určit, jestli se obsah ze zpráv a volání nástrojů zaznamená do trasování, předejte enable_content_recording konstruktoru AzureAIOpenTelemetryTracer . Nahrávání obsahu je ve výchozím nastavení povolené.

Tip

Nastavte enable_content_recording=False v konstruktoru AzureAIOpenTelemetryTracer tak, aby skrýval obsah zprávy a argumenty volání nástrojů z trasování.

Vytvořte trasovač

Vytvořte jednu instanci traceru a znovu ji použijte v rámci pracovního postupu.

import os

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

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

Co tento fragment kódu dělá: Nakonfiguruje trasovač, který získá přidružený řetězec připojení Application Insights z koncového bodu vašeho projektu Foundry a povolí trasování pro uzly LangGraph. Pomocí agent_id parametru nastavte atribut gen_ai.agent.id při vyvolání agentů. Parametr name nastaví název traceru OpenTelemetry.

Tracer podporuje běžné ovládací prvky pro produkční pracovní postupy:

  • Předejte connection_string pro cílení na konkrétní prostředek Application Insights nebo nakonfigurujte proměnnou prostředí APPLICATION_INSIGHTS_CONNECTION_STRING.
  • Nastavte trace_all_langgraph_nodes=True pro trasování všech uzlů ve výchozím nastavení.
  • Použijte metadata uzlu, například otel_trace: True nebo otel_trace: False k zahrnutí nebo přeskočení konkrétních uzlů.
  • Použijte message_keys a message_paths když jsou zprávy vnořené v rámci struktury vlastního stavu, například chat_history.

Odkaz:

Sledování agenta

Začněte s minimálním agentem LangChain, abyste mohli rychle ověřit trasování. Pro LangGraph připojte k zkompilovanému grafu trasovací modul s with_config.

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.

Co tento fragment kódu dělá: Vytvoří jednoduchého agenta LangGraph, připojí tracer a vyvolá agenta se zprávou.

Odkaz:

Sledujte spustitelnou komponentu LangChain

Začněte s minimálním tokem LangChain, abyste mohli rychle ověřit trasování.

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.

Co tento fragment kódu dělá: Spustí standardní kanál LangChain a odešle chat spans do OpenTelemetry prostřednictvím AzureAIOpenTelemetryTracer.

Odkaz:

Trasování grafu LangGraph

Pro LangGraph připojte k zkompilovanému grafu trasovací modul s with_config. Tento fragment kódu se opakovaně používá model a tracer z předchozích příkladů.

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

Pak můžete graf spustit obvyklým způsobem:

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.

Co tento fragment kódu dělá: Vytvoří jednoduchou aplikaci LangGraph, označí uzel pro trasování a vygeneruje invoke_agent a model/nástroj se rozdělí do stejného trasování.

Odkaz:

Pochopte strukturu trasování

Tracer vysílá rozsahy, které následují sémantické konvence OpenTelemetry GenAI. Každý typ rozsahu používá určitou gen_ai.operation.name hodnotu:

Typ rozpětí gen_ai.operation.name Popis
Vyvolání agenta/řetězce invoke_agent Každý uzel LangGraph nebo krok řetězu Název rozsahu je invoke_agent {gen_ai.agent.name}.
Volání chatovacího modelu chat Žádosti o odvození LLM Název rozsahu je chat {gen_ai.request.model}.
Dokončování textu text_completion Nechatovací hovory LLM.
Provádění nástrojů execute_tool Volání nástrojů aktivované modelem Název rozsahu je execute_tool {gen_ai.tool.name}.
Retriever execute_tool Operace načítání z vektorových úložišť nebo dotazování.

Spans má také tyto klíčové atributy:

  • gen_ai.agent.name — Název agenta nebo uzlu.
  • gen_ai.agent.id — Nastavte z parametru konstruktoru agent_id .
  • gen_ai.agent.description — Popis agenta.
  • gen_ai.provider.name— Poskytovatel modelu (například openai, ). azure.ai.inference
  • gen_ai.request.model — Název modelu použitý k odvozování.
  • gen_ai.conversation.id — Identifikátor vlákna nebo relace, pokud je k dispozici.
  • gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Počet tokenů z odpovědí modelu.
  • gen_ai.input.messages / gen_ai.output.messages — Obsah zprávy (pokud je povolen záznam obsahu).

Jak tracer vyřeší gen_ai.agent.name

Identifikátor rozpozná jméno agenta z první neprázdné hodnoty v tomto pořadí:

  1. agent_name v metadatech uzlu.
  2. langgraph_node v metadatech uzlu (automaticky nastaveno jazykem LangGraph).
  3. agent_type v metadatech uzlu.
  4. Klíčový argument name ze zpětného volání LangChain.
  5. langgraph_path (poslední prvek) pokud výše uvedené jsou obecné zástupné symboly.
  6. Serializované ID řetězce nebo název třídy.
  7. Parametr name z konstruktoru AzureAIOpenTelemetryTracer (výchozí hodnota).

Jak tracer vyřeší gen_ai.agent.id

Nástroj pro sledování určuje ID agenta z:

  1. agent_id v metadatech uzlu (přepsání podle uzlu).
  2. Parametr konstruktoru agent_id (výchozí hodnota pro všechny rozsahy)

Přizpůsobení atributů pomocí metadat uzlů

Pomocí metadat jazyka LangGraph můžete nastavit agent_name, agent_ida agent_description na každý uzel. Jakýkoli klíč metadat začínající gen_ai. je také předán jako atribut 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)

Při použití jazyka LangGraph můžete také nastavit metadata na uzel v definici grafu:

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

Odkaz:

Zobrazení trasování v Azure Monitor

Trasování se odesílají do Aplikace Azure Insights a lze je dotazovat pomocí Azure Monitoru.

  1. Přejděte na portál Azure.

  2. Přejděte na Aplikace Azure Insights, které jste nakonfigurovali.

  3. Pomocí levého navigačního panelu vyberte Prozkoumat>Agenty (Preview).

  4. Zobrazí se řídicí panel zobrazující spuštění agenta, modelu a nástrojů. Toto zobrazení vám umožní pochopit celkovou aktivitu vašich agentů.

  5. Vyberte Zobrazit trasování pomocí spuštění agenta. V bočním panelu se zobrazí všechny stopy vygenerované spuštěním agenta.

    Snímek obrazovky zobrazující sekci Agenti (Preview) v Azure Monitor, která zobrazuje více spuštění.

  6. Vyberte jednu z tras. Měli byste vidět podrobnosti.

    Snímek obrazovky zobrazující podrobnosti o trasování vybraného spuštění

Zobrazení trasování v řídicí rovině systému Foundry

Pokud jste nasadili řešení LangGraph nebo LangChain, můžete toto nasazení zaregistrovat do Foundry Control Plane , abyste získali přehled a správu.

Zaregistrujte svou aplikaci do Foundry Control Plane, abyste mohli zobrazit trasování v portálu Foundry.

Postupujte:

  1. Ujistěte se, že splňujete požadavky na používání funkce vlastního agenta Foundry Control Plane:

    • Brána AI nakonfigurovaná v prostředku Foundry. Foundry používá Azure API Management k registraci agentů jako rozhraní API.

    • Agent, kterého nasadíte a zpřístupníte přes dostupný koncový bod. Koncový bod může být veřejný koncový bod nebo koncový bod, který je dostupný ze sítě, kam nasadíte prostředek Foundry.

  2. Ujistěte se, že máte v projektu nakonfigurovanou pozorovatelnost.

  3. Při konfiguraci třídy AzureAIOpenTelemetryTracernezapomeňte použít koncový bod projektu, na který má být agent zaregistrovaný. Ujistěte se, že jste nakonfigurovali agent_id.

  4. Přejděte na portál Foundry.

  5. Na panelu nástrojů vyberte Operace.

  6. V podokně Přehled vyberte Zaregistrovat agenta.

  7. Zobrazí se průvodce registrací. Nejprve vyplňte podrobnosti o agentu, kterého chcete zaregistrovat.

    • Adresa URL agenta: Koncový bod (URL), ve kterém váš agent běží a přijímá požadavky.
    • Protokol: Komunikační protokol, který váš agent podporuje.
    • ID agenta OpenTelemetry: agent_id Parametr, který jste nakonfigurovali ve AzureAIOpenTelemetryTracer třídě.
    • Projekt: Projekt, který jste nakonfigurovali pro příjem tras ve třídě AzureAIOpenTelemetryTracer.
    • Název agenta: Název agenta (může být stejný jako agent_id).

  8. Vyvolání agenta a ujistěte se, že je spuštěný.

  9. Na panelu nástrojů vyberte Operace.

  10. V levém podokně vyberte Prostředky.

  11. Vyberte agenta, který jste vytvořili.

  12. V části Trasování se zobrazí jedna položka pro každé volání HTTP provedené do koncového bodu agenta.

    Pokud chcete zobrazit podrobnosti, vyberte položku.

    Snímek obrazovky volání na koncový bod agenta pod cestou pro běhy a datový proud.

Odstraňování problémů

  • Pokud se nezobrazí žádné stopy, ověřte, zda je connection_string nakonfigurovaný nebo zda koncový bod projektu poskytuje telemetrii.
  • Pokud se obsah zprávy zobrazí jako redigovaný, nastavte enable_content_recording=True v konstruktoru AzureAIOpenTelemetryTracer.
  • Pokud některé uzly LangGraph chybí, nastavte trace_all_langgraph_nodes=True nebo přidejte metadata otel_trace: True uzlu.

Použijte paměť Foundry s LangChain a LangGraph

Související obsah

  • Last updated on