Sdílet prostřednictvím

Konfigurace trasování pro architektury agentů AI (Preview)

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

Poznámka:

Trasování je obecně dostupné pouze pro promptní agenty. Pracovní postup, hostovaný a vlastní agenti jsou ve verzi Preview.

Když se agenti umělé inteligence chovají neočekávaně v produkčním prostředí, trasování vám poskytne přehled o rychlé identifikaci původní příčiny. Trasování zachycuje podrobnou telemetrii, včetně volání LLM, vyvolání nástrojů a rozhodovacích procesů agentů, což umožňuje ladit problémy, sledovat latenci a rozumět chování agenta napříč žádostmi.

Microsoft Foundry poskytuje integrace trasování pro oblíbené architektury agentů, které vyžadují minimální změny kódu. V tomto článku se naučíte:

  • Konfigurace automatického trasování pro rozhraní Microsoft Agent Framework
  • Nastavte sledovací proces langchain-azure-ai pro LangChain a LangGraph
  • Instrumentujte sadu OpenAI Agents SDK s využitím OpenTelemetry.
  • Ověřte, že se stopy zobrazují na portálu Foundry
  • Řešení běžných problémů s trasováním

Předpoklady

  • Projekt Foundry se sledováním připojeným ke službě Azure Monitor Application Insights.
  • Role přispěvatele nebo vyšší role prostředku Application Insights pro příjem trasování
  • Přístup k připojenému prostředku Application Insights ke sledování záznamů. U dotazů založených na protokolech můžete také potřebovat access do přidruženého pracovního prostoru služby Log Analytics.
  • Python 3.10 nebo novější (vyžaduje se pro všechny ukázky kódu v tomto článku).
  • Balíček langchain-azure-ai verze 0.1.0 nebo novější (vyžaduje se pro ukázky LangChain a LangGraph).
  • Pokud používáte LangChain nebo LangGraph, prostředí Pythonu s nainstalovaným pipem.

Potvrzení, že můžete zobrazit telemetrii

Pokud chcete zobrazit data trasování, ujistěte se, že váš účet má access k připojenému prostředku Application Insights.

  1. V portálu Azure otevřete prostředek Application Insights připojený k vašemu projektu Foundry.

  2. Vyberte Access control (IAM).

  3. Přiřaďte uživateli nebo skupině odpovídající roli.

    Pokud používáte dotazy založené na protokolu, začněte tím, že udělíte roli čtenáře Log Analytics.

Zabezpečení a ochrana osobních údajů

Trasování může zaznamenávat citlivé informace (například vstupy uživatelů, výstupy modelu a argumenty a výsledky nástrojů).

  • Povolte nahrávání obsahu během vývoje a ladění, abyste viděli úplná data požadavků a odpovědí. Zakažte záznam obsahu v produkčních prostředích a chraňte citlivá data. V ukázkách v tomto článku se záznam obsahu řídí nastavením, jako je enable_content_recording a OTEL_RECORD_CONTENT.
  • Neukládejte tajné kódy, přihlašovací údaje ani tokeny do výzev nebo argumentů nástroje.

Další pokyny najdete v tématu Zabezpečení a ochrana osobních údajů.

Poznámka:

Trasování dat uložených v Application Insights podléhá nastavení uchovávání dat vašeho pracovního prostoru a cenám Azure Monitor. V případě správy nákladů zvažte úpravu vzorkovacích sazeb nebo období uchovávání v produkčním prostředí. Viz Ceny Azure Monitor a Nastavení uchovávání dat a archivace.

Konfigurace trasování pro rozhraní Microsoft Agent Framework

Microsoft Foundry má nativní integrace s rozhraním Microsoft Agent Framework. Agenti postavení s kterýmkoliv rámcem automaticky generují trasování, když je pro váš projekt Foundry povolené trasování – nevyžaduje se žádný další kód ani balíčky.

Ověření, že trasování funguje:

  1. Spusťte agenta alespoň jednou.
  2. Na portálu Foundry přejděte do Pozorovatelnost>.Trasy.
  3. Ověřte, že se zobrazí nové trasování s rozsahy operací vašeho agenta.

Stopy se obvykle zobrazují za 2–5 minut po spuštění agenta. Pokročilou konfiguraci najdete v dokumentaci specifické pro danou architekturu:

Konfigurace trasování pro LangChain a LangGraph

Poznámka:

Integrace trasování pro LangChain a LangGraph je aktuálně dostupná jenom v Pythonu.

Pomocí balíčku langchain-azure-ai vygenerujte rozsahy kompatibilní s OpenTelemetry pro operace LangChain a LangGraph. Tyto stopy jsou zobrazeny v zobrazení Trasy>stop v portálu Foundry.

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

Pomocí této ucelené ukázky instrumentujte agenta LangChain v1 (Preview) pomocí trasování langchain-azure-ai. Tento nástroj pro sledování implementuje nejnovější sémantické konvence OpenTelemetry (OTel), takže můžete prohlížet podrobné trasování v zobrazení sledovatelnosti Foundry.

LangChain v1: Instalace balíčků

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

LangChain v1: Konfigurace prostředí

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Připojovací řetězec Azure Monitor Application Insights pro trasování.
  • AZURE_OPENAI_ENDPOINT: Adresa 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.
  • SDK řeší přihlašovací údaje Azure pomocí DefaultAzureCredential, který podporuje proměnné prostředí, spravovanou identitu a přihlášení pomocí VS Code.

Tyto hodnoty uložte do .env souboru pro místní vývoj.

LangChain v1: 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]

LangChain v1: 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,
)

LangChain v1: Definování nástrojů a výzvy

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: Použití kontextu modulu runtime a definování nástroje pro informace 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]

LangChain v1: 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,
)

LangChain v1: Spuštění 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()

S langchain-azure-ai povoleným všechny operace LangChain v1 (volání LLM, vyvolání nástrojů, kroky agenta) emitují OpenTelemetry stopy podle nejnovějších sémantických konvencí. Tyto stopy se objeví v zobrazení pozorovatelnost>Stopy na portálu Foundry a jsou spojeny se službou Application Insights.

Návod

Po spuštění agenta počkejte několik minut, než se zobrazí sledy. Pokud trasování nevidíte, ověřte, zda je správný připojovací řetězec Application Insights a zkontrolujte část Řešení běžných problémů.

Ověřte své stopy LangChain v1

Po spuštění agenta:

  1. Počkejte 2 až 5 minut, než se stopy rozšíří.
  2. Na portálu Foundry přejděte do Pozorovatelnost>.Trasy.
  3. Vyhledejte stopu se zadaným názvem (například "Agent informací o počasí").
  4. Rozbalte trasování a zobrazte úseky pro volání LLM, použití nástrojů a kroky agenta.

Pokud nevidíte stopy, zkontrolujte část Řešení běžných problémů.

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

LangGraph: Instalace balíčků

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

LangGraph: Konfigurace prostředí

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Připojovací řetězec Azure Monitor Application Insights pro trasování.
  • AZURE_OPENAI_ENDPOINT: Adresa 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 uložte do .env souboru pro místní vývoj.

Konfigurace trasování 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: Nástroje

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

LangGraph: 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ž je povolené 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 trasování proudí do Application Insights a zobrazí se v zobrazenípozorovatelnosti> na portálu Foundry.

Návod

Každý uzel grafu a hraniční přechod vytvoří samostatné rozpětí, což usnadňuje vizualizaci rozhodovacího toku agenta.

Ověřte své stopy LangGraph

Po spuštění agenta:

  1. Počkejte 2 až 5 minut, než se stopy rozšíří.
  2. Na portálu Foundry přejděte do Pozorovatelnost>.Trasy.
  3. Vyhledejte stopy se zadaným názvem (například "Agent hudebního přehrávače").
  4. Rozbalením trasování zobrazíte rozsahy pro uzly grafu, volání nástrojů a volání modelu.

Pokud nevidíte stopy, zkontrolujte část Řešení běžných problémů.

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

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

LangChain 0.3: Instalace balíčků

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

LangChain 0.3: Konfigurace prostředí

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Application Insights connection string pro trasování. Pokud chcete tuto hodnotu najít, otevřete prostředek Application Insights v Azure portal, vyberte Overview a zkopírujte Connection String.
  • 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.
  • AZURE_OPENAI_API_KEY: Klíč rozhraní API Azure OpenAI.

Poznámka:

V této ukázce se kvůli jednoduchosti používá ověřování pomocí klíče rozhraní API. V případě produkčních úloh použijte DefaultAzureCredential spolu s get_bearer_token_provider, jak je znázorněno v ukázkách LangChain v1 a LangGraph.

LangChain 0.3: Tracer 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] k vašim řetězům, nástrojům nebo agentům, aby byly operace LangChain 0.3 sledovány. Po spuštění svého řetězu nebo agenta se trasování zobrazí ve zobrazení pozorovatelnosti na portálu Foundry během 2 až 5 minut.

Konfigurace trasování pro OpenAI Agents SDK

Sada OpenAI Agents SDK podporuje instrumentaci OpenTelemetry. Pomocí následujícího fragmentu kódu nakonfigurujte rozsahy trasování a exportu do Azure Monitoru. Pokud APPLICATION_INSIGHTS_CONNECTION_STRING není nastavený, exportér se vrátí do konzoly pro místní ladění.

Před spuštěním ukázky nainstalujte požadované balíčky:

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

Ověřit stopy na portálu Foundry

  1. Přihlaste se k Microsoft Foundry. Ujistěte se, že je zapnutý přepínač New Foundry . Tyto kroky se týkají nové verze aplikace Foundry.
  2. Ověřte, že je trasování připojeno k vašemu projektu. V případě potřeby postupujte podle pokynů k nastavení trasování v Microsoft Foundry.
  3. Spusťte agenta alespoň jednou.
  4. Na portálu Foundry přejděte do Pozorovatelnost>.Trasy.
  5. Ověřte, že se zobrazí nové trasování s rozsahy operací vašeho agenta.

Stopy se obvykle zobrazují za 2–5 minut po spuštění agenta. Pokud se stopy stále nezobrazují ani po této době, přečtěte si téma Řešení běžných problémů.

Řešení běžných potíží

Problém Příčina Řešení
V Foundry nevidíte stopy Trasování není spojeno, nedochází k žádnému nedávnému provozu, nebo je zpožděn příjem dat. Potvrďte připojení Application Insights, vygenerujte nový provoz a aktualizujte se po 2 až 5 minutách.
Nezobrazují se úseky LangChain ani LangGraph. Trasovací zpětná volání nejsou připojená k běhu programu. Ověřte, že pro spuštění, které chcete trasovat, předáte trasovač v callbacks (například config = {"callbacks": [azure_tracer]}).
LangChain úseky se zobrazí, ale chybí volání funkcí nástrojů Nástroje nejsou svázané s modelem nebo uzlem nástrojů nejsou nakonfigurované. Ověřte, že nástroje jsou předány do bind_tools() na model a že uzly nástrojů jsou přidány do vašeho grafu.
Zobrazují se stopy, ale nejsou úplné nebo chybí úseky. Záznam obsahu je zakázaný nebo některé operace nejsou instrumentované. Povolte enable_content_recording=True úplnou telemetrii. Pro vlastní operace přidejte ruční rozsahy pomocí sady OpenTelemetry SDK.
Při dotazování telemetrie se zobrazují chyby autorizace. Chybějící oprávnění RBAC ve službě Application Insights nebo Log Analytics Potvrďte přístup v Řízení přístupu (IAM) pro připojené prostředky. U dotazů protokolu přiřaďte roli čtenáře Log Analytics.
Citlivý obsah se objevuje v protokolech. Nahrávání obsahu je povolené a výzvy, argumenty nástrojů nebo výstupy obsahují citlivá data. Zakázat zaznamenávání obsahu v produkčním prostředí a upravit citlivá data předtím, než vstoupí do telemetrie.

Další kroky

  • Last updated on