Overzicht van agenttracering

Belangrijk

Items die in dit artikel zijn gemarkeerd (preview) zijn momenteel beschikbaar als openbare preview. Deze preview wordt aangeboden zonder een service level agreement en we raden deze niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure previews voor meer informatie.

Opmerking

Tracering is algemeen beschikbaar voor prompts en gehoste agenten. Workflow en externe agents zijn als preview beschikbaar.

Microsoft Foundry biedt een waarneembaarheidsplatform voor het bewaken en traceren van AI-agents. Tijdens een agentuitvoering worden belangrijke gegevens vastgelegd, zoals invoer, uitvoer, hulpprogrammagebruik, nieuwe pogingen, latenties en kosten. Inzicht in de redenering achter de uitvoeringen van uw agent is belangrijk voor probleemoplossing en foutopsporing. Het begrijpen van complexe agents brengt echter om verschillende redenen uitdagingen met zich mee:

  • Er kan een groot aantal stappen zijn betrokken bij het genereren van een antwoord, waardoor het moeilijk is om ze allemaal bij te houden.
  • De reeks stappen kan variëren op basis van gebruikersinvoer.
  • De invoer en uitvoer in elke fase kunnen lang zijn en meer gedetailleerde inspectie verdienen.
  • Elke stap van de runtime van een agent kan ook betrekking hebben op nesten. Een agent kan bijvoorbeeld een hulpprogramma aanroepen dat gebruikmaakt van een ander proces, dat vervolgens een ander hulpprogramma aanroept. Als u merkt dat de uitvoer van een top-level agent vreemd of onjuist is, kan het lastig zijn om precies te bepalen waar het probleem in de uitvoering is geïntroduceerd.

Traceringen pakken deze uitdagingen aan door u in staat te stellen de invoer en uitvoer van elke primitieve die betrokken is bij een bepaalde agentuitvoering weer te geven, weergegeven in de volgorde waarin ze zijn aangeroepen, zodat u eenvoudig het gedrag van uw AI-agent kunt begrijpen en er fouten in kunt opsporen.

Voorwaarden

Als u het traceren van end-to-end wilt gebruiken, hebt u het volgende nodig:

Opmerking

Met tracering worden telemetriegegevens opgeslagen in Azure Monitor Application Insights. Dit kan kosten in rekening worden gebracht op basis van gegevensvolume en bewaarinstellingen. Zie Application Insights-prijzen voor meer informatie over prijzen.

OpenTelemetry in Foundry

OpenTelemetry (OTel) biedt gestandaardiseerde protocollen voor het verzamelen en routeren van telemetriegegevens. Foundry maakt gebruik van semantische OpenTelemetry-conventies, zodat traceringen consistent zijn in ondersteunde hulpprogramma's en integraties.

Belangrijke concepten traceren

De volgende belangrijke concepten zijn in dit artikel van toepassing:

Sleutelbegrippen Beschrijving
Sporen Traceringen leggen het traject van een aanvraag of werkstroom vast via uw toepassing door gebeurtenissen en statuswijzigingen (functie-aanroepen, waarden, systeemevenementen) vast te leggen. Zie OpenTelemetry Traces.
Overspanningen Spans zijn de bouwstenen van traceringen, die één bewerking binnen een tracering vertegenwoordigen. Elke periode legt begin- en eindtijden, kenmerken vast en kan worden genest om hiërarchische relaties weer te geven, zodat u de volledige aanroepstack en de volgorde van bewerkingen kunt zien.
Kenmerken Kenmerken zijn sleutel-waardeparen die aan traces en spans zijn gekoppeld, en bevatten contextuele metagegevens zoals functieparameters, retourwaarden of aangepaste aantekeningen. Deze verrijken traceringsgegevens, waardoor deze informatiever en nuttiger zijn voor analyse.
Semantische conventies OpenTelemetry definieert semantische conventies voor het standaardiseren van namen en indelingen voor traceringsgegevenskenmerken, waardoor het gemakkelijker is om hulpprogramma's en platforms te interpreteren en analyseren. Zie de semantische conventies van OpenTelemetry GenAI voor meer informatie.
Exporteurs traceren Traceerexporteurs verzenden traceringsgegevens naar back-endsystemen voor opslag en analyse. In Foundry worden traceringen opgeslagen in Azure Monitor Application Insights. Ga naar tracering instellen in Microsoft Foundry om te leren hoe u traceringen kunt inschakelen en bekijken.

Hoe tracering werkt in Foundry

Met tracering kunt u vragen beantwoorden zoals 'Waar is dit antwoord vandaan gekomen?' en 'Welke stap heeft een fout- of latentiepiek geïntroduceerd?'

Op hoog niveau legt tracering het volgende vast:

  • Gebruikersinvoer en agentuitvoer.
  • Hulpprogrammagebruik, inclusief hulpprogramma-aanroepen en resultaten.
  • Tokenverbruik.
  • Tijdsignalen zoals duur en latentie.

Wanneer u tracering voor uw project inschakelt, kunt u traceringen controleren in de Foundry-portal en in Azure Monitor Application Insights. Zie Opvolging instellen in Microsoft Foundry voor stapsgewijze installatie- en weergaveopties.

OpenTelemetry uitbreiden met waarneembaarheid met meerdere agents

Microsoft draagt in samenwerking met Cisco Outshift semantische conventies voor systemen met meerdere agents bij. Deze conventies bouwen voort op OpenTelemetry GenAI-agent- en frameworkspans en W3C Trace Context. Ze standaardiseren telemetrie voor werkstromen met meerdere agents, waaronder agentoproepen, werkstroomindeling, planning, modeloproepen en uitvoering van hulpprogramma's.

Belangrijk

De semantische conventies van OpenTelemetry GenAI hebben de status Ontwikkeling en kunnen in toekomstige releases veranderen.

Deze verbeteringen zijn geïntegreerd in:

  • Gieterij
  • Microsoft Agent Framework
  • LangChain
  • LangGraph
  • OpenAI Agents SDK

Zie traceringsintegraties voor meer informatie.

In de volgende tabel worden algemene OpenTelemetry GenAI-conventies beschreven voor waarneembaarheid met meerdere agents. Spans registreren bewerkingen, onderliggende spans tonen geneste werkzaamheden en attributen leveren metadata. De weergegeven bovenliggende spanten zijn veelvoorkomende voorbeelden; daadwerkelijke nesting is afhankelijk van de geïnstrueerde agent of het framework.

Type Context/bovenliggende spanwijdte Naam/kenmerk/gebeurtenis Purpose
Span — invoke_agent Roept een agent aan via een externe service of binnen hetzelfde proces.
Onderliggend bereik invoke_agent invoke_agent Volgt een aanroep van een andere agent via een ouder-kindrelatie tussen spans.
Onderliggend bereik invoke_agent plan Registreert een planningsfase van een agent of een fase voor taakopsplitsing.
Span — invoke_workflow Roept een gecoördineerde werkstroom aan die agents of andere generatieve AI-bewerkingen bevat.
Onderliggend bereik invoke_agent of invoke_workflow execute_tool Registreert de uitvoering van een hulpprogramma.
Onderliggend bereik invoke_agent of invoke_workflow create_memory, search_memory, update_memory, upsert_memory of delete_memory Registreert een geheugenbewerking.
Kenmerk invoke_agent gen_ai.tool.definitions Registreert definities van hulpprogramma's die beschikbaar zijn voor een agent of model.
Kenmerk execute_tool gen_ai.tool.call.arguments Registreert de argumenten die zijn doorgegeven aan een aanroep van een hulpprogramma.
Kenmerk execute_tool gen_ai.tool.call.result Registreert het resultaat dat wordt geretourneerd door een geslaagde aanroep van het hulpprogramma.

Beste praktijken

  • Gebruik consistente spankenmerken: Gebruik dezelfde kenmerknamen en -indelingen voor alle agents en hulpprogramma's om het uitvoeren van query's en analyses te vereenvoudigen.
  • Correleer evaluatieuitvoerings-id's: koppel traceringsgegevens aan evaluatieuitvoeringen om zowel kwaliteit als prestaties in een uniforme weergave te analyseren.
  • Gevoelige inhoud redigeren: Verwijder of maskeer persoonlijke gegevens, geheimen en referentiegegevens uit prompts, hulpprogramma-argumenten en span-attributen voordat ze telemetrie bereiken.

Beveiliging en privacy

Tracering kan gevoelige informatie vastleggen, zoals gebruikersinvoer, modeluitvoer en hulpprogrammaargumenten en resultaten. Gebruik deze procedures om het risico te verminderen:

  • Sla geen geheimen, referenties of tokens op in prompts, programma-argumenten of kenmerken.
  • Persoonlijke gegevens en andere gevoelige inhoud redacteren of minimaliseren voordat deze in telemetrie worden weergegeven.
  • Traceringsgegevens behandelen als productietelemetrie en hetzelfde toegangsbeheer en bewaarbeleid toepassen dat u gebruikt voor logboeken en metrische gegevens.

Zie Toegang tot gevoelige inhoud beperken voor informatie over het routeren van gevoelige inhoud naar de toegewezen tabel en het beperken van de toegang tot deze tabel.

Probleemoplossing

Als tracelogs niet worden weergegeven in het Foundry-portaal of Application Insights:

  • Controleer of uw Foundry-project is verbonden met een Application Insights-resource.
  • Controleer of uw account over de vereiste machtigingen beschikt om een query uit te voeren op telemetriegegevens.
  • Zorg ervoor dat uw agentcode de benodigde instrumentatie bevat. Zie Traceringsintegraties voor frameworkspecifieke installatie.

Tip

Tracering is beschikbaar in alle regio's waar Foundry wordt ondersteund. Traceer gegevensretentie en steekproeven volgens uw Application Insights-configuratie. Zie Dataretentie en -archief in Azure Monitor Logboeken voor meer informatie.

Verwante inhoud

  • Last updated on