Trasování a sledování agentů AI v Microsoft Foundry (Preview) (Classic)

Platí jenom pro:Portál Foundry (Classic). Tento článek není k dispozici pro nový portál Foundry. Přečtěte si další informace o novém portálu.

Poznámka:

Odkazy v tomto článku můžou otevírat obsah v nové dokumentaci Microsoft Foundry místo dokumentace Foundry (classic), kterou si právě prohlížíte.

Důležité

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji pro produkční úlohy. Některé funkce se nemusí podporovat nebo mohou mít omezené možnosti. Další informace najdete v tématu Supplementální podmínky použití pro Microsoft Azure Verze Preview.

V tomto článku se naučíte:

Seznamte se s klíčovými koncepty trasování.
Trasování a sledování agentů AI v Foundry
Prozkoumejte nové sémantické konvence s využitím pozorovatelnosti s více agenty.
Integrace s oblíbenými architekturami agentů
Prohlédněte si stopy v portálu Foundry a v Azure Monitoru.
Zobrazte vlákna agentů v prostředí pro agenty.

Určení důvodů provádění agenta je důležité pro řešení potíží a ladění. Pro složité agenty může být obtížné fungovat z mnoha důvodů.

Při generování odpovědi může být velký počet kroků, což znesnadňuje sledování všech těchto kroků.
Posloupnost kroků se může lišit v závislosti na vstupu uživatele.
Vstupy a výstupy v každé fázi můžou být dlouhé a zaslouží si podrobnější kontrolu.
Každý krok modulu runtime agenta může zahrnovat také vnoření. Agent může například vyvolat nástroj, který používá jiný proces, který pak vyvolá jiný nástroj. Pokud si všimnete podivného nebo nesprávného výstupu ze spuštění top-level agenta, může být obtížné přesně určit, kde během provádění došlo k problému.

Výsledky trasování tento problém řeší tím, že vám umožní zobrazit vstupy a výstupy jednotlivých primitiv zapojených do konkrétního spuštění agenta. Výsledky se zobrazí v pořadí, v jakém jsou vyvolány primitivy, což usnadňuje pochopení a ladění chování agenta AI.

Přehled trasovacích klíčových konceptů

Tady je stručný přehled klíčových konceptů před getting started:

Klíčové koncepty	Description
Trasování	Trasování zaznamenává průběh požadavku nebo pracovního postupu v aplikaci tím, že nahrává události a změny stavu, jako jsou volání funkcí, hodnoty a systémové události. Viz trasování OpenTelemetry.
Rozpětí	Jednotlivé úseky jsou základní prvky sledování, které představují jednotlivé operace v rámci sledování. Každý rozsah zachycuje počáteční a koncové časy a atributy a mohou být vložené, aby zobrazovaly hierarchické vztahy. Zobrazí se kompletní zásobník volání a posloupnost operací.
Attributes	Atributy jsou páry klíč-hodnota přiřazené k trasování a úsekům. Poskytují kontextová metadata, jako jsou parametry funkce, návratové hodnoty nebo vlastní poznámky. Tyto hodnoty vylepšují data trasování, což z nich dělá více informativních a užitečnějších pro analýzu.
Sémantické konvence	OpenTelemetry definuje sémantické konvence pro standardizaci názvů a formátů pro atributy dat trasování. Tyto konvence usnadňují interpretaci a analýzu dat napříč nástroji a platformami. Další informace najdete v tématu sémantické konvence OpenTelemetry.
Exportéři sledování	Exportéři trasování odesílají data trasování do back-endových systémů pro storage a analýzu. Azure AI podporuje export trasování do Azure Monitor a dalších platforem kompatibilních s OpenTelemetry, což umožňuje integraci s různými nástroji pozorovatelnosti.

Osvědčené postupy

Používejte konzistentní atributy spanu.
Spojte ID evaluace pro analýzu kvality a výkonu.
Redigovat citlivý obsah. Vyhněte se ukládání tajných kódů v atributech.

Rozšíření OpenTelemetry prostřednictvím pozorovatelnosti s více agenty

Microsoft vylepšuje pozorovatelnost více agentů tím, že zavádí nové sémantické konvence pro OpenTelemetry, vyvinuté společně s Outshift, inkubační platformou společnosti Cisco. Tyto doplňky založené na OpenTelemetry a kontextu trasování W3C vytvářejí standardizované postupy pro trasování a telemetrii v rámci systémů s více agenty. Usnadňují konzistentní protokolování klíčových metrik pro kvalitu, výkon, bezpečnost a náklady. Tento systematický přístup umožňuje komplexnější přehled o pracovních postupech s více agenty, včetně vyvolání nástrojů a spolupráce. Microsoft tyto pokroky integrují do Microsoft Foundry, Microsoft Agent Framework, Sémantické jádro a Azure balíčků AI pro LangChain, LangGraph a sadu OpenAI Agents SDK. Pomocí Foundry můžou zákazníci získat jednotnou pozorovatelnost pro systémy agentů vytvořené pomocí některé z těchto architektur. Přečtěte si další informace o integraci trasování.

Typ	Kontext nebo rodičovské rozpětí	Název/atribut/událost	Účel
Rozpětí	—	execute_task	Zaznamenává plánování úkolů a šíření událostí a poskytuje přehled o tom, jak se úkoly rozkládají a distribuují.
Dětské rozpětí	invoke_agent	interakce agentů	Trasuje komunikaci mezi agenty.
Dětské rozpětí	invoke_agent	agent.state.management	Efektivní kontext, krátkodobá nebo dlouhodobá správa paměti
Dětské rozpětí	invoke_agent	plánování agenta	Zaznamená interní kroky plánování agenta.
Dětské rozpětí	invoke_agent	Orchestrace agentů	Zachytává orchestraci mezi agenty.
Vlastnost	invoke_agent	definice_nástrojů	Popisuje účel nebo konfiguraci nástroje.
Vlastnost	invoke_agent	llm_spans	Zaznamenává rozsah volání modelu.
Vlastnost	spustit_nástroj	tool.call.arguments	Zaznamená argumenty předané během vyvolání nástroje.
Vlastnost	spustit_nástroj	nástroj.volání.výsledky	Zaznamenává výsledky vrácené nástrojem.
Událost	—	Vyhodnocení (název, error.type, štítek)	Umožňuje strukturované vyhodnocení výkonu a rozhodování agentů.

Nastavení trasování v sadě Microsoft Foundry SDK

Pro dokončování chatu nebo sestavování agentů s Foundry nainstalujte:

pip install azure-ai-projects azure-identity

Pro instrumentování trasování nainstalujte následující knihovny instrumentace:

pip install azure-monitor-opentelemetry opentelemetry-sdk

Pokud chcete zobrazit trasování v Foundry, připojte prostředek Application Insights k vašemu projektu Foundry.

V levém navigačním podokně portálu Foundry přejděte na Trasování .
Pokud ho ještě nemáte, vytvořte nový prostředek Application Insights.
Připojte prostředek k vašemu projektu Foundry.

Trasování instrumentace v kódu

Pokud chcete sledovat obsah chatových zpráv, nastavte AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED proměnnou prostředí na true (nerozlišují se malá a velká písmena). Tento obsah může obsahovat osobní údaje. Další informace najdete v klientské knihovně Azure Core Tracing OpenTelemetry pro Python.

import os
os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true" # False by default

Začněme instrumentací našeho agenta pomocí trasování OpenTelemetry tak, že nejprve ověříme a připojíme se k vašemu projektu Azure AI pomocí AIProjectClient.

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=os.environ["PROJECT_ENDPOINT"],
)

Dále načtěte připojovací řetězec z prostředku Application Insights připojeného k vašemu projektu a nastavte exportéry OTLP tak, aby odesílaly telemetrii do Azure Monitor.

from azure.monitor.opentelemetry import configure_azure_monitor

connection_string = project_client.telemetry.get_application_insights_connection_string()
configure_azure_monitor(connection_string=connection_string) #enable telemetry collection

Teď sledujte kód, kde vytváříte a spouštíte agenta a zprávu uživatele v Project Azure AI, abyste viděli podrobné kroky pro řešení potíží nebo monitorování.

from opentelemetry import trace
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.threads.create()
    message = project_client.agents.messages.create(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)

Po spuštění agenta můžete začít prohlížet stopy na portálu Foundry.

Trasování protokolů místně

Pokud se chcete připojit k řídicímu panelu Aspire nebo jinému back-endu kompatibilnímu s OpenTelemetry, nainstalujte vývozce OpenTelemetry Protocol (OTLP). Pomocí tohoto vývozce můžete zobrazit stopy v konzole nebo použít místní prohlížeč stop, jako je Aspire Dashboard.

pip install azure-core-tracing-opentelemetry opentelemetry-exporter-otlp opentelemetry-sdk

Dále nakonfigurujte trasování pro výstup konzoly:

from azure.core.settings import settings
settings.tracing_implementation = "opentelemetry"

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import SimpleSpanProcessor, ConsoleSpanExporter

# Setup tracing to console
span_exporter = ConsoleSpanExporter()
tracer_provider = TracerProvider()
tracer_provider.add_span_processor(SimpleSpanProcessor(span_exporter))
trace.set_tracer_provider(tracer_provider)

Nebo upravte předchozí kód na základě řídicího panelu Aspire tak, aby trasoval do místního prohlížeče OTLP.

Teď povolte instrumentaci agenta a spusťte agenta:

from azure.ai.agents.telemetry import AIAgentsInstrumentor
AIAgentsInstrumentor().instrument()

# Start tracing
tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("example-tracing"):
    agent = project_client.agents.create_agent(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        name="my-assistant",
        instructions="You are a helpful assistant"
    )
    thread = project_client.agents.threads.create()
    message = project_client.agents.messages.create(
        thread_id=thread.id, role="user", content="Tell me a joke"
    )
    run = project_client.agents.runs.create_and_process(thread_id=thread.id, agent_id=agent.id)

Alternativa: Sada nástrojů AI pro VS Code

Sada AI Toolkit poskytuje jednoduchý způsob, jak trasovat místně ve VS Code. Používá místní kolektor kompatibilní s OTLP, který je ideální pro vývoj a ladění.

Sada nástrojů podporuje architektury AI, jako je služba Foundry Agents Service, OpenAI, Anthropic a LangChain prostřednictvím OpenTelemetry. Trasování můžete okamžitě zobrazit ve VS Code bez nutnosti přístupu ke cloudu.

Podrobné pokyny k nastavení a příklady kódu specifické pro sadu SDK najdete v tématu Trasování v sadě nástrojů AI.

Sledování vlastních funkcí

Ke sledování vlastních funkcí použijte sadu OpenTelemetry SDK k instrumentaci kódu.

Nastavení poskytovatele trasování: Inicializace poskytovatele trasování pro správu a vytváření úseků
Vytvoření rozsahů: Zabalte kód, který chcete trasovat pomocí rozsahů. Každé rozpětí představuje jednotku práce a můžete vnořit rozsahy, které tvoří trasovací strom.
Přidejte atributy: Obohaťte rozsahy o atributy, které poskytují více kontextu pro trasovací data.
Konfigurace vývozce: Odeslání dat trasování do back-endu pro analýzu a vizualizaci

Tady je příklad trasování vlastní funkce:

from opentelemetry import trace
from opentelemetry.trace import SpanKind

# Initialize tracer
tracer = trace.get_tracer(__name__)

def custom_function():
    with tracer.start_as_current_span("custom_function") as span:
        span.set_attribute("custom_attribute", "value")
        # Your function logic here
        print("Executing custom function")

custom_function()

Podrobné pokyny a pokročilé použití najdete v dokumentaci k OpenTelemetry.

Připojte zpětnou vazbu uživatelů k stopám

Pokud chcete připojit zpětnou vazbu uživatelů k trasování a vizualizaci na portálu Foundry, instrumentujte aplikaci, abyste povolili trasování a protokolování zpětné vazby uživatelů pomocí sémantických konvencí OpenTelemetry.

S použitím ID odpovědi nebo ID vlákna můžete korelovat stopy zpětné vazby s příslušnými stopy žádostí chatu a zobrazit a spravovat je na portálu Foundry. Specifikace OpenTelemetry umožňuje standardizovaná a rozšířená data trasování, která můžete analyzovat na portálu Foundry za účelem optimalizace výkonu a přehledů uživatelského prostředí. Tento přístup vám pomůže využít plný výkon OpenTelemetry pro lepší pozorovatelnost ve vašich aplikacích.

Pokud chcete protokolovat názory uživatelů, postupujte podle tohoto formátu:

Událost vyhodnocení zpětné vazby uživatele se zaznamenává pouze v případě, že uživatel poskytne reakci na odpověď modelu GenAI. Pokud je to možné, přidružte tuto událost k rozsahu GenAI, který popisuje takovou odpověď.

Text události zpětné vazby uživatele má následující strukturu:

Základní pole	Typ	Description	Příklady	Úroveň požadavku
`comment`	řetězec	Další podrobnosti o zpětné vazbě uživatelů	`"I did not like it"`	`Opt-in`

Použití názvu služby v datech trasování

Pokud chcete službu identifikovat prostřednictvím jedinečného ID v Application Insights, použijte ve svých datech trasování vlastnost OpenTelemetry s názvem služby. Tato vlastnost je užitečná, pokud protokolujete data z více aplikací do stejného prostředku Application Insights a chcete mezi nimi rozlišovat.

Řekněme například, že máte dvě aplikace: App-1 a App-2 s trasováním nakonfigurovaným pro protokolování dat do stejného prostředku Application Insights. Možná byste chtěli nastavit , aby se aplikace App-1 vyhodnocovala nepřetržitě podle relevance a app-2 , aby se vyhodnocovala nepřetržitě podle relevance. Název služby můžete použít k filtrování Application při monitorování aplikace na portálu Foundry.

Pokud chcete nastavit vlastnost názvu služby, přidejte ji přímo do kódu vaší aplikace podle pokynů v části Použití více poskytovatelů trasování s různými prostředky. Můžete také nastavit proměnnou OTEL_SERVICE_NAME prostředí před nasazením aplikace. Další informace o práci s názvem služby najdete v tématu Proměnné prostředí OTEL a sémantické konvence prostředků služby.

Pokud chcete dotazovat data trasování pro daný název služby, zadejte dotaz na cloud_roleName vlastnost.

| where cloud_RoleName == "service_name"

Integrations

Foundry usnadňuje protokolování trasování s minimálními změnami pomocí integrace trasování s Microsoft Agent Framework, Sémantické jádro, LangChain, LangGraph a OpenAI Agent SDK.

Trasování agentů založených na Microsoft Agent Frameworku a Sémantické jádro

Foundry má nativní integrace s Microsoft Agent Framework a Sémantické jádro. Agenti, kteří jsou postaveni na těchto dvou architekturách, získají předem integrované trasování v pozorovatelnosti.

Přečtěte si další informace o trasování a pozorovatelnosti v Sémantické jádro a Microsoft Agent Framework.

Povolení trasování pro agenty postavené na LangChain a LangGraph

Poznámka:

Integrace trasování pro LangChain a LangGraph popsané tady je aktuálně dostupná jenom v Python.

Trasování pro LangChain, které se řídí standardy OpenTelemetry, můžete povolit podle opentelemetry-instrumentation-langchain.

Po instalaci potřebných balíčků můžete snadno instrument trasování v kódu.

Poznámka:

Verze LangChain a LangGraph v1 jsou v současné době aktivní ve vývoji. Rozhraní API jako takové a jeho trasování se může v rámci této verze změnit. Sledujte aktualizace na stránce Zpráva k vydání verze LangChain v1.0.

Ukázka: Agent LangChain v1 s trasováním Azure AI

Pomocí tohoto kompletního příkladu monitorujte agenta LangChain v1 pomocí nástroje langchain-azure-ai tracer. Implementuje nejnovější specifikace OpenTelemetry (OTel), abyste mohli zobrazit bohaté trasování v pozorovatelnosti.

Instalace balíčků

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

Konfigurace prostředí

APPLICATION_INSIGHTS_CONNECTION_STRING: Připojovací řetězec Azure Monitor Application Insights pro trasování.
AZURE_OPENAI_ENDPOINT: URL adresa koncového bodu Azure OpenAI.
AZURE_OPENAI_CHAT_DEPLOYMENT: Název nasazení chatovacího modelu.
AZURE_OPENAI_VERSION: Verze rozhraní API, například 2024-08-01-preview.
Azure přihlašovací údaje jsou vyřešeny prostřednictvím DefaultAzureCredential (podporuje proměnné prostředí, spravovanou identitu, přihlášení VS Code a další).

Tyto hodnoty můžete uložit do .env souboru pro místní vývoj.

Nastavení traceru

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]

Nastavení modelu (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,
)

Definování nástrojů a pobídek

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}!"

Použití kontextu modulu runtime a definování nástroje s informacemi o uživateli

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]

Vytvoření agenta

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

Spustit agenta s trasováním

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

Když povolíte langchain-azure-ai, všechny příslušné operace LangChain v1 (volání LLM, volání nástrojů, kroky agenta) se trasují pomocí nejnovějších sémantických konvencí OpenTelemetry. Zobrazují se v pozorovatelnosti propojené s vaším prostředkem Application Insights.

Ukázka: Agent LangGraph s trasováním Azure AI

Tato ukázka ukazuje jednoduchého agenta LangGraph instrumentovaného pomocí langchain-azure-ai pro emitování tras kompatibilních s OpenTelemetry pro kroky grafu, volání nástrojů a volání modelů.

Instalace balíčků

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

Konfigurace prostředí

APPLICATION_INSIGHTS_CONNECTION_STRING: Připojovací řetězec Azure Monitor Application Insights pro trasování.
AZURE_OPENAI_ENDPOINT: URL koncového bodu Azure OpenAI.
AZURE_OPENAI_CHAT_DEPLOYMENT: Název nasazení chatovacího modelu.
AZURE_OPENAI_VERSION: Verze rozhraní API, například 2024-08-01-preview.

Tyto hodnoty můžete uložit do .env souboru pro místní vývoj.

Nastavení traceru

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

Tools

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]

Nastavení modelu (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)

Sestavení pracovního postupu 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)

Spuštění s trasováním

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

Když povolíte langchain-azure-ai, spouštění jazyka LangGraph generuje rozsahy kompatibilní s OpenTelemetry pro volání modelu, vyvolání nástrojů a přechody grafů. Tyto stopy proudí do Application Insights a objeví se v pozorovatelnosti.

Ukázka: Nastavení LangChain 0.3 s trasováním Azure AI

Toto minimální nastavení ukazuje, jak povolit trasování Azure AI v aplikaci LangChain 0.3 pomocí langchain-azure-ai tracer a AzureChatOpenAI.

Instalace balíčků

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

Konfigurace prostředí

APPLICATION_INSIGHTS_CONNECTION_STRING: Připojovací řetězec Application Insights pro trasování.
AZURE_OPENAI_ENDPOINT: Azure OpenAI koncový bod URL.
AZURE_OPENAI_CHAT_DEPLOYMENT: Název nasazení chatovacího modelu
AZURE_OPENAI_VERSION: Verze rozhraní API, například 2024-08-01-preview.
AZURE_OPENAI_API_KEY: Azure klíč rozhraní API OpenAI.

Trasování a nastavení modelu

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

Připojte callbacks=[azure_tracer] ke svým řetězům, nástrojům nebo agentům, abyste zajistili, že operace LangChain 0.3 jsou sledovány a viditelné v monitoringu.

Povolte trasování pro agenty vytvořené na sadě OpenAI Agents SDK

Nainstalujte požadované balíčky:

pip install opentelemetry-sdk opentelemetry-instrumentation-openai-agents azure-monitor-opentelemetry-exporter

Tento fragment kódu použijte ke konfiguraci trasování OpenTelemetry pro sadu SDK pro agenty OpenAI a instrumentaci architektury. Exportuje se do Azure Monitor, pokud je nastavena APPLICATION_INSIGHTS_CONNECTION_STRING; jinak se vrátí zpět do konzoly.

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

Zobrazit trasování na portálu Foundry

Ve vašem projektu přejděte na Tracing a filtrovat stopy podle potřeby.

Výběrem záznamu můžete procházet každý úsek a identifikovat problémy a zároveň sledovat, jak vaše aplikace reaguje. Tento proces vám pomůže ladit a určit problémy v aplikaci.

Zobrazení stop v Azure Monitor

Pokud jste zaprotokolovali trasování pomocí předchozího fragmentu kódu, můžete nyní zobrazit své trasování v Azure Monitor Application Insights. Application Insights můžete otevřít ze Správa zdroje dat a pomocí zobrazení podrobností o celé transakci můžete dále prozkoumat.

Další informace o odesílání trasování Azure AI Inference do Azure Monitor a vytváření prostředků Azure Monitor najdete v dokumentaci k Azure Monitor OpenTelemetry.

Zobrazit výsledky vlákna na dětském hřišti Foundry Agents

Prostředí pro Agenty na portálu Foundry vám umožňuje zobrazit výsledky vláken a běhů, které vaši agenti vytvářejí. Pokud chcete zobrazit výsledky vlákna, vyberte protokoly vláken v aktivním vlákně. Volitelně můžete také vybrat metriky , které umožní automatické vyhodnocení výkonu modelu v několika dimenzích kvality AI a rizik a bezpečnosti.

Poznámka:

Jak je uvedeno v části Důvěryhodnost a Pozorovatelnost na stránce s cenami na stránce s cenami se účtuje vyhodnocení v dětském hřišti. Výsledky jsou k dispozici po dobu 24 hodin před vypršením platnosti. Pokud chcete získat výsledky vyhodnocení, vyberte požadované metriky a chatujte s vaším agentem.

Vyhodnocení nejsou k dispozici v následujících oblastech.
- australiaeast
- japaneast
- southindia
- uksouth

Po výběru protokolů vláken zkontrolujte:

Podrobnosti o vlákně
Informace o spuštění
Seřazené kroky spuštění a volání nástrojů
Vstupy a výstupy mezi uživatelem a agentem
Propojené metriky vyhodnocení (pokud jsou povolené)

Návod

Pokud chcete zobrazit výsledky vlákna z předchozího vlákna, vyberte Moje vlákna na obrazovce Agenti . Zvolte vlákno a pak vyberte Vyzkoušet v dětském hřišti. Zobrazí se tlačítko Protokoly vláken v horní části obrazovky a zobrazí se výsledky trasování.

Poznámka:

Funkce pozorovatelnosti, jako je hodnocení rizik a bezpečnosti, se účtují na základě spotřeby uvedené na stránce s cenami Azure.

Python samples obsahující plně spustitelný Python kód pro trasování pomocí synchronních a asynchronních klientů.
Ukázky kódu v Pythonu pro trasování agentů s použitím trasování v konzoli a Azure Monitor
Ukázky JavaScriptu obsahující plně spustitelný JavaScript kód pro trasování pomocí synchronních a asynchronních klientů.
C# Samples obsahující plně spustitelný kód jazyka C# pro odvozování pomocí synchronních a asynchronních metod.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-04-09

Trasování a sledování agentů AI v Microsoft Foundry (Preview) (Classic)

Přehled trasovacích klíčových konceptů

Osvědčené postupy

Rozšíření OpenTelemetry prostřednictvím pozorovatelnosti s více agenty

Nastavení trasování v sadě Microsoft Foundry SDK

Trasování instrumentace v kódu

Trasování protokolů místně

Alternativa: Sada nástrojů AI pro VS Code

Sledování vlastních funkcí

Připojte zpětnou vazbu uživatelů k stopám

Použití názvu služby v datech trasování

Integrations

Trasování agentů založených na Microsoft Agent Frameworku a Sémantické jádro

Povolení trasování pro agenty postavené na LangChain a LangGraph

Ukázka: Agent LangChain v1 s trasováním Azure AI

Instalace balíčků

Konfigurace prostředí

Nastavení traceru

Nastavení modelu (Azure OpenAI)

Definování nástrojů a pobídek

Použití kontextu modulu runtime a definování nástroje s informacemi o uživateli

Vytvoření agenta

Spustit agenta s trasováním

Ukázka: Agent LangGraph s trasováním Azure AI

Instalace balíčků

Konfigurace prostředí

Nastavení traceru

Tools

Nastavení modelu (Azure OpenAI)

Sestavení pracovního postupu LangGraph

Spuštění s trasováním

Ukázka: Nastavení LangChain 0.3 s trasováním Azure AI

Instalace balíčků

Konfigurace prostředí

Trasování a nastavení modelu

Povolte trasování pro agenty vytvořené na sadě OpenAI Agents SDK

Zobrazit trasování na portálu Foundry

Zobrazení stop v Azure Monitor

Zobrazit výsledky vlákna na dětském hřišti Foundry Agents

Související obsah

Váš názor

Další materiály