Compartir a través de

Configurar el seguimiento para frameworks de agentes de IA (vista previa)

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin acuerdo de nivel de servicio y no se recomienda para las cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios para las versiones preliminares de Microsoft Azure.

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
  • Configura el langchain-azure-ai rastreador 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 foundry con seguimiento conectado a Application Insights.
  • Colaborador o rol superior en el recurso de Application Insights para la ingestión de trazas.
  • Acceso al recurso de Application Insights conectado para ver seguimientos. 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 Azure Portal, 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 mensajes o argumentos de herramienta.

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

Nota:

Los datos de seguimiento almacenados en Application Insights están sujetos a la configuración de retención de datos del área de trabajo y a los precios de Azure Monitor. Para la administración de costos, considere la posibilidad de ajustar las tasas de muestreo o los períodos de retención en producción. Consulte Precios de Azure Monitor y Configuración de la retención y el archivo de datos.

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 marcos emiten automáticamente seguimientos cuando el seguimiento está habilitado para el 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>Trazas.
  3. Confirme que aparece un nuevo rastro con segmentos para 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:

Configuración del seguimiento para LangChain y LangGraph

Nota:

La integración de seguimiento para LangChain y LangGraph solo está disponible actualmente en Python.

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

Ejemplo: Agente langChain v1 con seguimiento de Azure AI

Utiliza este ejemplo integral para instrumentar un agente LangChain v1 (versión preliminar) mediante el langchain-azure-ai trazador. 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 Application Insights de Azure Monitor para el seguimiento.
  • AZURE_OPENAI_ENDPOINT: dirección 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.
  • El SDK resuelve las credenciales de Azure mediante DefaultAzureCredential, que admite variables de entorno, identidad administrada y inicio de sesión de 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 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 de Observabilidad>Seguimientos en el portal de Foundry y están vinculados al recurso de Application Insights.

Sugerencia

Después de ejecutar el agente, espere unos minutos para que aparezcan los rastros. Si no ve seguimientos, compruebe que la cadena de conexión de Application Insights es correcta y compruebe la sección Solución de problemas comunes .

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

En este ejemplo se muestra un agente simple de LangGraph 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 Application Insights de Azure Monitor para el seguimiento.
  • AZURE_OPENAI_ENDPOINT: dirección 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.

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 de Observabilidad>Seguimientos del portal Foundry.

Sugerencia

Cada nodo de grafo y transición perimetral crea un intervalo independiente, lo que facilita la visualización del flujo de decisión del agente.

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 especificado (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 el seguimiento de Azure AI

Esta configuración mínima muestra cómo habilitar el trazado de Azure AI en una aplicación LangChain 0.3 mediante el langchain-azure-ai tracer 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 seguimiento. Para encontrar este valor, abra el recurso de Application Insights en Azure Portal, seleccione Información general y copie la cadena de conexión.
  • AZURE_OPENAI_ENDPOINT: dirección 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 API de Azure OpenAI.

Nota:

En este ejemplo se usa la autenticación de clave de API para simplificar. En el caso de las cargas de trabajo de producción, use DefaultAzureCredential con get_bearer_token_provider como se muestra en los ejemplos LangChain v1 y LangGraph.

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

Adjunte 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 tu cadena o agente, las trazas aparecen en la vista de Observabilidad>Traces en el portal de Foundry dentro de 2 a 5 minutos.

Configuración del 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 los intervalos de seguimiento y exportación a Azure Monitor. Si no se establece APPLICATION_INSIGHTS_CONNECTION_STRING, 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 seguimiento está habilitado para su 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. Confirme que aparece un nuevo rastro con segmentos para 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

Cuestión Causa Resolución
No ves rastros en Foundry El seguimiento no está conectado, no hay tráfico reciente o la ingestión está retrasada. Confirme la conexión de Application Insights, genere tráfico nuevo y actualice después de 2 a 5 minutos.
No se ven intervalos LangChain ni LangGraph Las devoluciones de llamada de trazado no están vinculadas al proceso de ejecución Confirme que pasa el seguimiento en callbacks (por ejemplo, config = {"callbacks": [azure_tracer]}) para la ejecución de la que desea realizar el seguimiento.
Los intervalos de LangChain aparecen, pero faltan llamadas a herramientas Las herramientas no están vinculadas al modelo o el nodo de herramientas no está configurado. Verifique que las herramientas se pasen a bind_tools() en el modelo y que los nodos de herramienta se agreguen al grafo.
Los rastros aparecen pero están incompletos o faltan segmentos La grabación de contenido está deshabilitada o algunas operaciones no se instrumentan Habilite enable_content_recording=True para la telemetría completa. Para las operaciones personalizadas, agregue intervalos manuales mediante el SDK de OpenTelemetry.
Verá errores de autorización cuando consulta la telemetría. Faltan permisos de RBAC en Application Insights o Log Analytics Confirme el acceso en Control de acceso (IAM) para los recursos conectados. Para las consultas de registro, asigne el rol Lector de Log Analytics.
Aparece contenido confidencial en registros La grabación de contenido está habilitada y las solicitudes, los argumentos de la herramienta o las salidas incluyen datos confidenciales. Deshabilite la grabación de contenido en producción y redacte datos confidenciales antes de que ingresen a la telemetría.

Pasos siguientes

  • Last updated on