Schnellstart: Ihren gehosteten Agent nachverfolgen

Note

Tracing ist derzeit als Vorschau verfügbar.

In dieser Schnellstartanleitung zeigen Sie End-to-End-Ablaufverfolgungen für den gehosteten Agent an, den Sie in Der Bereitstellung Ihres ersten gehosteten Agents bereitgestellt haben. Sie verwenden Ihren Agent, um Trace-Daten zu erzeugen und Traces im Foundry-Portal zu prüfen.

Die Hostingbibliotheken (azure-ai-agentserver-responses und azure-ai-agentserver-invocations) lassen sich nahtlos in die Microsoft OpenTelemetry-Distribution integrieren, die sofort einsatzbereite Instrumentierung für Microsoft Agent Framework und LangChain bereitstellt und Ablaufverfolgungen an Application Insights exportiert. Darüber hinaus gibt der Foundry-Agent-Dienst serverseitige Telemetrie für den Agentaufruf automatisch aus – es sind keine Codeänderungen erforderlich.

Die Ablaufverfolgung bietet Ihnen Einblicke in die Behandlung der einzelnen Anforderungen, sodass Sie Probleme debuggen, Latenz überwachen und das Verhalten des Agents verstehen können, bevor Sie Änderungen an Benutzern freigeben.

Voraussetzungen

Bevor Sie beginnen, benötigen Sie Folgendes:

  • Ein bereitgestellter, aufrufbarer gehosteter Agent aus Bereitstellen Ihres ersten gehosteten Agents sowie das azd Projektverzeichnis, das Sie in dieser Schnellstartanleitung erstellt haben.

  • Die Rolle " Foundry User " in der Foundry-Ressource.

  • Um den Benutzeroberflächenpfad zu verwenden, greifen Sie auf das Foundry-Portal zu. Zum azd-Pfad siehe die folgenden Anforderungen.

  • Azure Developer CLI (AZD) 1.25.3 oder höher mit der azd microsoft.foundry Erweiterung:

    azd ext install microsoft.foundry

  • Eine authentifizierte azd Sitzung. Überprüfen Sie Ihren Status mit azd auth status, und führen Sie die Ausführung azd auth login aus, wenn Sie nicht angemeldet sind.

    Important

    Die Foundry-RBAC-Rollen wurden kürzlich umbenannt. Foundry User, Foundry Owner, Foundry Account Owner und Foundry Project Manager wurden zuvor Azure KI-Benutzer, Azure KI-Besitzer, Azure KI-Kontobesitzer und Azure AI Project Manager benannt. Möglicherweise werden die vorherigen Namen an einigen Stellen weiterhin angezeigt, während der Umbenennungsrollout ausgeführt wird. Die Rollen-IDs und Kernberechtigungen bleiben durch die Umbenennung unverändert.

  • Eine Azure Monitor Application Insights-Ressource, die mit Ihrem Foundry-Projekt verbunden ist. Informationen zum Einrichten finden Sie unter Einrichten der Ablaufverfolgung in Microsoft Foundry.

  • Die Rolle „Log Analytics-Leser“ für die Application Insights-Ressource, die mit Ihrem Projekt verbunden ist. Wenn die zugrunde liegenden Log Analytics Tabellen geschützt sind, weisen Sie auch die Rolle "Privileged Monitoring Data Reader" zu.

Schritt 1: Aufrufen Ihres Agents

Generieren Sie Trace-Daten, indem Sie eine Anfrage an Ihren bereitgestellten Agenten senden.

Senden Sie in Ihrem azd Projektverzeichnis eine Testaufforderung:

azd ai agent invoke "Summarize the benefits of distributed tracing for AI agents."

Sie sollten innerhalb weniger Sekunden eine Antwort sehen.

Jeder Aufruf generiert eine vollständige Ablaufverfolgung. Für aussagekräftigere Traces senden Sie Prompts, die Tool-Aufrufe oder mehrstufiges Schlussfolgern auslösen.

Schritt 2: Ablaufverfolgungen im Foundry-Portal anzeigen

Die Ablaufverfolgung kann nach dem Aufruf im Foundry-Portal eingesehen werden.

  1. Öffnen Sie im Foundry-Portal Ihr Projekt.
  2. Wählen Sie im linken Navigationsbereich "Agents" aus.
  3. Wählen Sie oben Traces aus.
  4. Finden Sie Ihre Ablaufverfolgung in der Liste. Sie können nach Trace-ID, Response-ID suchen oder nach einem Zeitbereich filtern.

Trajektorie

Screenshot der Ablaufverfolgungs-Wasserfallansicht im Foundry-Portal mit Spannweiten für invoke_agent, Chatabschlusse und Tokenanforderungen mit Eingabe-/Ausgabedetails auf der rechten Seite.

Benutzeransicht

Animation der Trace-Ansicht für Benutzer im Foundry-Portal.

Tip

Wenn Ihr Agent Microsoft Agent Framework verwendet, gibt er automatisch seine eigene OpenTelemetry-Spanne aus. Diese Spannweiten werden als untergeordnete Elemente der Hostebene angezeigt, sodass Sie eine vollständige Ablaufverfolgungsstruktur von der HTTP-Anforderung über die Agent-Orchestrierung zu einzelnen Toolaufrufen und LLM-Interaktionen erhalten.

Bereinigen von Ressourcen

Nachverfolgungsdaten werden in Application Insights gespeichert und unterliegen den Datenaufbewahrungseinstellungen Ihres Arbeitsbereichs. In dieser Schnellstartanleitung werden keine zusätzlichen Ressourcen erstellt. Um alles zu entfernen, was Sie in diesem und dem vorherigen Schnellstart erstellt haben, führen Sie azd down im Verzeichnis Ihres Agent-Projekts aus.

Warning

azd down Löscht alle Ressourcen in der Ressourcengruppe dauerhaft, einschließlich des Foundry-Projekts, Modellbereitstellungen, Application Insights und des gehosteten Agents.

Troubleshooting

Issue Lösung
Wenn keine von Foundry gehosteten Agenten verwendet werden, werden Traces nicht angezeigt. In dieser Schnellstartanleitung werden nur gehostete Agents behandelt. Informationen zu Tracing-Agents, die außerhalb von Foundry gehostet werden, finden Sie unter Einen externen Agent registrieren.
Nach dem Aufruf des Agents werden keine Ablaufverfolgungen angezeigt. Bestätigen Sie, dass Application Insights mit Ihrem Foundry-Projekt verbunden ist. Wenn sie nicht aktiviert ist, lesen Sie "Einrichten der Ablaufverfolgung in Microsoft Foundry". Überprüfen Sie, ob der Agent mit azd ai agent invoke erfolgreich geantwortet hat.
Ablaufverfolgungen werden angezeigt, aber es fehlen Eingabe-/Ausgabedatenattribute. Aktivieren Sie die Inhaltsaufzeichnung, indem Sie die Umgebungsvariable OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true in Ihrer Agentkonfiguration festlegen.
AuthorizationFailed beim Anzeigen von Ablaufverfolgungen Sie benötigen die Rolle „Log Analytics-Leser“ für die Application Insights-Ressource. Wenn die Tabellen geschützt sind, weisen Sie auch privileged Monitoring Data Reader zu.
Ablaufverfolgungen werden angezeigt, aber Spans für Tool-Aufrufe fehlen Überprüfen Sie, ob Ihr Agent Tools definiert, und das Modell ruft sie während der Anforderung auf. Wenn Sie Microsoft Agent Framework verwenden, vergewissern Sie sich, dass Tools beim Agent-Konstruktor über den tools-Parameter registriert werden. Weitere Informationen finden Sie unter Hinzufügen von Tools zu Ihrem Agent.
AuthenticationError oder DefaultAzureCredential Fehler Aktualisieren Sie anmeldeinformationen mit azd auth logout und dann azd auth login.

Was Sie gelernt haben

In dieser Schnellstartanleitung führen Sie die folgenden Schritte aus:

  • Erfahren Sie, dass Hosting-Bibliotheken die Microsoft OpenTelemetry-Distribution für eine sofort einsatzbereite Instrumentierung integrieren.
  • Der bereitgestellte Agent wurde aufgerufen, um Ablaufverfolgungsdaten zu generieren.
  • End-to-End-Ablaufverfolgungen im Foundry-Portal angezeigt.

Nächste Schritte

Ablaufverfolgung in Microsoft Foundry einrichten

Verwandte Inhalte

  • Last updated on