Configurar el seguimiento para plataformas de agentes de IA (versión preliminar)

Cuando los agentes de inteligencia artificial se comportan inesperadamente en producción, el seguimiento proporciona la visibilidad para identificar rápidamente la causa principal. El seguimiento captura datos de telemetría detallados, incluidas las llamadas LLM, las invocaciones de herramientas y los flujos de decisión del agente, para que pueda depurar problemas, supervisar la latencia y comprender el comportamiento del agente entre las solicitudes.

Microsoft Foundry proporciona integraciones de seguimiento para marcos de agentes populares que requieren cambios mínimos en el código. En este artículo aprenderá a:

• Configuración del seguimiento automático para Microsoft Agent Framework y Kernel Semántico
• Configurar el rastreador de langchain-azure-ai para LangChain y LangGraph
• Instrumentación del SDK de agentes de OpenAI con OpenTelemetry
• Verificar que las trazas aparecen en el portal de Foundry
• Solución de problemas comunes de seguimiento

Prerrequisitos

• Un proyecto de Foundry con rastreo conectado a los Application Insights.
• Colaborador o rol superior en el recurso de Application Insights para el procesamiento de seguimientos.
• Accede al recurso de Application Insights conectado para ver rastros. En el caso de las consultas basadas en registros, es posible que también necesite acceso al espacio de trabajo de Log Analytics asociado.
• Python 3.10 o posterior (necesario para todos los ejemplos de código de este artículo).
• El paquete langchain-azure-ai versión 0.1.0 o posterior (necesario para ejemplos de LangChain y LangGraph).
• Si usa LangChain o LangGraph, un entorno de Python con pip instalado.

Confirmación de que puede ver la telemetría

Para ver los datos de seguimiento, asegúrese de que la cuenta tiene acceso al recurso de Application Insights conectado.

1. En el portal de Azure, abra el recurso de "Application Insights" conectado a su proyecto Foundry.

2. Seleccione Access control (IAM).

3. Asigne un rol adecuado al usuario o grupo.

   Si usa consultas basadas en registros, empiece por conceder el rol de "Log Analytics Reader".

Seguridad y privacidad

El seguimiento puede capturar información confidencial (por ejemplo, entradas de usuario, salidas del modelo y argumentos y resultados de la herramienta).

• Habilite la grabación de contenido durante el desarrollo y la depuración para ver datos completos de solicitud y respuesta. Deshabilite la grabación de contenido en entornos de producción para proteger los datos confidenciales. En los ejemplos de este artículo, la grabación de contenido se controla mediante la configuración como enable_content_recording y OTEL_RECORD_CONTENT.
• No almacene secretos, credenciales ni tokens en mensajes o argumentos de herramienta.

Para obtener más instrucciones, consulte Seguridad y privacidad.

Configuración del seguimiento para Microsoft Agent Framework y el Kernel Semántico

Microsoft Foundry tiene integraciones nativas con Microsoft Agent Framework y Kernel semántico. Los agentes creados con cualquiera de los frameworks emiten automáticamente trazas cuando el trazado está habilitado para tu proyecto de Foundry; no se requiere código ni paquetes adicionales.

Para comprobar que el seguimiento funciona:

1. Ejecute el agente al menos una vez.
2. En el portal de Foundry, vaya a Observabilidad>Trazas.
3. Si confirma un nuevo seguimiento, aparece con segmentos en las operaciones del agente.

Los seguimientos suelen aparecer en un plazo de 2 a 5 minutos después de la ejecución del agente. Para obtener una configuración avanzada, consulte la documentación específica del marco de trabajo:

• Flujos de trabajo de Microsoft Agent Framework: observabilidad
• Observabilidad semántica del kernel

Configuración del seguimiento para LangChain y LangGraph

Use el paquete langchain-azure-ai para emitir intervalos compatibles con OpenTelemetry para las operaciones LangChain y LangGraph. Estos seguimientos aparecen en la vista Observabilidad>Seguimientos en el portal de Foundry.

• Convenciones semánticas de OpenTelemetry para IA generativa
• paquete langchain-azure-ai en PyPI

Ejemplo: Agente LangChain v1 con trazado de IA de Azure

Utilice este ejemplo de un extremo a otro para instrumentar un agente LangChain v1 (versión preliminar) mediante el trazador langchain-azure-ai. Este trazador implementa las últimas convenciones semánticas de OpenTelemetry (OTel), de modo que puede ver trazas enriquecidas en la vista de observabilidad de Foundry.

LangChain v1: Instalación de paquetes

pip install \
  langchain-azure-ai \
  langchain \
  langgraph \
  langchain-openai \
  azure-identity \
  python-dotenv \
  rich

LangChain v1: Configuración del entorno

• APPLICATION_INSIGHTS_CONNECTION_STRING: Cadena de conexión de Azure Monitor Application Insights para rastreo.
• AZURE_OPENAI_ENDPOINT: dirección URL del punto de conexión de OpenAI de Azure.
• AZURE_OPENAI_CHAT_DEPLOYMENT: nombre de implementación del modelo de chat.
• AZURE_OPENAI_VERSION: versión de API, por ejemplo 2024-08-01-preview.
• El SDK utiliza las credenciales de Azure mediante DefaultAzureCredential, que admite variables de entorno, identidad administrada y autenticación en VS Code.

Almacene estos valores en un .env archivo para el desarrollo local.

LangChain v1: configuración de Tracer

from dotenv import load_dotenv
import os
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Weather information agent",
    id="weather_info_agent_771929",
)

tracers = [azure_tracer]

LangChain v1: configuración del modelo (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
)

LangChain v1: Definir herramientas e indicaciones

from dataclasses import dataclass
from langchain_core.tools import tool

system_prompt = """You are an expert weather forecaster, who speaks in puns.

You have access to two tools:

- get_weather_for_location: use this to get the weather for a specific location
- get_user_location: use this to get the user's location

If a user asks you for the weather, make sure you know the location.
If you can tell from the question that they mean wherever they are,
use the get_user_location tool to find their location."""

# Mock user locations keyed by user id (string)
USER_LOCATION = {
    "1": "Florida",
    "2": "SF",
}

@dataclass
class UserContext:
    user_id: str

@tool
def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

LangChain v1: uso del contexto en tiempo de ejecución y definición de una herramienta de información de usuario

from langgraph.runtime import get_runtime
from langchain_core.runnables import RunnableConfig

@tool
def get_user_info(config: RunnableConfig) -> str:
    """Retrieve user information based on user ID."""
    runtime = get_runtime(UserContext)
    user_id = runtime.context.user_id
    return USER_LOCATION[user_id]

LangChain v1: Creación del agente

from langchain.agents import create_agent
from langgraph.checkpoint.memory import InMemorySaver
from dataclasses import dataclass

@dataclass
class WeatherResponse:
    conditions: str
    punny_response: str

checkpointer = InMemorySaver()

agent = create_agent(
    model=model,
    prompt=system_prompt,
    tools=[get_user_info, get_weather],
    response_format=WeatherResponse,
    checkpointer=checkpointer,
)

LangChain v1: ejecutar el agente con seguimiento

from rich import print

def main():
    config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
    context = UserContext(user_id="1")

    r1 = agent.invoke(
        {"messages": [{"role": "user", "content": "what is the weather outside?"}]},
        config=config,
        context=context,
    )
    print(r1.get("structured_response"))

    r2 = agent.invoke(
        {"messages": [{"role": "user", "content": "Thanks"}]},
        config=config,
        context=context,
    )
    print(r2.get("structured_response"))

if __name__ == "__main__":
    main()

Con langchain-azure-ai habilitado, todas las operaciones de LangChain v1 (llamadas LLM, invocaciones de herramientas, pasos del agente) emiten intervalos de OpenTelemetry mediante las convenciones semánticas más recientes. Estos seguimientos aparecen en la vista Observabilidad>Seguimientos en el portal de Foundry y están vinculados al recurso de Application Insights.

Verifica tus seguimientos de LangChain v1

Después de ejecutar el agente:

1. Espere entre 2 y 5 minutos para que las trazas se propaguen.
2. En el portal de Foundry, vaya a Observabilidad>Trazas.
3. Busque un seguimiento con el nombre especificado (por ejemplo, "Agente de información meteorológica").
4. Expanda el seguimiento para ver segmentos de llamadas al LLM, invocaciones de herramientas y procedimientos del agente.

Si no ve rastros, consulte la sección Solución de problemas comunes.

Ejemplo: Agente de LangGraph con rastreo de IA de Azure

En este ejemplo se muestra un agente LangGraph simple instrumentado con langchain-azure-ai para emitir trazas compatibles con OpenTelemetry para pasos de grafos, llamadas a herramientas e invocaciones de modelo.

LangGraph: Instalación de paquetes

pip install \
  langchain-azure-ai \
  langgraph>=1.0.0 \
  langchain>=1.0.0 \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: Configuración del entorno

• APPLICATION_INSIGHTS_CONNECTION_STRING: Cadena de conexión de Azure Monitor Application Insights para rastreo.
• AZURE_OPENAI_ENDPOINT: dirección URL del punto de conexión de OpenAI de Azure.
• AZURE_OPENAI_CHAT_DEPLOYMENT: nombre de implementación del modelo de chat.
• AZURE_OPENAI_VERSION: versión de API, por ejemplo 2024-08-01-preview.

Almacene estos valores en un .env archivo para el desarrollo local.

Configuración del seguimiento de LangGraph

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=os.getenv("OTEL_RECORD_CONTENT", "true").lower() == "true",
    name="Music Player Agent",
)

LangGraph: Herramientas

from langchain_core.tools import tool

@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!"

tools = [play_song_on_apple, play_song_on_spotify]

LangGraph: configuración del modelo (Azure OpenAI)

import os
import azure.identity
from langchain_openai import AzureChatOpenAI

token_provider = azure.identity.get_bearer_token_provider(
    azure.identity.DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

model = AzureChatOpenAI(
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    openai_api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    azure_ad_token_provider=token_provider,
).bind_tools(tools, parallel_tool_calls=False)

Compilación del flujo de trabajo de LangGraph

from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode
from langgraph.checkpoint.memory import MemorySaver

tool_node = ToolNode(tools)

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.invoke(messages)
    return {"messages": [response]}

workflow = StateGraph(MessagesState)
workflow.add_node("agent", call_model)
workflow.add_node("action", tool_node)

workflow.add_edge(START, "agent")
workflow.add_conditional_edges(
    "agent",
    should_continue,
    {
        "continue": "action",
        "end": END,
    },
)
workflow.add_edge("action", "agent")

memory = MemorySaver()
app = workflow.compile(checkpointer=memory)

LangGraph: Ejecutar con trazabilidad

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}, "callbacks": [azure_tracer]}
input_message = HumanMessage(content="Can you play Taylor Swift's most popular song?")

for event in app.stream({"messages": [input_message]}, config, stream_mode="values"):
    event["messages"][-1].pretty_print()

Con langchain-azure-ai habilitado, la ejecución de LangGraph emite intervalos compatibles con OpenTelemetry para llamadas de modelo, invocaciones de herramientas y transiciones de grafos. Estos seguimientos se envían a Application Insights y aparecen en la vista Observabilidad>Seguimientos del portal de Foundry.

Verifica tus trazas de LangGraph

Después de ejecutar el agente:

1. Espere entre 2 y 5 minutos para que las trazas se propaguen.
2. En el portal de Foundry, vaya a Observabilidad>Trazas.
3. Busque un seguimiento con el nombre que haya indicado (por ejemplo, "Agente de reproductor de música").
4. Expanda la traza para visualizar intervalos de nodos de grafo, llamadas de modelo e invocaciones de herramientas.

Si no ve rastros, consulte la sección Solución de problemas comunes.

Ejemplo: Configuración de LangChain 0.3 con Seguimiento de IA de Azure

Esta configuración mínima muestra cómo habilitar la trazabilidad de Azure IA en una aplicación LangChain 0.3 utilizando el trazador langchain-azure-ai y AzureChatOpenAI.

LangChain 0.3: Instalación de paquetes

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  langchain-azure-ai \
  python-dotenv

LangChain 0.3: Configuración del entorno

• APPLICATION_INSIGHTS_CONNECTION_STRING: Cadena de conexión de Application Insights para el rastreo. Para encontrar este valor, abra el recurso de Application Insights en el Azure portal, seleccione Overview y copie el Connection String.
• AZURE_OPENAI_ENDPOINT: URL del punto de conexión de Azure OpenAI.
• AZURE_OPENAI_CHAT_DEPLOYMENT: nombre de implementación del modelo de chat.
• AZURE_OPENAI_VERSION: versión de API, por ejemplo 2024-08-01-preview.
• AZURE_OPENAI_API_KEY: Clave API de Azure OpenAI.

LangChain 0.3: Seguimiento y configuración del modelo

import os
from dotenv import load_dotenv
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Tracer: emits spans conforming to updated OTel spec
azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Trip Planner Orchestrator",
    id="trip_planner_orchestrator_v3",
)
tracers = [azure_tracer]

# Model: Azure OpenAI with callbacks for tracing
llm = AzureChatOpenAI(
    azure_deployment=os.environ.get("AZURE_OPENAI_CHAT_DEPLOYMENT"),
    api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
    azure_endpoint=os.environ.get("AZURE_OPENAI_ENDPOINT"),
    api_version=os.environ.get("AZURE_OPENAI_VERSION"),
    temperature=0.2,
    callbacks=tracers,
)

Añada callbacks=[azure_tracer] a las cadenas, herramientas o agentes para asegurarse de que se realiza un seguimiento de las operaciones de LangChain 0.3. Después de ejecutar la cadena o agente, los seguimientos aparecen en la vista de Observabilidad>Seguimientos en el portal de Foundry tras 2-5 minutos.

Configuración del seguimiento para el SDK de agentes de OpenAI

El SDK de agentes de OpenAI admite la instrumentación de OpenTelemetry. Use el siguiente fragmento de código para configurar los intervalos de seguimiento y exportación en Azure Monitor. Si no se ha establecido APPLICATION_INSIGHTS_CONNECTION_STRING, el exportador activa la consola para la depuración local.

Antes de ejecutar el ejemplo, instale los paquetes necesarios:

pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter

import os
from opentelemetry import trace
from opentelemetry.instrumentation.openai_agents import OpenAIAgentsInstrumentor
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

# Configure tracer provider + exporter
resource = Resource.create({
    "service.name": os.getenv("OTEL_SERVICE_NAME", "openai-agents-app"),
})
provider = TracerProvider(resource=resource)

conn = os.getenv("APPLICATION_INSIGHTS_CONNECTION_STRING")
if conn:
    from azure.monitor.opentelemetry.exporter import AzureMonitorTraceExporter
    provider.add_span_processor(
        BatchSpanProcessor(AzureMonitorTraceExporter.from_connection_string(conn))
    )
else:
    provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))

trace.set_tracer_provider(provider)

# Instrument the OpenAI Agents SDK
OpenAIAgentsInstrumentor().instrument(tracer_provider=trace.get_tracer_provider())

# Example: create a session span around your agent run
tracer = trace.get_tracer(__name__)
with tracer.start_as_current_span("agent_session[openai.agents]"):
    # ... run your agent here
    pass

Verificar trazas en el portal de Foundry

1. Inicie sesión en Microsoft Foundry. Asegúrese de que el interruptor New Foundry está activado. Estos pasos hacen referencia a Foundry (nuevo).
2. Confirme que el seguimiento está habilitado para el proyecto. Si es necesario, siga con Configurar el seguimiento en Microsoft Foundry.
3. Ejecute el agente al menos una vez.
4. En el portal de Foundry, vaya a Observabilidad>Trazas.
5. Si confirma un nuevo seguimiento, aparece con segmentos en las operaciones del agente.

Los seguimientos suelen aparecer en un plazo de 2 a 5 minutos después de la ejecución del agente. Si los rastros aún no aparecen después de este tiempo, consulte Solución de problemas comunes.

Solucionar problemas comunes

Pasos siguientes

• Conozca los conceptos básicos y la arquitectura en la Información general sobre los seguimientos de agentes.
• Si aún no ha habilitado el seguimiento, consulte Configuración del seguimiento en Microsoft Foundry.
• Visualice las métricas de rendimiento y estado del agente con el panel de supervisión del agente.
• Explore las funcionalidades de observabilidad más amplias en Observabilidad en la inteligencia artificial generativa.