Udostępnij przez

Konfigurowanie śledzenia dla platform agentów sztucznej inteligencji (wersja zapoznawcza)

Ważna

Elementy oznaczone jako (wersja zapoznawcza) w tym artykule są aktualnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Gdy agenci sztucznej inteligencji zachowują się nieoczekiwanie w środowisku produkcyjnym, śledzenie zapewnia widoczność, aby szybko zidentyfikować główną przyczynę. Śledzenie przechwytuje szczegółowe dane telemetryczne — w tym wywołania LLM, wywołania narzędzi i przepływy decyzyjne agenta — dzięki czemu można debugować problemy, monitorować opóźnienia i interpretować zachowanie agenta między żądaniami.

Rozwiązanie Microsoft Foundry udostępnia integracje śledzenia dla popularnych struktur agentów, które wymagają minimalnych zmian w kodzie. W tym artykule dowiesz się, jak:

  • Konfigurowanie automatycznego śledzenia dla programu Microsoft Agent Framework i jądra semantycznego
  • Skonfiguruj langchain-azure-ai śledzenie dla LangChain i LangGraph
  • Instrumentacja zestawu SDK agentów OpenAI przy użyciu platformy OpenTelemetry
  • Sprawdź, czy ślady są wyświetlane w portalu Foundry
  • Rozwiązywanie typowych problemów z śledzeniem

Wymagania wstępne

  • Projekt Foundry z śledzeniem połączonym z usługą Application Insights.
  • Współautor lub wyższa rola w zasobie usługi Application Insights do gromadzenia danych śledzenia.
  • Dostęp do połączonego zasobu usługi Application Insights w celu wyświetlania śladów. W przypadku zapytań opartych na dziennikach może być również potrzebny dostęp do skojarzonego obszaru roboczego usługi Log Analytics.
  • Środowisko Python w wersji 3.10 lub nowszej (wymagane dla wszystkich przykładów kodu w tym artykule).
  • Pakiet langchain-azure-ai w wersji 0.1.0 lub nowszej (wymagany dla przykładów LangChain i LangGraph).
  • Jeśli używasz bibliotek LangChain lub LangGraph, potrzebujesz środowiska Python z zainstalowanym pip.

Potwierdź, że możesz wyświetlić dane telemetryczne

Aby wyświetlić dane śledzenia, upewnij się, że twoje konto ma dostęp do połączonego zasobu usługi Application Insights.

  1. W witrynie Azure Portal otwórz zasób usługi Application Insights połączony z projektem Foundry.

  2. Wybierz pozycję Kontrola dostępu (IAM).

  3. Przypisz odpowiednią rolę do użytkownika lub grupy.

    Jeśli używasz zapytań opartych na dziennikach, zacznij od udzielenia roli Czytelnik Log Analytics.

Bezpieczeństwo i prywatność

Śledzenie może przechwytywać poufne informacje (na przykład dane wejściowe użytkownika, dane wyjściowe modelu i argumenty narzędzi i wyniki).

  • Włącz rejestrowanie zawartości podczas programowania i debugowania, aby wyświetlić pełne dane żądania i odpowiedzi. Wyłącz rejestrowanie zawartości w środowiskach produkcyjnych, aby chronić poufne dane. W przykładach w tym artykule rejestrowanie zawartości jest kontrolowane przez ustawienia takie jak enable_content_recording i OTEL_RECORD_CONTENT.
  • Nie przechowuj danych tajnych, poświadczeń ani tokenów w podpowiedziach lub argumentach narzędzi.

Aby uzyskać więcej wskazówek, zobacz Zabezpieczenia i prywatność.

Uwaga / Notatka

Dane śledzenia przechowywane w usłudze Application Insights podlegają ustawieniom przechowywania danych obszaru roboczego i cenom usługi Azure Monitor. W przypadku zarządzania kosztami rozważ dostosowanie częstotliwości próbkowania lub okresów przechowywania w środowisku produkcyjnym. Zobacz Cennik usługi Azure Monitor i Konfigurowanie przechowywania i archiwizowania danych.

Konfigurowanie śledzenia dla Microsoft Agent Framework i Semantic Kernel

Platforma Microsoft Foundry ma natywną integrację zarówno z programem Microsoft Agent Framework, jak i jądrem semantycznym. Agenci stworzeni za pomocą obu frameworków automatycznie emitują ślady po włączeniu śledzenia dla projektu Foundry — nie są wymagane żadne dodatkowe pakiety ani kod.

Aby sprawdzić, czy śledzenie działa:

  1. Uruchom swojego agenta przynajmniej raz.
  2. W portalu Foundry przejdź do Monitorowanie>Śladów.
  3. Upewnij się, że zostanie wyświetlony nowy ślad z zakresami dla operacji agenta.

Ślady zwykle pojawiają się w ciągu 2–5 minut po uruchomieniu agenta. Aby uzyskać zaawansowaną konfigurację, zobacz dokumentację specyficzną dla platformy:

Konfigurowanie śledzenia dla bibliotek LangChain i LangGraph

Uwaga / Notatka

Integracja śledzenia dla LangChain i LangGraph jest obecnie dostępna tylko w języku Pythonie.

Użyj pakietu langchain-azure-ai, aby emitować ślady zgodne ze standardem OpenTelemetry dla operacji LangChain i LangGraph. Te Ślady pojawiają się w widoku > w portalu Foundry.

Przykład: LangChain v1 agent ze śledzeniem AI na platformie Azure

Użyj tego pełnego przykładu, aby zaimplementować agenta LangChain v1 (wersja zapoznawcza) przy użyciu tracer langchain-azure-ai. Ten śledzik implementuje najnowsze konwencje semantyczne protokołu OpenTelemetry (OTel), dzięki czemu można wyświetlać zaawansowane ślady w widoku obserwowalności Foundry.

LangChain v1: Instalowanie pakietów

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

LangChain v1: Konfigurowanie środowiska

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Parametry połączenia usługi Azure Monitor Application Insights do śledzenia.
  • AZURE_OPENAI_ENDPOINT: Adres URL punktu końcowego usługi Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: nazwa wdrożenia modelu czatu.
  • AZURE_OPENAI_VERSION: wersja interfejsu API, na przykład 2024-08-01-preview.
  • Zestaw SDK rozpoznaje poświadczenia platformy Azure przy użyciu programu DefaultAzureCredential, który obsługuje zmienne środowiskowe, tożsamość zarządzaną i logowanie programu VS Code.

Zapisz te wartości w pliku na potrzeby programowania lokalnego .env .

LangChain v1: Konfiguracja narzędzia Tracer

from dotenv import load_dotenv
import os
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

load_dotenv(override=True)

azure_tracer = AzureAIOpenTelemetryTracer(
    connection_string=os.environ.get("APPLICATION_INSIGHTS_CONNECTION_STRING"),
    enable_content_recording=True,
    name="Weather information agent",
    id="weather_info_agent_771929",
)

tracers = [azure_tracer]

LangChain v1: Konfiguracja 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://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: Definiowanie narzędzi i monitów

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: Użyj kontekstu środowiska uruchomieniowego i zdefiniuj narzędzie 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: tworzenie 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: Uruchom agenta ze śledzeniem

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

Po włączeniu langchain-azure-ai wszystkie operacje LangChain v1 (wywołania LLM, wywołania narzędzi, kroki agenta) emitują spany OpenTelemetry, wykorzystując najnowsze konwencje semantyczne. Te ślady są wyświetlane w widoku Obserwowalność>Ślady w portalu Foundry i są połączone z zasobem usługi Application Insights.

Wskazówka

Po uruchomieniu agenta poczekaj kilka minut na wyświetlenie śladów. Jeśli nie widzisz śladów, sprawdź, czy parametry połączenia usługi Application Insights są poprawne i sprawdź sekcję Rozwiązywanie typowych problemów .

Zweryfikuj swoje ślady LangChain v1

Po uruchomieniu agenta:

  1. Poczekaj 2–5 minut na propagację śladów.
  2. W portalu Foundry przejdź do Monitorowanie>Śladów.
  3. Wyszukaj ślad z określoną nazwą (na przykład "Agent informacji o pogodzie").
  4. Rozwiń ślad, aby wyświetlić zakresy wywołań LLM, wywołań narzędzi i kroków agenta.

Jeśli nie widzisz śladów, zapoznaj się z sekcją Rozwiązywanie typowych problemów .

Przykład: Agent LangGraph ze śledzeniem AI w ramach Azure

W tym przykładzie pokazano prostego agenta LangGraph wyposażonego w langchain-azure-ai, który emituje ślady zgodne ze standardem OpenTelemetry dla działań w krokach grafu, wywołań narzędzi oraz modelu.

LangGraph: Instalowanie pakietów

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

LangGraph: Konfigurowanie środowiska

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Parametry połączenia usługi Azure Monitor Application Insights do śledzenia.
  • AZURE_OPENAI_ENDPOINT: Adres URL punktu końcowego usługi Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: nazwa wdrożenia modelu czatu.
  • AZURE_OPENAI_VERSION: wersja interfejsu API, na przykład 2024-08-01-preview.

Zapisz te wartości w pliku na potrzeby programowania lokalnego .env .

Konfiguracja śledzenia 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: Narzędzia

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

Budowanie przepływu pracy 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: Uruchamianie z śledzeniem

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

Po włączeniu langchain-azure-ai, LangGraph emituje zakresy zgodne ze standardem OpenTelemetry dla wywołań modelu, wywołań narzędzi oraz przejść grafu. Te ślady przepływają do usługi Application Insights i są wyświetlane w widokuŚlady obserwacji> w portalu Foundry.

Wskazówka

Każdy węzeł grafu i przejście brzegowe tworzy oddzielny zakres, co ułatwia wizualizowanie przepływu decyzyjnego agenta.

Zweryfikuj swoje ślady LangGraph

Po uruchomieniu agenta:

  1. Poczekaj 2–5 minut na propagację śladów.
  2. W portalu Foundry przejdź do Monitorowanie>Śladów.
  3. Poszukaj śladu o określonej nazwie (na przykład "Agent odtwarzacza muzyki").
  4. Rozwiń ścieżkę, aby wyświetlić zakresy dla węzłów grafu, wywołań narzędzi i wywołań modelu.

Jeśli nie widzisz śladów, zapoznaj się z sekcją Rozwiązywanie typowych problemów .

Przykład: konfigurowanie aplikacji LangChain 0.3 za pomocą śledzenia sztucznej inteligencji platformy Azure

Ta konfiguracja minimalna pokazuje, jak włączyć śledzenie Azure AI w aplikacji LangChain 0.3 przy użyciu langchain-azure-ai tracera i AzureChatOpenAI.

LangChain 0.3: Instalowanie pakietów

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

LangChain 0.3: Konfigurowanie środowiska

  • APPLICATION_INSIGHTS_CONNECTION_STRING: Parametry połączenia usługi Application Insights do śledzenia. Aby znaleźć tę wartość, otwórz zasób usługi Application Insights w witrynie Azure Portal, wybierz pozycję Przegląd i skopiuj parametry połączenia.
  • AZURE_OPENAI_ENDPOINT: Adres URL punktu końcowego usługi Azure OpenAI.
  • AZURE_OPENAI_CHAT_DEPLOYMENT: Nazwa wdrożenia modelu czatu.
  • AZURE_OPENAI_VERSION: wersja interfejsu API, na przykład 2024-08-01-preview.
  • AZURE_OPENAI_API_KEY: Klucz interfejsu API usługi Azure OpenAI.

Uwaga / Notatka

W tym przykładzie użyto uwierzytelniania klucza API dla uproszczenia. W przypadku obciążeń produkcyjnych należy używać DefaultAzureCredential i get_bearer_token_provider, jak pokazano w przykładach LangChain v1 i LangGraph.

LangChain 0.3: Tracer i konfiguracja 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,
)

Dołącz callbacks=[azure_tracer] do swoich łańcuchów, narzędzi lub agentów, aby zapewnić śledzenie operacji w LangChain 0.3. Po uruchomieniu łańcucha lub agenta, ślady pojawiają się w widoku Obserwowalność>Ślady w portalu Foundry w ciągu 2–5 minut.

Konfigurowanie trace’owania dla pakietu SDK agentów OpenAI

Zestaw SDK agentów OpenAI obsługuje instrumentację OpenTelemetry. Użyj poniższego fragmentu kodu, aby skonfigurować zakresy śledzenia i eksportu do usługi Azure Monitor. Jeśli APPLICATION_INSIGHTS_CONNECTION_STRING nie zostanie ustawiona, eksporter wróci do konsoli na potrzeby lokalnego debugowania.

Przed uruchomieniem przykładu zainstaluj wymagane pakiety:

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

Weryfikowanie śladów w portalu Foundry

  1. Zaloguj się do usługi Microsoft Foundry. Upewnij się, że przełącznik New Foundry jest włączony. Te kroki dotyczą rozwiązania Foundry (nowy).
  2. Upewnij się, że śledzenie jest włączone dla twojego projektu. W razie potrzeby wykonaj czynności opisane w temacie Konfigurowanie śledzenia w rozwiązaniu Microsoft Foundry.
  3. Uruchom swojego agenta przynajmniej raz.
  4. W portalu Foundry przejdź do Monitorowanie>Śladów.
  5. Upewnij się, że zostanie wyświetlony nowy ślad z zakresami dla operacji agenta.

Ślady zwykle pojawiają się w ciągu 2–5 minut po uruchomieniu agenta. Jeśli ślady nadal nie są wyświetlane po tym czasie, zobacz Rozwiązywanie typowych problemów.

Rozwiązywanie typowych problemów

Problematyka Przyczyna Rezolucja
Nie widać śladów w Foundry Śledzenie nie jest połączone, nie ma ostatniego ruchu lub pozyskiwanie jest opóźnione Potwierdź połączenie usługi Application Insights, wygeneruj nowy ruch i odśwież po 2–5 minutach.
Nie widzisz rozpiętości LangChain ani LangGraph Wywołania zwrotne śledzenia nie są dołączone do przebiegu Upewnij się, że przekazujesz element tracer w pliku callbacks (na przykład ) dla przebiegu, config = {"callbacks": [azure_tracer]}który chcesz śledzić.
Zakresy langchain są wyświetlane, ale brakuje wywołań narzędzi Narzędzia nie są powiązane z modelem lub węzeł narzędzia nie jest skonfigurowany Sprawdź, czy narzędzia są przekazywane do bind_tools() w modelu oraz czy węzły narzędzi są dodawane do grafu.
Ślady są wyświetlane, ale są niekompletne lub brakują fragmenty. Nagrywanie zawartości jest wyłączone lub niektóre operacje nie są instrumentowane Włącz enable_content_recording=True dla pełnej telemetrii. W przypadku operacji niestandardowych dodaj zakresy ręczne przy użyciu zestawu narzędziowego OpenTelemetry SDK.
Podczas wykonywania zapytań dotyczących telemetrii są wyświetlane błędy autoryzacji Brak uprawnień RBAC w usłudze Application Insights lub Log Analytics Potwierdź dostęp do połączonych zasobów w Kontroli dostępu (IAM). W przypadku zapytań dziennika przypisz rolę Czytelnik usługi Log Analytics.
Zawartość wrażliwa pojawia się w śladowych ilościach Rejestrowanie zawartości jest włączone, a monity, argumenty narzędzi lub dane wyjściowe obejmują dane poufne Wyłącz rejestrowanie zawartości w środowisku produkcyjnym i zredaguj poufne dane, zanim wejdą do telemetrii.

Dalsze kroki

  • Last updated on