Configuración del 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 agente 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
• Configuración de la distribución Microsoft OpenTelemetry 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

Requisitos previos

• Un proyecto de fundición. Para obtener más información, vea Create a Foundry project.
• Seguimiento conectado a un recurso de Application Insights de Azure Monitor. Para configurarlo, consulte Configuración del seguimiento en Microsoft Foundry.
• Rol de colaborador o superior en el recurso de Application Insights para la ingesta de seguimientos.
• Acceso al recurso conectado de Application Insights para ver rastros. En el caso de las consultas basadas en registros, es posible que también necesite acceso al área de trabajo de Log Analytics asociada.
• Python 3.10 o posterior (necesario para todos los ejemplos de código de este artículo).
• El microsoft-opentelemetry paquete (necesario para los ejemplos 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 al proyecto foundry.

2. Seleccione Control de acceso (IAM) .

3. Asigne un rol adecuado al usuario o grupo.

   Si usa consultas basadas en registros, empiece por conceder el rol lector de Log Analytics. Si las tablas de Log Analytics subyacentes están protegidas, conceda también el rol de Lector de datos de supervisión con privilegios.

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 las variables OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENTde entorno , OTEL_SEMCONV_STABILITY_OPT_INy AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING.
• No almacene secretos, credenciales ni tokens en indicaciones o parámetros 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 rastreo está habilitado para tu proyecto 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>Seguimientos.
3. Si confirma un nuevo seguimiento, aparece con segmentos en las operaciones del agente.

Los rastros suelen aparecer en un plazo de 2 a 5 minutos tras 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 con bibliotecas de instrumentación de OpenInference

Microsoft Foundry admite bibliotecas de instrumentación de OpenInference para el seguimiento de agentes de IA. Estos openinference-* paquetes proporcionan instrumentación automática para una amplia gama de frameworks y pueden utilizarse para rastrear tanto agentes alojados (agentes implementados en Foundry) como agentes que no son de Foundry (agentes alojados fuera de Foundry).

Examine los paquetes de instrumentación disponibles en PyPI. Para LangChain, consulte el ejemplo de LangChain de Distribución de Microsoft OpenTelemetry, que muestra cómo habilitar la exportación a Azure Monitor y la instrumentación automática de LangChain con use_microsoft_opentelemetry.

El requisito clave es correlacionar los seguimientos de OpenInference a un agente específico. La forma de lograrlo depende de dónde se ejecute el agente:

Agentes hospedados (implementados en Foundry)

Al implementar un agente en Foundry con uno de los paquetes del servidor de agentes hospedado, la correlación de seguimiento se controla automáticamente. El paquete de servidor:

• Configura la exportación a Azure Monitor de los intervalos de OpenTelemetry.
• Enriquece todos los intervalos con los atributos del proyecto, el nombre del agente, la versión del agente y el identificador del agente para que la interfaz de usuario de Foundry pueda consultarlos y mostrarlos.

No se requiere ninguna configuración adicional. Instale el paquete de instrumentación pertinente openinference-* para su framework y las trazas aparecerán automáticamente en el portal de Foundry.

agentes de Microsoft Agent Framework hospedados fuera de Foundry

Si el agente de Microsoft Agent Framework no se ha implementado con un paquete de servidor de agente hospedado de Foundry, configure la exportación a Azure Monitor y la instrumentación de Agent Framework con la distribución OpenTelemetry de Microsoft. La distribución puede habilitar el exportador de Azure Monitor y agregar atributos de identidad del agente a los spans:

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    azure_monitor_connection_string="...",
    sampling_ratio=1.0,
    enable_sensitive_data=True,
    instrumentation_options={
        "agent-framework": {
            "enabled": True,
            "agent_id": "ms-imagination-agent",
            "agent_name": "ms-imagination-agent",
        },
    },
)

Establezca azure_monitor_connection_string como el recurso de Application Insights conectado a su proyecto de Foundry. Para capturar contenido de solicitudes y finalizaciones durante el desarrollo, establezca enable_sensitive_data=True.

Agentes de LangChain hospedados fuera de Foundry

Si el agente no está implementado con un paquete del servidor de agentes hospedado de Foundry, configure la exportación a Azure Monitor y la instrumentación de LangChain con la Distribución de Microsoft OpenTelemetry. La distribución puede habilitar el exportador de Azure Monitor y agregar atributos de identidad de agente a intervalos de LangChain:

from microsoft.opentelemetry import use_microsoft_opentelemetry

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "weather_info_agent_771929",
            "agent_name": "Weather information agent",
        },
    },
)

Establezca APPLICATIONINSIGHTS_CONNECTION_STRING como el recurso de Application Insights conectado a su proyecto de Foundry. Para capturar contenido de solicitudes y finalizaciones durante el desarrollo, establezca OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=SPAN_AND_EVENT, OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimentaly AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING=true.

Configuración del seguimiento para LangChain y LangGraph

Use la Distribución de Microsoft OpenTelemetry para emitir seguimientos compatibles con OpenTelemetry para las operaciones de LangChain y LangGraph. Estos seguimientos aparecen en la vista Observabilidad>Seguimientos en el portal de Foundry.

• Convenciones semánticas de OpenTelemetry para IA generativa
• Ejemplo de LangChain de la distribución OpenTelemetry de Microsoft

Ejemplo: Agente LangChain v1 con seguimiento de IA de Azure

Utilice este ejemplo integral para instrumentar un agente LangChain v1 (versión preliminar) con la distribución OpenTelemetry de Microsoft. La distribución habilita la instrumentación automática de LangChain con las últimas convenciones semánticas de OpenTelemetry (OTel), para que pueda ver seguimientos detallados en la vista de Foundry Observability.

LangChain v1: Instalación de paquetes

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

LangChain v1: Configuración del entorno

• APPLICATIONINSIGHTS_CONNECTION_STRING: cadena de conexión de Azure Monitor Application Insights para el seguimiento.
• 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 resuelve las credenciales de Azure mediante DefaultAzureCredential, que admite variables de entorno, identidad administrada e inicio de sesión de Visual Studio Code.

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

LangChain v1: configuración de Tracer

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "weather_info_agent_771929",
            "agent_name": "Weather information agent",
        },
    },
)

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: Definición de herramientas e indicación

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"}}
    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 la distribución de Microsoft OpenTelemetry habilitada, todas las operaciones de LangChain v1 (llamadas a LLM, invocaciones de herramientas, pasos del agente) emiten intervalos de OpenTelemetry siguiendo las últimas convenciones semánticas. Estos seguimientos aparecen en la vista Observabilidad>Seguimientos en el portal de Foundry y están vinculados al recurso de Application Insights.

Verifica tus rastros de LangChain v1

Después de ejecutar el agente:

1. Espere de 2 a 5 minutos para que las trazas se propaguen.
2. En el portal de Foundry, vaya a Observabilidad>Seguimientos.
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 seguimiento de IA de Azure

Este ejemplo muestra un agente simple de LangGraph instrumentado con la distribución de Microsoft OpenTelemetry para emitir seguimientos compatibles con OpenTelemetry para pasos de grafo, llamadas a herramientas e invocaciones del modelo.

LangGraph: Instalación de paquetes

pip install \
  microsoft-opentelemetry \
  "langgraph>=1.0.0" \
  "langchain>=1.0.0" \
  langchain-openai \
  azure-identity \
  python-dotenv

LangGraph: Configuración del entorno

• APPLICATIONINSIGHTS_CONNECTION_STRING: cadena de conexión de Azure Monitor Application Insights para el seguimiento.
• 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

from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry

load_dotenv(override=True)

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_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 seguimiento

from langchain_core.messages import HumanMessage

config = {"configurable": {"thread_id": "1"}}
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 la distribución OpenTelemetry de Microsoft habilitada, la ejecución de LangGraph emite trazas compatibles con OpenTelemetry para llamadas al modelo, invocaciones de herramientas y transiciones del grafo. Estos seguimientos se envían a Application Insights y aparecen en la vista Observabilidad>Seguimientos del portal de Foundry.

Verifica las trazas de LangGraph

Después de ejecutar el agente:

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

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

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

Esta configuración mínima muestra cómo habilitar el seguimiento de Azure AI en una aplicación de LangChain 0.3 mediante la distribución de Microsoft OpenTelemetry y AzureChatOpenAI.

LangChain 0.3: Instalación de paquetes

pip install \
  "langchain>=0.3,<0.4" \
  langchain-openai \
  microsoft-opentelemetry \
  python-dotenv

LangChain 0.3: Configuración del entorno

• APPLICATIONINSIGHTS_CONNECTION_STRING: Cadena de conexión de Application Insights para el rastreo. Para encontrar este valor, abra el recurso de Application Insights en el portal de Azure, 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 de acceso API de Azure OpenAI.

LangChain 0.3: Seguimiento y configuración del modelo

import os
from dotenv import load_dotenv
from microsoft.opentelemetry import use_microsoft_opentelemetry
from langchain_openai import AzureChatOpenAI

load_dotenv(override=True)

# Enable Azure Monitor export and LangChain auto-instrumentation
use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    sampling_ratio=1.0,
    instrumentation_options={
        "langchain": {
            "enabled": True,
            "agent_id": "trip_planner_orchestrator_v3",
            "agent_name": "Trip Planner Orchestrator",
        },
    },
)

# Model: Azure OpenAI
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,
)

Con la distro ya inicializada, las operaciones de LangChain 0.3 se instrumentan automáticamente de forma global. 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.

Configurar el seguimiento para OpenAI Agents SDK

El SDK de agentes de OpenAI admite la instrumentación de OpenTelemetry. Use el siguiente fragmento de código para configurar 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 sistema de seguimiento está conectado para su proyecto. Si es necesario, siga Configurar el rastreo en Microsoft Foundry (Set up tracing in Microsoft Foundry).
3. Ejecute el agente al menos una vez.
4. En el portal de Foundry, vaya a Observabilidad>Seguimientos.
5. Si confirma un nuevo seguimiento, aparece con segmentos en las operaciones del agente.

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

Solución de problemas comunes

Contenido relacionado

• Obtenga información sobre los conceptos básicos y la arquitectura en la visión general del seguimiento del agente.
• Si aún no ha habilitado el seguimiento, consulte Configurar el 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.