Configurare il tracciamento per i framework degli agenti di intelligenza artificiale (anteprima)

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per altre informazioni, vedere Condizioni supplementari per l'utilizzo delle anteprime di Microsoft Azure.

Nota

La funzionalità di rastremazione è generalmente disponibile solo per gli agenti prompt. I flussi di lavoro, gli agenti ospitati e gli agenti personalizzati sono in fase di anteprima.

Quando gli agenti di intelligenza artificiale si comportano in modo imprevisto nell'ambiente di produzione, la traccia offre la visibilità per identificare rapidamente la causa radice. La traccia acquisisce dati di telemetria dettagliati, tra cui chiamate LLM, chiamate agli strumenti e flussi decisionali dell'agente, in modo da poter eseguire il debug dei problemi, monitorare la latenza e comprendere il comportamento dell'agente tra le richieste.

Microsoft Foundry fornisce integrazioni di traccia per i framework agente più diffusi che richiedono modifiche minime al codice. Questo articolo illustra come:

  • Configurare il tracciamento automatico per Microsoft Agent Framework
  • Configurare il langchain-azure-ai rilevatore per LangChain e LangGraph
  • Strumentare l'SDK degli OpenAI Agents con OpenTelemetry
  • Verificare che le tracce appaiano nel portale Foundry
  • Risolvere i problemi comuni di tracciamento

Prerequisiti

  • Un progetto Foundry con tracciamento collegato all’Monitoraggio di Azure Application Insights.
  • Ruolo collaboratore o superiore nella risorsa di Application Insights per l'inserimento di tracce.
  • Accesso alla risorsa di Application Insights connessa per la visualizzazione delle tracce. Per le query basate su log, potrebbe essere necessario accedere anche all'area di lavoro Log Analytics associata.
  • Python 3.10 o versione successiva (obbligatorio per tutti gli esempi di codice in questo articolo).
  • Il langchain-azure-ai pacchetto versione 0.1.0 o successiva (obbligatorio per gli esempi LangChain e LangGraph).
  • Per utilizzare LangChain o LangGraph, è necessario disporre di un ambiente Python con pip installato.

Verificare che sia possibile visualizzare i dati di telemetria

Per visualizzare i dati di traccia, assicurarsi che l'account abbia accesso alla risorsa di Application Insights connessa.

  1. Nel portale di Azure aprire la risorsa di Application Insights connessa al progetto Foundry.

  2. Selezionare Controllo di accesso (IAM).

  3. Assegnare un ruolo appropriato all'utente o al gruppo.

    Se si usano query basate su log, iniziare concedendo il ruolo Log Analytics Reader.

Sicurezza e privacy

La traccia può acquisire informazioni riservate, ad esempio input utente, output del modello e argomenti e risultati degli strumenti.

  • Abilitare la registrazione del contenuto durante lo sviluppo e il debug per visualizzare i dati completi relativi a richieste e risposte. Disabilitare la registrazione del contenuto negli ambienti di produzione per proteggere i dati sensibili. Negli esempi di questo articolo la registrazione del contenuto è controllata da impostazioni come enable_content_recording e OTEL_RECORD_CONTENT.
  • Non archiviare segreti, credenziali o token nei prompt o negli argomenti dello strumento.

Per altre indicazioni, vedere Sicurezza e privacy.

Nota

I dati di traccia archiviati in Application Insights sono soggetti alle impostazioni di conservazione dei dati dell'area di lavoro e ai prezzi Monitoraggio di Azure. Per la gestione dei costi, valutare la possibilità di modificare i tassi di campionamento o i periodi di conservazione nell'ambiente di produzione. Vedere Monitoraggio di Azure prezzi e Configurare la conservazione e l'archivio dei dati.

Configurare il tracciamento per Microsoft Agent Framework

Microsoft Foundry include integrazioni native con Microsoft Agent Framework. Gli agenti compilati con uno dei due framework generano automaticamente tracce quando la traccia è abilitata per il progetto Foundry. Non sono necessari codice o pacchetti aggiuntivi.

Per verificare che il tracciamento sia operativo:

  1. Eseguire l'agente almeno una volta.
  2. Nel portale Foundry, vai a Osservabilità>Tracce.
  3. Verificare che venga visualizzata una nuova traccia con intervalli per le operazioni dell'agente.

Le tracce vengono in genere visualizzate entro 2-5 minuti dall'esecuzione dell'agente. Per la configurazione avanzata, vedere la documentazione specifica del framework:

Configurare il tracciamento per LangChain e LangGraph

Nota

L'integrazione della traccia per LangChain e LangGraph è attualmente disponibile solo in Python.

Usare il langchain-azure-ai pacchetto per generare intervalli conformi a OpenTelemetry per le operazioni LangChain e LangGraph. Queste tracce vengono visualizzate nella visualizzazione Osservabilità>Tracce nel portale di Foundry.

Esempio: Agente LangChain v1 con tracciamento AI di Azure

Usare questo esempio end-to-end per attrezzare un agente LangChain v1 (anteprima) usando il langchain-azure-ai tracciatore. Questo tracer implementa le più recenti convenzioni semantiche di OpenTelemetry (OTel), in modo da poter visualizzare tracce dettagliate nella visualizzazione di osservabilità Foundry.

LangChain v1: Installare i pacchetti

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

LangChain v1: Configurare l'ambiente

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Stringa di connessione di Monitoraggio di Azure Application Insights per il tracciamento.
  • AZURE_OPENAI_ENDPOINT: URL dell'endpoint di OpenAI su Azure.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: nome della distribuzione del modello di chat.
  • AZURE_OPENAI_VERSION: versione dell'API, ad esempio 2024-08-01-preview.
  • L'SDK risolve le credenziali Azure usando DefaultAzureCredential, che supporta variabili di ambiente, identità gestita e accesso a VS Code.

Archiviare questi valori in un .env file per lo sviluppo locale.

LangChain v1: Configurazione del Tracciatore

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: configurazione del modello (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: Definire gli strumenti software e il prompt

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: usare il contesto di runtime e definire uno strumento user-info

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: Creare l'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: Eseguire l'agente con tracciamento

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 l'abilitazione, tutte le operazioni LangChain v1 (chiamate LLM, chiamate degli strumenti, passaggi dell'agente) generano intervalli OpenTelemetry usando le convenzioni semantiche più recenti. Queste tracce vengono visualizzate nella visualizzazione Tracce>Osservabilità nel portale Foundry e sono collegate alla risorsa di Application Insights.

Suggerimento

Dopo aver eseguito l'agente, attendere alcuni minuti per visualizzare le tracce. Se le tracce non vengono visualizzate, verificare che la stringa di connessione di Application Insights sia corretta e controllare la sezione Risolvere i problemi comuni.

Verifica le tracce di LangChain v1

Dopo aver eseguito l'agente:

  1. Attendere 2-5 minuti per la propagazione delle tracce.
  2. Nel portale Foundry, vai a Osservabilità>Tracce.
  3. Cercare una traccia con il nome specificato, ad esempio "Agente informazioni meteo".
  4. Espandere la traccia per visualizzare gli intervalli per le chiamate LLM, le chiamate agli strumenti e i passaggi dell'agente.

Se non vengono visualizzate tracce, vedere la sezione Risolvere i problemi comuni .

L'esempio: L'agente LangGraph con tracciamento AI di Azure

Questo esempio mostra un semplice agente LangGraph instrumentato con langchain-azure-ai per generare tracce conformi a OpenTelemetry per i passaggi del grafo, le chiamate agli strumenti e le chiamate al modello.

LangGraph: Installare i pacchetti

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

LangGraph: Configurare l'ambiente

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Stringa di connessione di Monitoraggio di Azure Application Insights per il tracciamento.
  • AZURE_OPENAI_ENDPOINT: URL dell'endpoint di OpenAI su Azure.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: nome della distribuzione del modello di chat.
  • AZURE_OPENAI_VERSION: versione dell'API, ad esempio 2024-08-01-preview.

Archiviare questi valori in un .env file per lo sviluppo locale.

Configurazione di LangGraph tracer

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

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: configurazione del modello (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)

Compilare il flusso di lavoro 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: Esegui con tracciamento

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 l'abilitazione, l'esecuzione di LangGraph genera intervalli conformi a OpenTelemetry per chiamate di modello, chiamate agli strumenti e transizioni di grafi. Queste tracce fluiscono verso Application Insights e appaiono nella vista osservabilità>Tracce nel portale Foundry.

Suggerimento

Ogni nodo del grafo e la transizione dei bordi crea un intervallo separato, semplificando la visualizzazione del flusso decisionale dell'agente.

Verifica le tracce LangGraph

Dopo aver eseguito l'agente:

  1. Attendere 2-5 minuti per la propagazione delle tracce.
  2. Nel portale Foundry, vai a Osservabilità>Tracce.
  3. Cercare una traccia con il nome specificato ,ad esempio "Music Player Agent".
  4. Espandere la traccia per visualizzare gli intervalli per i nodi del grafo, le chiamate agli strumenti e le chiamate al modello.

Se non vengono visualizzate tracce, vedere la sezione Risolvere i problemi comuni .

Esempio: Configurazione di LangChain 0.3 con tracciamento sull'intelligenza artificiale di Azure

Questa configurazione essenziale illustra come abilitare il tracciamento Azure AI in un'applicazione LangChain 0.3 usando il tracciatore langchain-azure-ai e AzureChatOpenAI.

LangChain 0.3: Installare i pacchetti

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

LangChain 0.3: Configurare l'ambiente

  • APPLICATION_INSIGHTS_CONNECTION_STRING: stringa di connessione di Application Insights per il tracciamento. Per trovare questo valore, aprire la risorsa di Application Insights nel portale di Azure, selezionare Panoramica e copiare il Connection String.
  • AZURE_OPENAI_ENDPOINT: URL dell'endpoint Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: nome dell'implementazione del modello di chat.
  • AZURE_OPENAI_VERSION: versione dell'API, ad esempio 2024-08-01-preview.
  • AZURE_OPENAI_API_KEY: chiave API OpenAI di Azure.

Nota

Questo esempio usa l'autenticazione della chiave API per semplicità. Per i carichi di lavoro di produzione, usare DefaultAzureCredential con get_bearer_token_provider come illustrato negli esempi LangChain v1 e LangGraph.

LangChain 0.3: Tracer e configurazione del modello

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

Collega callbacks=[azure_tracer] alle tue catene, strumenti o agenti per assicurarsi che le operazioni di LangChain 0.3 siano tracciate. Dopo aver eseguito la catena o l'agente, le tracce vengono visualizzate nella visualizzazione di osservabilità delle Tracce> nel portale Foundry entro 2-5 minuti.

Configurare il tracciamento per OpenAI Agents SDK

OpenAI Agents SDK supporta la strumentazione OpenTelemetry. Usare il frammento di codice seguente per configurare gli intervalli di traccia ed esportazione in Monitoraggio di Azure. Se APPLICATION_INSIGHTS_CONNECTION_STRING non è impostato, l'esportatore ripiega sulla console per il debug locale.

Prima di eseguire l'esempio, installare i pacchetti necessari:

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

Verificare le tracce nel portale di Foundry

  1. Accedere a Microsoft Foundry. Assicurarsi che l'interruttore New Foundry sia attivato. Questi passaggi fanno riferimento a Foundry (nuovo).These steps refer to Foundry (new).
  2. Verificare che il tracciamento sia connesso per il tuo progetto. Se necessario, seguire Impostare il tracciamento in Microsoft Foundry.
  3. Eseguire l'agente almeno una volta.
  4. Nel portale Foundry, vai a Osservabilità>Tracce.
  5. Verificare che venga visualizzata una nuova traccia con intervalli per le operazioni dell'agente.

Le tracce vengono in genere visualizzate entro 2-5 minuti dall'esecuzione dell'agente. Se le tracce non vengono ancora visualizzate dopo questa volta, vedere Risolvere i problemi comuni.

Risolvere i problemi comuni

Problema Causa Risoluzione
Non vengono visualizzate tracce in Foundry La traccia non è connessa, non è presente traffico recente o l'inserimento viene ritardato Confermare la connessione di Application Insights, generare nuovo traffico e aggiornare dopo 2-5 minuti.
Non vengono visualizzati intervalli LangChain o LangGraph I callback di tracciamento non sono collegati all'esecuzione Assicurarsi di passare la traccia in callbacks (ad esempio, config = {"callbacks": [azure_tracer]}) per l'esecuzione che si vuole tracciare.
Vengono visualizzati intervalli LangChain, ma mancano le chiamate agli strumenti Gli strumenti non sono associati al modello o il nodo dello strumento non è configurato Verificare che gli strumenti vengano passati al bind_tools() modello e che i nodi degli strumenti vengano aggiunti al grafico.
Le tracce vengono visualizzate ma sono intervalli incompleti o mancanti La registrazione del contenuto è disabilitata o alcune operazioni non sono instrumentate Abilitare enable_content_recording=True per i dati di telemetria completi. Per le operazioni personalizzate, aggiungere intervalli manuali usando OpenTelemetry SDK.
Vengono visualizzati errori di autorizzazione quando si eseguono query sui dati di telemetria Autorizzazioni di controllo degli accessi basato sul ruolo mancanti in Application Insights o Log Analytics Verificare l'accesso in Controllo di accesso (IAM) per le risorse connesse. Per le query di log, assegnare il ruolo Log Analytics Reader.
Il contenuto sensibile viene visualizzato nelle tracce La registrazione del contenuto è abilitata e le richieste, gli argomenti degli strumenti o i risultati includono dati sensibili. Disabilitare la registrazione del contenuto nell'ambiente di produzione e redigere i dati sensibili prima che entrino nella telemetria.

Passaggi successivi

  • Last updated on