Śledź aplikacje LangChain i LangGraph za pomocą Microsoft Foundry i Azure Monitor

Użyj pakietu integracyjnego langchain-azure-ai, aby emitować trasówki OpenTelemetry z aplikacji LangChain i LangGraph oraz wysyłać je do aplikacja systemu Azure Insights. W tym artykule skonfigurujesz AzureAIOpenTelemetryTracer, dołącz je do elementu runnable i sprawdzisz ślady w Azure Monitor.

Tracer emituje zakresy dla wykonywania agenta, wywołań modelu, wykonywania narzędzi i operacji pobierania. Można go używać w przypadku aplikacji, które uruchamiają w pełni lokalne, hybrydowe przepływy wywołujące usługę agenta foundry lub rozwiązania LangGraph z wieloma agentami.

Wymagania wstępne

• Subskrypcja Azure. Utwórz je bezpłatnie.
• Projekt Foundry.
• Wdrożony model czatu Azure OpenAI (na przykład gpt-4.1).
• Python 3.10 lub nowsza.
• Azure CLI jest zalogowane (az login), więc DefaultAzureCredential może się uwierzytelnić.

Konfigurowanie środowiska

Zainstaluj wymagane pakiety:

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

Ustaw zmienne środowiskowe używane w tym artykule:

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

Aby kontrolować, czy zawartość komunikatów i wywołań narzędzi jest zapisywana w śledzeniu, przekaż enable_content_recording do konstruktora AzureAIOpenTelemetryTracer. Nagrywanie zawartości jest domyślnie włączone.

Tworzenie tracera

Utwórz jedno wystąpienie narzędzia tracer i użyj go ponownie w przepływie pracy.

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 robi ten fragment kodu: Konfiguruje narzędzie śledzenia, które ustala powiązany ciąg połączenia dla usługi Application Insights z endpointu projektu Foundry i umożliwia śledzenie węzłów LangGraph. Użyj agent_id parametru, aby ustawić atrybut gen_ai.agent.id podczas wywoływania agentów. Parametr name ustawia nazwę trasera OpenTelemetry.

Program śledzący obsługuje standardowe kontrole dla przepływów pracy w produkcji.

• Przekaż connection_string w celu nakierowania na określony zasób usługi Application Insights albo poprzez skonfigurowanie zmiennej środowiskowej APPLICATION_INSIGHTS_CONNECTION_STRING.
• Ustaw wartość trace_all_langgraph_nodes=True , aby domyślnie śledzić wszystkie węzły.
• Użyj metadanych węzła, takich jak otel_trace: True lub otel_trace: False , aby uwzględnić lub pominąć określone węzły.
• Użyj message_keys i message_paths , gdy komunikaty są zagnieżdżone pod niestandardowym kształtem stanu, na przykład chat_history.

Referencja:

• AzureAIOpenTelemetryTracer

Śledzenie agenta

Zacznij od minimalnego agenta LangChain, aby szybko zweryfikować śledzenie. Dla LangGraph, dołącz tracer z with_config na skompilowanym grafie.

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 robi ten fragment kodu: Tworzy prostego agenta LangGraph, dołącza element tracer i wywołuje agenta z komunikatem.

Referencja:

• LangGraph
• OpenTelemetry

Śledzenie elementu Runnable LangChain

Zacznij od minimalnego procesu LangChain, aby szybko zweryfikować śledzenie.

import os

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

model = AzureAIChatCompletionsModel(
	project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="gpt-4.1",
)

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 robi ten fragment kodu: Uruchamia standardowy potok LangChain i wysyła zakresy czatów do biblioteki OpenTelemetry za pośrednictwem polecenia AzureAIOpenTelemetryTracer.

Referencja:

• AzureAIChatCompletionsModel
• ChatPromptTemplate

Śledzenie grafu LangGraph

Dla LangGraph, dołącz tracer z with_config na skompilowanym grafie. Ten fragment kodu ponownie wykorzystuje model i tracer z wcześniejszych przykładów.

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

Następnie możesz uruchomić graf w zwykły sposób:

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 robi ten fragment kodu: Tworzy prostą aplikację LangGraph, oznacza węzeł do śledzenia i emituje invoke_agent i model/narzędzie obejmuje ten sam ślad.

Referencja:

• LangGraph
• OpenTelemetry

Omówienie struktury śledzenia

Tracer emituje zakresy, które są zgodne z konwencjami semantycznymi OpenTelemetry GenAI. Każdy typ zakresu używa określonej gen_ai.operation.name wartości:

Zakresy mają również następujące kluczowe atrybuty:

• gen_ai.agent.name — nazwa agenta lub węzła.
• gen_ai.agent.id — zostało ustawione z parametru konstruktora agent_id.
• gen_ai.agent.description — opis agenta.
• gen_ai.provider.name — dostawca modelu (na przykład openai).
• gen_ai.request.model — nazwa modelu używana do wnioskowania.
• gen_ai.conversation.id — identyfikator wątku lub sesji, jeśli jest dostępny.
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens — Liczba tokenów z odpowiedzi modelu.
• gen_ai.input.messages / gen_ai.output.messages — Zawartość wiadomości (po włączeniu rejestrowania zawartości).

Jak narzędzie tracer rozwiązuje problem gen_ai.agent.name

Tracer rozpoznaje nazwę agenta z pierwszej niepustej wartości w następującej kolejności:

1. agent_name w metadanych węzła.
2. langgraph_node w metadanych węzła (automatycznie ustawiane przez LangGraph).
3. agent_type w metadanych węzła.
4. Argument słowa kluczowego name z wywołania zwrotnego LangChain.
5. langgraph_path (ostatni element), jeśli powyższe są uniwersalnymi symbolami zastępczymi.
6. Serializowany identyfikator łańcucha lub nazwa klasy.
7. Parametr name z konstruktora AzureAIOpenTelemetryTracer (domyślna wartość rezerwowa).

Jak narzędzie tracer rozwiązuje problem gen_ai.agent.id

Narzędzie tracer rozpoznaje identyfikator agenta z:

1. agent_id w metadanych węzła (nadpisanie na poziomie poszczególnych węzłów).
2. Parametr konstruktora (wartość domyślna agent_id dla wszystkich zakresów).

Dostosowywanie atrybutów za pomocą metadanych węzła

Można ustawić agent_name, agent_idi agent_description na węzeł przy użyciu metadanych LangGraph. Każdy klucz metadanych rozpoczynający się od gen_ai. jest również przekazywany jako atrybut span.

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

W przypadku korzystania z języka LangGraph można również ustawić metadane na węzeł w definicji grafu:

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

Referencja:

• Zakresy agentów OpenTelemetry GenAI
• OpenTelemetry GenAI Spans

Wyświetlanie śladów w Azure Monitor

Ślady są wysyłane do usługi aplikacja systemu Azure Insights i mogą być odpytywane przy użyciu Azure Monitor:

1. Przejdź do portalu Azure.

2. Przejdź do skonfigurowanego rozwiązania aplikacja systemu Azure Insights.

3. Korzystając z lewego paska nawigacyjnego, wybierz pozycję Zbadaj>Agentów (wersja zapoznawcza).

4. Zobaczysz pulpit nawigacyjny pokazujący wykonania agentów, modeli i narzędzi. Użyj tego widoku, aby zrozumieć ogólną aktywność agentów.

5. Wybierz Opcję Wyświetl ślady z działaniami agenta. Na panelu bocznym są wyświetlane wszystkie ślady generowane przez przebiegi agenta.

   

6. Wybierz jeden ze śladów. Powinieneś zobaczyć szczegóły.

   

Wyświetlanie śladów w płaszczyźnie sterowania Foundry

Jeśli wdrożyłeś rozwiązanie LangGraph albo LangChain, możesz zarejestrować to wdrożenie w Foundry Control Plane, aby uzyskać wgląd i zarządzanie.

Zarejestruj aplikację w Foundry Control Plane, aby wyświetlić ślady w portalu Foundry.

Wykonaj następujące kroki:

1. Upewnij się, że spełniasz wymagania dotyczące używania niestandardowej funkcji agenta warstwy kontrolnej Foundry:

   • Brama sztucznej inteligencji skonfigurowana w zasobie Foundry. Usługa Foundry używa Azure API Management do rejestrowania agentów jako interfejsów API.

   • Agent, który wdrażasz i udostępniasz za pośrednictwem dostępnego punktu końcowego. Punkt końcowy może być publicznym punktem końcowym lub punktem końcowym dostępnym z sieci, w której wdrażasz zasób foundry.

2. Upewnij się, że w projekcie skonfigurowano możliwość obserwacji.

3. Podczas konfigurowania klasy AzureAIOpenTelemetryTracerupewnij się, że używasz punktu końcowego projektu, na którym ma być zarejestrowany agent. Upewnij się, że skonfigurowałeś agent_id.

4. Przejdź do portalu Foundry.

5. Na pasku narzędzi wybierz pozycję Obsługa.

6. W okienku Przegląd wybierz pozycję Zarejestruj agenta.

7. Zostanie wyświetlony kreator rejestracji. Najpierw wypełnij szczegółowe informacje o agencie, który chcesz zarejestrować.

   • Adres URL agenta: punkt końcowy (adres URL), w którym agent jest uruchamiany i odbiera żądania.
   • Protokół: protokół komunikacyjny, który obsługuje agent.
   • Identyfikator agenta OpenTelemetry: agent_id parametr skonfigurowany w AzureAIOpenTelemetryTracer klasie.
   • Projekt: projekt, który skonfigurowałeś do odbierania śladów w klasie AzureAIOpenTelemetryTracer.
   • Nazwa agenta: nazwa agenta (może być taka sama jak agent_id).

8. Wywołaj agenta, aby upewnić się, że został uruchomiony.

9. Na pasku narzędzi wybierz pozycję Obsługa.

10. W okienku po lewej stronie wybierz pozycję Zasoby.

11. Wybierz utworzonego agenta.

12. Sekcja Ślady zawiera jeden wpis dla każdego wywołania HTTP wykonanego do punktu końcowego agenta.

    Aby wyświetlić szczegóły, wybierz wpis.

    

Rozwiązywanie problemów

• Jeśli żadne ślady nie są wyświetlane, sprawdź, czy connection_string jest skonfigurowany lub punkt końcowy projektu uwidacznia dane telemetryczne.
• Jeśli zawartość komunikatu zostanie zasłonięta, ustaw enable_content_recording=True w AzureAIOpenTelemetryTracer konstruktorze.
• Jeśli brakuje niektórych węzłów LangGraph, ustaw trace_all_langgraph_nodes=True lub dodaj metadane węzła otel_trace: True.

Powiązana zawartość

• Wprowadzenie do języka langchain-azure-ai
• Używanie języka LangGraph z usługą agenta
• Konfigurowanie integracji śledzenia dla frameworków agentów