Configurar el seguimiento para marcos de trabajo 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
• Configurar el langchain-azure-ai trazador 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 Foundry con seguimiento conectado a Azure Monitor Application Insights.
• Contribuyente o un rol de nivel superior en el recurso de Application Insights para la ingestión de trazas.
• 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).
• La langchain-azure-ai versión del paquete 0.1.0 o posterior (necesaria para los 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 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.

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 indicaciones o parámetros de herramienta.

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

Configurar el seguimiento para Microsoft Agent Framework

Microsoft Foundry tiene integraciones nativas con Microsoft Agent Framework. 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. Confirme que aparece una nueva traza con espacios para 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 del marco del agente de Microsoft: observabilidad

Configuración del seguimiento para LangChain y LangGraph

Utilice el paquete langchain-azure-ai para emitir trazas 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
• paquete langchain-azure-ai en PyPI

Ejemplo: Agente LangChain v1 con seguimiento de IA de Azure

Utiliza este ejemplo de extremo a extremo para instrumentar un agente LangChain v1 (versión preliminar) mediante el langchain-azure-ai trazador. Este rastreador implementa las últimas convenciones semánticas de OpenTelemetry (OTel), por lo que puede ver trazas detalladas 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 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
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://ai.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: ejecución del 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 langChain v1 (llamadas LLM, invocaciones de herramientas, pasos del agente) emiten intervalos de OpenTelemetry mediante las convenciones semánticas más recientes. Estos trazas aparecen en la vista Observabilidad>Trazas en el portal de Foundry y están vinculados a tu 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 intervalos de llamadas LLM, invocaciones de herramientas y pasos 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

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

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://ai.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"}, "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 trazas fluyen a Application Insights y aparecen en la vista Observabilidad - Trazas en el 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 especificado (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 como habilitar el trazado de IA de Azure en una aplicación de LangChain 0.3 usando 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 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 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,
)

Conecte callbacks=[azure_tracer] a sus cadenas, herramientas o agentes para garantizar el seguimiento de las operaciones de LangChain 0.3. Después de ejecutar la cadena o el agente, los rastros aparecen en la vistaObservabilidad en>Seguimientos del portal de Foundry en un plazo de 2 a 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 APPLICATION_INSIGHTS_CONNECTION_STRING no está configurado, el exportador vuelve a 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. Confirme que aparece una nueva traza con espacios para 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

Pasos siguientes

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