Condividi tramite

Configurare il monitoraggio per i framework di agenti AI (anteprima)

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente disponibili 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 presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.

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 offre integrazioni di traccia per i framework agente più diffusi che richiedono modifiche minime al codice. In questo articolo vengono illustrate le operazioni seguenti:

  • Configurare la traccia automatica per Microsoft Agent Framework e il kernel semantico
  • Configurare la langchain-azure-ai traccia per LangChain e LangGraph
  • Instrumentare OpenAI Agents SDK con OpenTelemetry
  • Verificare che le tracce appaiano nel portale Foundry
  • Risoluzione dei problemi comuni di tracciamento

Prerequisiti

  • Progetto Foundry con tracciamento connesso ad 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).
  • Se si usa LangChain o LangGraph, 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. Seleziona 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 lettore di Log Analytics.

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.

Annotazioni

I dati di traccia archiviati in Application Insights sono soggetti alle impostazioni di conservazione dei dati dell'area di lavoro e ai prezzi di 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 Prezzi di Monitoraggio di Azuree Configurare la conservazione e l'archivio dei dati.

Configurare il tracciamento per Microsoft Agent Framework e il Semantic Kernel.

Microsoft Foundry include integrazioni native con Microsoft Agent Framework e Semantic Kernel. 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 funzioni:

  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 di solito appaiono 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

Annotazioni

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

Usare questo esempio end-to-end per instrumentare un agente LangChain v1 (anteprima) usando il tracciante langchain-azure-ai. Questo tracer implementa le più recenti convenzioni semantiche OpenTelemetry (OTel), in modo da poter visualizzare tracce avanzate nella visualizzazione di osservabilità di 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 Azure Monitor Application Insights per il tracciamento.
  • AZURE_OPENAI_ENDPOINT: l'URL dell'endpoint OpenAI di Azure.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: nome del modello di distribuzione della chat.
  • AZURE_OPENAI_VERSION: versione dell'API, ad esempio 2024-08-01-preview.
  • L'SDK risolve le credenziali di 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://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: Definire gli strumenti 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 Osservabilità>Tracce nel portale Foundry e sono collegate alla risorsa di Application Insights.

Suggerimento

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

Verificare le tracce 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 .

Esempio: 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 Azure Monitor Application Insights per il tracciamento.
  • AZURE_OPENAI_ENDPOINT: l'URL dell'endpoint OpenAI di Azure.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: nome del modello di distribuzione della 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 del tracer 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: 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://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)

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 passano ad Application Insights e vengono visualizzate nella visualizzazione 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.

Verificare 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 il tracciamento di Azure AI

Questa configurazione minima illustra come abilitare la traccia di Azure AI in un'applicazione LangChain 0.3 usando la traccia 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 monitoraggio. Per trovare questo valore, aprire la risorsa di Application Insights nel portale di Azure, selezionare Panoramica e copiare la stringa di connessione.
  • AZURE_OPENAI_ENDPOINT: URL dell'endpoint OpenAI di Azure.
  • 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.

Annotazioni

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

Collegare 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 appaiono nella vista Osservabilità>Tracce nel portale Foundry entro 2-5 minuti.

Configurare il tracciamento per OpenAI Agents SDK

OpenAI Agents SDK supporta la strumentazione OpenTelemetry. Usare il seguente frammento di codice per configurare il tracciamento ed esportare le tracce ad Azure Monitor. Se APPLICATION_INSIGHTS_CONNECTION_STRING non è impostato, l'esportatore ricorre alla 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 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 collegato al tuo progetto. Se necessario, seguire Configurare la traccia 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 di solito appaiono 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 Motivo Risoluzione
Non ci sono tracce visibili 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 traccia non sono associati all'esecuzione Verificare di passare la traccia in callbacks (ad esempio, config = {"callbacks": [azure_tracer]}) per l'esecuzione da tracciare.
Vengono visualizzati intervalli LangChain, ma mancano le chiamate agli strumenti Gli strumenti non sono associati al nodo del 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 RBAC 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 lettore di Log Analytics.
Il contenuto sensibile compare nei log La registrazione del contenuto è abilitata e i prompt, gli argomenti degli strumenti o gli output includono dati sensibili Disattivare la registrazione del contenuto nell'ambiente di produzione e redigere i dati sensibili prima che entrino nella telemetria.

Passaggi successivi

  • Last updated on