Seguimiento de aplicaciones LangChain y LangGraph con Microsoft Foundry y Azure Monitor

Utilice el paquete de integración langchain-azure-ai para emitir trazas de OpenTelemetry desde aplicaciones LangChain y LangGraph y registrarlas en Aplicación de Azure Insights. En este artículo, configurará AzureAIOpenTelemetryTracer, lo asociará a su ejecutable e inspeccionará las trazas en Azure Monitor.

El agente de trazado emite trazas para la ejecución del agente, las llamadas a modelos, la ejecución de herramientas y las operaciones de recuperación de datos. Puede usarlo para aplicaciones que se ejecutan completamente de forma local, flujos híbridos que llaman a Foundry Agent Service, o soluciones LangGraph multiagente.

Requisitos previos

• Una suscripción Azure. Cree uno gratis.
• Un proyecto de fundición.
• Un modelo de chat de OpenAI implementado Azure (por ejemplo, gpt-4.1).
• Python 3.10 o posterior.
• CLI de Azure inició sesión (az login) para que DefaultAzureCredential pueda autenticarse.

Configuración del entorno

Instale los paquetes necesarios:

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

Establezca las variables de entorno que se usan en este artículo:

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

Para controlar si el contenido de los mensajes y las invocaciones de herramientas se registra en el seguimiento, pase enable_content_recording al constructor AzureAIOpenTelemetryTracer. La grabación de contenido está habilitada de forma predeterminada.

Crear el trazador

Cree una instancia de seguimiento y reutilízela en el flujo de trabajo.

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

¿Qué hace este fragmento de código: Configura un rastreador que resuelve la cadena de conexión asociada de Application Insights desde el punto de conexión del proyecto Foundry y habilita el rastreo para los nodos de LangGraph. Usa el parámetro agent_id para establecer el atributo gen_ai.agent.id al invocar a los agentes. El parámetro name establece el nombre del rastreador de OpenTelemetry.

El rastreador admite controles estándar para flujos de trabajo de producción.

• Pase connection_string para dirigirse a un recurso específico de Application Insights o configurando la variable de entorno APPLICATION_INSIGHTS_CONNECTION_STRING.
• Establezca trace_all_langgraph_nodes=True para realizar un seguimiento de todos los nodos de forma predeterminada.
• Use metadatos de nodo como otel_trace: True o otel_trace: False para incluir o omitir nodos específicos.
• Use message_keys y message_paths cuando los mensajes estén anidados bajo una forma de estado personalizada, por ejemplo chat_history.

Referencia:

• AzureAIOpenTelemetryTracer

Seguimiento de un agente

Comience con un agente de LangChain mínimo para que pueda comprobar el seguimiento rápidamente. Para LangGraph, adjunte el trazador con with_config en el gráfico compilado.

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.

Qué hace este fragmento de código: Crea un agente sencillo de LangGraph, adjunta el trazador e invoca al agente con un mensaje.

Referencia:

• LangGraph
• OpenTelemetry

Realizar el seguimiento de un runnable de LangChain

Comience con un flujo de LangChain mínimo para que pueda comprobar el seguimiento rápidamente.

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.

Qué hace este fragmento de código: Ejecuta una canalización estándar de LangChain y envía intervalos de chat a OpenTelemetry a través de AzureAIOpenTelemetryTracer.

Referencia:

• AzureAIChatCompletionsModel
• ChatPromptTemplate

Trazar un grafo de LangGraph

Para LangGraph, adjunte el trazador con with_config en el gráfico compilado. Este fragmento de código reutiliza model y tracer de ejemplos anteriores.

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

A continuación, puede ejecutar el gráfico como de costumbre:

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.

Qué hace este fragmento de código: Crea una aplicación sencilla de LangGraph, marca el nodo para el trazado y emite spans de invoke_agent y modelo/herramienta en el mismo trazado.

Referencia:

• LangGraph
• OpenTelemetry

Descripción de la estructura de seguimiento

El trazador emite intervalos que siguen las convenciones semánticas de OpenTelemetry GenAI. Cada tipo de intervalo usa un valor específico gen_ai.operation.name :

Los intervalos también llevan estos atributos clave:

• gen_ai.agent.name : el nombre del agente o del nodo.
• gen_ai.agent.id : se establece desde el parámetro del agent_id constructor.
• gen_ai.agent.description : una descripción del agente.
• gen_ai.provider.name : el proveedor de modelos (por ejemplo, openai, azure.ai.inference).
• gen_ai.request.model : el nombre del modelo usado para la inferencia.
• gen_ai.conversation.id — Subproceso o identificador de sesión, cuando esté disponible.
• gen_ai.usage.input_tokens / gen_ai.usage.output_tokens : recuentos de tokens de las respuestas del modelo.
• gen_ai.input.messages / gen_ai.output.messages — Contenido del mensaje (cuando la grabación de contenido está habilitada).

Cómo funciona el rastreador gen_ai.agent.name

El trazador determina el nombre del agente a partir del primer valor no vacío siguiendo este orden:

1. agent_name en los metadatos del nodo.
2. langgraph_node en los metadatos del nodo (establecido automáticamente por LangGraph).
3. agent_type en los metadatos del nodo.
4. Argumento name de palabra clave del callback de LangChain.
5. langgraph_path (último elemento) si los anteriores son marcadores de posición genéricos.
6. Identificador de cadena serializado o nombre de clase.
7. El parámetro name del constructor AzureAIOpenTelemetryTracer (valor predeterminado de reserva).

Cómo funciona el rastreador gen_ai.agent.id

Los rastreadores determinan el identificador del agente a partir de:

1. agent_id en los metadatos del nodo (sobrescritura por nodo).
2. Parámetro agent_id del constructor (valor predeterminado para todos los intervalos).

Personalización de atributos con metadatos de nodo

Puede establecer agent_name, agent_idy agent_description por nodo mediante metadatos de LangGraph. Cualquier clave de metadatos que comience con gen_ai. también se reenvía como un atributo 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)

Al usar LangGraph, también puede establecer metadatos por nodo en la definición del grafo:

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

Referencia:

• Intervalos de agente de OpenTelemetry GenAI
• Intervalos de GenAI de OpenTelemetry

Visualizar trazas en Azure Monitor

Los seguimientos se envían a Aplicación de Azure Insights y se pueden consultar mediante Azure Monitor:

1. Vaya al portal Azure.

2. Vaya a el Aplicación de Azure Insights que ha configurado.

3. Con la barra de navegación izquierda, seleccione Investigar>agentes (versión preliminar).

4. Verá un panel en el que se muestran las ejecuciones del agente, el modelo y las herramientas. Use esta vista para comprender la actividad general de los agentes.

5. Seleccione Ver seguimientos con ejecuciones del agente. El panel lateral muestra todas las trazas generadas por las ejecuciones de agentes.

   

6. Seleccione uno de los rastros. Deberías ver los detalles.

   

Ver trazas en el Plano de Control Foundry

Si ha implementado la solución LangGraph o LangChain, puede registrar esa implementación en el Plano de Control Foundry para obtener visibilidad y gobernanza.

Registre la aplicación en el plano de control de Foundry para ver los seguimientos en el portal de Foundry.

Siga estos pasos:

1. Asegúrese de cumplir los requisitos para usar la funcionalidad del agente personalizado del plano de control Foundry.

   • Una puerta de enlace de IA configurada en el recurso Foundry. Foundry usa Azure API Management para registrar agentes como API.

   • Un agente que implantas y expones a través de un punto de conexión accesible. El punto de conexión puede ser un punto de conexión público o un punto de conexión accesible desde la red donde se implementa el recurso Foundry.

2. Asegúrese de que tiene la observabilidad configurada en el proyecto.

3. Al configurar la clase AzureAIOpenTelemetryTracer, asegúrese de usar el punto de conexión del proyecto en el que desea que el agente se registre. Asegúrese de configurar agent_id.

4. Vaya al portal de Foundry.

5. En la barra de herramientas, seleccione Operar.

6. En el panel Información general , seleccione Registrar agente.

7. Aparece el asistente de registro. En primer lugar, complete los detalles sobre el agente que desea registrar.

   • Dirección URL del agente: el punto de conexión (URL) donde se ejecuta el agente y recibe solicitudes.
   • Protocolo: el protocolo de comunicación que admite el agente.
   • Identificador del agente de OpenTelemetry: el parámetro que configuró en la clase AzureAIOpenTelemetryTracer.
   • Proyecto: El proyecto que configuró para recibir rastreos en la clase AzureAIOpenTelemetryTracer.
   • Nombre del agente: el nombre del agente (puede ser el mismo que agent_id).

8. Invoque al agente para asegurarse de que ejecuta procesos.

9. En la barra de herramientas, seleccione Operar.

10. En el panel izquierdo, seleccione Activos.

11. Seleccione el agente que ha creado.

12. En la sección Trazas se muestra una entrada para cada llamada HTTP realizada al endpoint del agente.

    Para ver los detalles, seleccione una entrada.

    

Solución de problemas

• Si no aparecen rastros, compruebe que bien connection_string está configurado, o que el punto de conexión de su proyecto expone telemetría.
• Si el contenido del mensaje aparece censurado, establezca enable_content_recording=True en el AzureAIOpenTelemetryTracer constructor .
• Si faltan algunos nodos de LangGraph, establezca trace_all_langgraph_nodes=True o agregue metadatos otel_trace: Truede nodo.

Contenido relacionado

• Introducción a langchain-azure-ai
• Uso de LangGraph con el servicio de agente
• Configuración de integraciones de seguimiento para marcos de agente