Debuggen eines gehosteten Agents

Diagnostizieren und beheben Sie häufige Probleme beim Erstellen, Ausführen und Bereitstellen von Agenten mit azd ai agent für Microsoft Foundry. Beginnen Sie mit den Diagnosebefehlen. Verwenden Sie dann die symptombasierten Abschnitte, um probleme mit Authentifizierung, lokaler Entwicklung, Bereitstellung, direkten Befehlen, Protokollen und Routinen zu beheben.

Voraussetzungen

Diagnosekontext sammeln

Bevor Sie in bestimmte Fehler eintauchen, verwenden Sie diese Befehle, um Kontext zu sammeln:

# Check extension version
azd ai agent version

# Verify Azure authentication
azd auth login

# Show current environment configuration
azd env get-values

# View agent details
azd ai agent show

# Show the resolved Foundry project endpoint and where it came from
azd ai project show

# Stream production logs
azd ai agent monitor --follow

Führen Sie azd ai agent doctor aus, um einen strukturierten Statusbericht zu erhalten. Weitere Informationen finden Sie unter Diagnose eines Projekts mit Agent-Arzt.

Diagnose der Aufruflatenz

Verwenden Sie die Latenz-Debug-Header, um festzustellen, ob eine langsame Anforderung an einen gehosteten Agent Zeit in der Plattform, in der Bereitstellungsinfrastruktur, beim Warten auf den Container oder bei der Verarbeitung der Anforderung durch Ihren Agent verbracht hat. Diese Header sind Diagnosesignale, keine SLA- oder Abrechnungsmetriken.

Aktivieren Sie die Diagnose für jede Anforderung durch Festlegen x-ms-debug-latency-enabled: true. Wenn die Anforderung diesen Header nicht enthält, enthält die Antwort nicht die x-ms-debug-latency-* Header.

  1. Fügen Sie den Latenzheader zu einer gehosteten Agent-Antwort- oder Aufrufprotokollanforderung hinzu. In diesem Beispiel wird das Antwortprotokoll verwendet:

    ENDPOINT="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token \
  --resource https://ai.azure.com \
  --query accessToken -o tsv)
AGENT="my-code-agent"

curl --http2 -i -X POST \
  "$ENDPOINT/agents/$AGENT/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-ms-debug-latency-enabled: true" \
  -d '{"model":"gpt-5.4-mini","input":"Hello, agent!","stream":false}'

  2. Überprüfen Sie die Antwort-Header. Alle Latenzwerte sind ganze Millisekunden:

    Header Meaning
    x-ms-debug-latency-session-start-type Art des Sitzungsstarts, die durch die Anforderung ausgelöst wurde: Kaltstart (cold), Warmstart (warm) oder Wiederaufnahme aus dem Leerlauf (resume).
    x-ms-debug-latency-platform-preprocessing-ms Plattformlaufzeit für Zugang, Authentifizierung, Sitzungsabfrage und Orchestrierung. Es berücksichtigt weder Verzögerungen bei der Bereitstellung von Micro-VMs noch Verzögerungen bei der Einsatzbereitschaft von Containern. Verfügbar für Kalt-, Warm- und Fortsetzungssitzungsstarts.
    x-ms-debug-latency-infra-setup-ms Zeit für die Bereitstellung der Micro-VM. Wird bei warmen Anforderungen weggelassen.
    x-ms-debug-latency-container-readiness-ms Zeit von der Erstellung der Micro-VM bis der Container Bereitschaft meldet. Wird bei warmen Anforderungen weggelassen.
    x-ms-debug-latency-container-response-ms Zeit von der Weiterleitung durch den Proxy bis zum Schreiben der Antwort-Header. Umfasst die Übertragung von Anfragen, die Verbindungseinrichtung, die Agentenverarbeitung, Wiederholungsversuche und die ausgaberichtliniengesteuerte Pufferung.
    x-ms-debug-latency-response-begin-ms Gesamtzeit von der Annahme der Anforderung durch den Dienst bis zum Committen der Antwortheader. Dieser Wert ist nicht die Zeit bis zum ersten Byte des Antworttexts oder bis zum ersten serverseitig gesendeten Ereignis.

    Die vier Zeitkomponenten ergeben zusammen x-ms-debug-latency-response-begin-ms. Wenn die Plattform nicht jede Bereitstellungsgrenze erfassen kann, werden bei einer kalten oder wiederaufgenommenen Anforderung die Infrastruktur- und Bereitschaftsheader weggelassen und diese Zeit in die Plattformvorverarbeitung eingeschlossen.

  3. Verwenden Sie den Sitzungsstarttyp und die größte Timing-Komponente, um die wahrscheinliche Verzögerungsquelle zu identifizieren:

    Result Auslegung Was zu tun ist
    x-ms-debug-latency-session-start-type ist cold oder resume, und x-ms-debug-latency-infra-setup-ms ist hoch Die Plattform hat Zeit für die Bereitstellung der Micro-VM aufgewendet. Vergleichen Sie mehrere kalte oder wiederaufgenommene Anforderungen. Wenn die Verzögerung weiterhin besteht, notieren Sie die Antwort-ID, den Zeitstempel und die Latenzheader für eine Supportanfrage.
    x-ms-debug-latency-session-start-type ist cold oder resume, und x-ms-debug-latency-container-readiness-ms ist hoch Der Container hat viel Zeit in Anspruch genommen, um den Start und den Bericht fertig zu machen. Messen Sie die Initialisierungsschritte in Ihren Startprotokollen, reduzieren Sie den Arbeitsaufwand, bevor der Readiness-Endpunkt verfügbar wird, und vorkompilieren Sie Anwendungscode, wo möglich.
    x-ms-debug-latency-platform-preprocessing-ms ist hoch für jeden Sitzungsstarttyp. Die Verzögerung trat in der Plattform vor der Bereitstellung von Micro-VMs oder der Bereitschaft von Containern auf. Erstellen Sie eine Supportanfrage. Schließen Sie die Antwort-ID, den Zeitstempel, den Sitzungsstarttyp und Latenzheader ein.
    x-ms-debug-latency-container-response-ms, x-ms-debug-latency-first-byte-ms oder first_byte_ms des Trailers ist hoch Die Verzögerung ist aufgetreten, nachdem die Proxyweiterleitung begonnen hat. Instrumentieren Sie den Anforderungshandler und prüfen Sie Agentprotokolle, Modellaufrufe, Toolaufrufe, Wiederholungen und Ausgabepuffer.

Verringern der Zeit für die Containerbereitschaft

Der Readiness-Wert des Containers umfasst die Zeit, die benötigt wird, um Ihren Prozess zu starten, die Anwendung zu laden und von /readiness HTTP 200 zurückzugeben. Fügen Sie Zeitstempel zu Startprotokollen hinzu, um langsame Importe, Abhängigkeitsladevorgang, Netzwerkaufrufe und andere Initialisierungsaufgaben zu identifizieren.

Wenden Sie diese Optimierungen auf die langsamen Schritte an, die Sie identifizieren:

  • Installieren Sie Abhängigkeiten und kompilieren Sie Code, wenn Sie das Image erstellen. Führen Sie beim Start des Containers keine Paketinstallation, Wiederherstellung oder Kompilierung aus.
  • Verwenden Sie einen mehrstufigen Build, und schließen Sie Buildtools, Paketcaches, Tests und andere Entwicklungsdateien aus dem Laufzeitimage aus.
  • Vermeiden Sie Modellaufrufe, Migrationen, Toolermittlungen und Ressourcendownloads vor der Bereitschaft. Parallelisieren Sie die unabhängigen Initialisierungsvorgänge, die zuerst abgeschlossen sein müssen.
  • Konzentrieren Sie /readiness sich darauf, ob der Agent Anforderungen annehmen kann. Wenn Sie die Initialisierung verzögern, messen Sie die erste Anforderung, um sicherzustellen, dass Sie die Startverzögerung nicht in die Anforderungsverarbeitung verschoben haben.

Installieren Sie Abhängigkeiten in einer virtuellen Umgebung, die Sie in das Laufzeitimage kopieren. Kompilieren Sie Abhängigkeiten nach dem Best-Effort-Prinzip, sodass eine Datei in einem Drittanbieterpaket, die nicht geparst werden kann, nicht zum Fehlschlagen des Builds führt. Kompilieren Sie die Anwendung mit strenger Prüfung, sodass Syntaxfehler zum Fehlschlagen des Builds führen.

FROM python:3.13-slim AS build

WORKDIR /app
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
RUN PYTHONDONTWRITEBYTECODE= python -m compileall -q /opt/venv \
      || true; \
    PYTHONDONTWRITEBYTECODE= python -m compileall -q /app

FROM python:3.13-slim AS final

ENV PATH="/opt/venv/bin:$PATH"
WORKDIR /app

COPY --from=build /opt/venv /opt/venv
COPY --from=build /app /app

# Precompile the standard library in the runtime image.
RUN PYTHONDONTWRITEBYTECODE= python -m compileall -q \
    "$(python -c "import sysconfig; print(sysconfig.get_path('stdlib'))")" \
    || true

CMD ["python", "main.py"]

Das Deaktivieren von PYTHONDONTWRITEBYTECODE für diesen Buildschritt ermöglicht es Python, den Bytecode im Image zu speichern. Die Umgebungsvariable blockiert Bytecode-Schreibvorgänge, nicht gelesen, sodass der ausgeführte Container weiterhin die kompilierten Dateien verwenden kann.

Referenz: compileall - Python-Bibliotheken bytekompilieren

Erstellen Sie eines der Bilder für die x86-64-Architektur, die von gehosteten Agents benötigt wird:

docker build --platform linux/amd64 -t my-agent:latest .

Hier ist linux/amd64 eine Docker-Plattform, kein .NET-Runtimebezeichner.

Referenz: Anforderungen für gehostete Agentcontainer

Untersuchen der Agent- und Modelllatenz

Wenn der Container schnell bereit ist, die Containerantwort oder die Zeit bis zum ersten Byte jedoch hoch, konzentrieren Sie Ihre Untersuchung auf den Anforderungspfad nach Beginn der Weiterleitung. Führen Sie azd ai agent monitor --follow aus, während Sie die Anfrage reproduzieren, und fügen Sie Tracing für Modellaufrufe, Toolaufrufe, externe Dienste, Wiederholungen und die Antwortserialisierung hinzu. Weitere Informationen finden Sie unter Überwachen der Protokolle des gehosteten Agents.

Messen Sie für einen Agent, der ein großes Sprachmodell aufruft, die Modelllatenz separat, bevor Sie die Bereitstellung ändern. Vergleichen Sie die Zeit bis zum ersten Token, die Zeit zwischen den Tokens, die Anzahl der generierten Tokens, die Promptgröße, die Auslastung der Bereitstellung und die Drosselung. Bewerten Sie dann die Modellauswahl, Ausgabetokenbeschränkungen, Streaming und Workloadtrennung. Siehe Verbessern Azure OpenAI-Leistung.

Wenn Messungen anhaltende Kapazitätsengpässe bei einer vorhersehbaren Arbeitslast zeigen, prüfen Sie ein bereitgestelltes Deployment und dimensionieren Sie es anhand der beobachteten Eingabe-Token, Ausgabe-Token und Anforderungsrate. Siehe bereitgestellter Durchsatz.

Fertigstellungszeiten prüfen

Bei HTTP/2 oder höher kann der Dienst den x-ms-debug-latency-final-Antworttrailer nach bestem Bemühen zurückgeben. Sie wiederholt die Antwortheaderwerte und kann diese Felder hinzufügen:

Feld Meaning
first_byte_ms Zeit von der Annahme der Anforderung bis zum ersten Byte des Antworttexts oder einem serverseitig gesendeten Ereignis.
total_last_byte_ms Zeit von der Serviceakzeptanz bis zum Abschluss der Antwortweiterleitung.

Der Trailer verwendet ein versioniertes, durch Semikolons getrenntes Format:

x-ms-debug-latency-final: v=1;start=cold;platform_pre_ms=...;
  infra_ms=...;ready_ms=...;container_response_ms=...;
  response_begin_ms=...;first_byte_ms=...;total_last_byte_ms=...

HTTP/1.1-Antworten enthalten diesen Trailer nicht. Ein Trailer kann auch nach einem Abbruch, der Trennung des Clients, einem Midstream-Fehler oder dann fehlen, wenn ein Gateway oder SDK Trailer nicht beibehält. Behandeln Sie die Antwort-Header als die garantierte diagnostische Zusicherung.

Abrufen gespeicherter Latenzergebnisse

Der Dienst speichert erfasste Zeitangaben mit der Antwort bzw. dem Aufruf. Eine spätere GET-Anforderung für dieselbe Antwort-ID oder Aufruf-ID gibt die Zeitangaben der ursprünglichen Anforderung als Antwortheader zurück. Die GET-Anforderung erfordert keinen Latenzheader und misst die GET-Anforderung nicht selbst.

Die GET-Anforderung kann diese Abschlusswerte auch als normale Header zurückgeben:

Header Meaning
x-ms-debug-latency-first-byte-ms Zeit bis zum ersten Byte des Antworttexts.
x-ms-debug-latency-total-last-byte-ms Zeit bis zum Abschluss der Antwortweiterleitung.

Der Speicher ist schließlich konsistent, sodass eine GET-Anforderung unmittelbar nach der ursprünglichen Anforderung die Header noch nicht enthält. Für eine asynchrone Antwort oder einen Aufruf sind nur die Plattform-Overhead-Werte verfügbar: Sitzungsstarttyp, Plattformvorverarbeitung, Infrastruktureinrichtung und Containerbereitschaft. Latenzheader werden für fehlgeschlagene Proxyantworten oder WebSocket-Anforderungen (invocations_ws) nicht ausgegeben.

Beheben von Authentifizierungsfehlern

Beheben von AuthenticationError

Symptome: Der Agent kann beim Aufrufen des KI-Modells nicht lokal gestartet werden oder gibt 401/403 zurück.

Ursachen und Korrekturen:

  • Abgelaufene Anmeldeinformationen -- Führen Sie azd auth login aus, um Ihre Azure-Sitzung zu aktualisieren.
  • Falsches Abonnement – Überprüfen und Vergleichen mit azd env get-values | grep AZURE_SUBSCRIPTION_ID dem Abonnement des Foundry-Projekts.
  • Fehlende RBAC-Rollen – Ihre Identität benötigt Foundry User oder gleichwertigen Zugriff auf das Foundry-Projekt.

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.

Ihre Identität benötigt außerdem Cognitive Services OpenAI-Benutzer, um Modellbereitstellungen verwenden zu können.

Beheben von AuthorizationFailed während der Bereitstellung

Symptome:azd up oder azd provision schlägt mit einem Berechtigungsfehler fehl.

Lösung: Fordern Sie die Rolle "Mitwirkender" für Ihr Azure-Abonnement an. Für CI/CD benötigt der Dienstprinzipal außerdem Foundry-Besitzer.

Beheben von SubscriptionNotRegistered

Symptome: Die Bereitstellung schlägt fehl, da ein erforderlicher Ressourcenanbieter nicht registriert ist.

Lösung:

az provider register --namespace Microsoft.CognitiveServices
az provider register --namespace Microsoft.ContainerRegistry

Beheben lokaler Entwicklungsprobleme

Verbindungsverweigerung auf Port 8088 beheben

Symptome:azd ai agent invoke --local es kann keine Verbindung hergestellt werden.

Ursachen und Korrekturen:

  • Agent wird nicht ausgeführt -- Starten Sie ihn mit azd ai agent run in einem separaten Terminal.

  • Portkonflikt – Ein anderer Prozess verwendet Port 8088. Beenden Sie sie, oder verwenden Sie einen benutzerdefinierten Port:

    azd ai agent run --port 9090
azd ai agent invoke --local --port 9090 "Hello!"

  • Absturz beim Start -- Überprüfen Sie das Terminal, in dem azd ai agent run ausgeführt wird, auf Fehlermeldungen. Häufige Ursachen sind fehlende Abhängigkeiten, Importfehler oder eine falsche startupCommand in azure.yaml.

Fehler bei der Installation von Abhängigkeiten beheben

Symptome:azd ai agent run Der Vorgang schlägt während der Installation von Abhängigkeiten fehl.

Ursachen und Korrekturen:

  • Falsche Laufzeitversion - Stellen Sie sicher, dass Python 3.10+ oder .NET 8+ installiert ist.
  • Fehlende requirements.txt oder .csproj -- Die CLI erkennt den Projekttyp automatisch aus diesen Dateien. Überprüfen Sie, ob sie in Ihrem Agentverzeichnis vorhanden sind.
  • Netzwerkprobleme – Paketregistrierungen können von Ihrem Unternehmensproxy blockiert werden. Überprüfen Sie Ihre pip- oder dotnet-Konfiguration.

Beheben ResourceNotFound oder DeploymentNotFound

Symptome: Der Agent wird gestartet, schlägt jedoch fehl, wenn versucht wird, das Modell aufzurufen.

Ursachen und Korrekturen:

  • Endpunkt stimmt nicht überein -- Führen Sie azd env get-values aus, und überprüfen Sie, ob FOUNDRY_PROJECT_ENDPOINT mit dem im Foundry-Portal angezeigten Endpunkt übereinstimmt.
  • Modellbereitstellungsname stimmt nicht überein – Der im Modell konfigurierte azure.yaml Bereitstellungsname muss mit dem Bereitstellungsnamen in Ihrem Foundry-Projekt übereinstimmen. Überprüfen Sie das Portal unter "Bereitstellungen".
  • Nicht provisionierte Ressourcen -- Wenn Sie azd up noch nicht ausgeführt haben, sind die Cloudressourcen noch nicht vorhanden. Führen Sie zuerst azd up aus und testen Sie dann lokal. Der lokale Agent ruft weiterhin in der Cloud gehostete Modelle auf.

Beheben von Bereitstellungsproblemen

Beheben von Containerbuildfehlern

Symptome:azd up schlägt während der Docker-Buildphase fehl.

Ursachen und Korrekturen:

  • Dockerfile fehlt -- Stellen Sie sicher, dass Ihr Agentverzeichnis eine Dockerfile enthält. Wenn Sie aus einer Vorlage initialisiert haben, wird dies automatisch generiert.
  • Fehler beim Build-Kontext -- Dockerfile muss sich in dem Verzeichnis befinden, das durch den Dienstpfad project in azure.yaml angegeben ist.
  • Abhängigkeitsinstallation in Docker: Wenn die pip/dotnet-Wiederherstellung im Container fehlschlägt, überprüfen Sie, ob in requirements.txt oder .csproj alle Abhängigkeiten ordnungsgemäß angeheftet sind.

Beheben von Hängenbleiben oder Timeouts bei azd up

Symptome: Die Provisionierung oder Bereitstellung dauert ungewöhnlich lange.

Ursachen und Korrekturen:

  • Erste Bereitstellung -- Die erste Bereitstellung azd up stellt alle Azure-Ressourcen bereit, einschließlich des Foundry-Projekts, ACR, der verwalteten Identität und der Modellbereitstellung, und kann 5–10 Minuten dauern. Nachfolgende Bereitstellungen sind schneller.
  • Remotebuild – Standardmäßig werden Containerimages remote auf ACR erstellt. Dies kann langsamer sein, erfordert jedoch docker nicht lokal. Wenn Sie stattdessen lokal erstellen möchten, legen Sie docker.remoteBuild: false in Ihrer azure.yaml-Dienstkonfiguration fest.
  • Regionskapazität – Einige Regionen haben möglicherweise eine begrenzte Kapazität für bestimmte Modell-SKUs. Versuchen Sie eine andere Region, wenn die Bereitstellung konsistent fehlschlägt.

Einen Agenten beheben, der bereitgestellt wird, aber nicht reagiert

Symptome:azd ai agent invoke führt zu einem Timeout oder gibt nach einer erfolgreichen Bereitstellung Fehler zurück.

Ursachen und Korrekturen:

  • Fehler beim Integritätstest: Ihr Container muss auf GET /readiness an Port 8088 mit dem Status 200 antworten. Überprüfen Sie Protokolle mit azd ai agent monitor --follow.
  • Protokollkonflikt – Stellen Sie sicher, dass das im azure.ai.agent Dienst azure.yaml definierte Protokoll mit dem übereinstimmt, was Ihr Code implementiert. Wenn azure.yamlresponses sagt, Ihr Code aber nur invocations verarbeitet, oder umgekehrt, schlagen Anfragen fehl.
  • Containerabstürzen – Überprüfen Sie systemprotokolle auf Neustartereignisse: azd ai agent monitor --type system. Häufige Ursachen sind unbehandelte Ausnahmen und Probleme durch unzureichenden Speicher. Erhöhen Sie bei Bedarf die Containerressourcen in azure.yaml.

Beheben von Direct-Command-Fehlern

Diese Fehler stammen von den direkten azd ai-Befehlen wie azd ai connection, azd ai toolbox und azd ai routine, wenn sie für ein Foundry-Projekt ausgeführt werden.

Fehlerbehebung bei nicht aufgelöstem Foundry-Projektendpunkt

Symptome: Ein direkter Befehl wird mit No Foundry project endpoint resolved. Run azd ai project set to set one, or pass --project-endpoint. beendet

Ursache: Die CLI konnte in keiner der unterstützten Quellen einen Foundry-Projektendpunkt finden: das --project-endpoint Flag, die aktive azd Umgebung, die globale Konfiguration oder die FOUNDRY_PROJECT_ENDPOINT Umgebungsvariable.

Fehlerbehebungen:

  • Führen Sie den Befehl aus azd ai project set <endpoint> , um den Endpunkt in Ihrer globalen azd Konfiguration (~/.azd/config.json) zu speichern.
  • Übergeben Sie --project-endpoint (-p) bei jedem Befehl: azd ai connection list -p https://my-proj.services.ai.azure.com/api/projects/my-project.
  • Legen Sie FOUNDRY_PROJECT_ENDPOINT in Ihrer Shellumgebung fest.

Die vollständige Auflösungsreihenfolge und der Zeitpunkt, an dem jede Quelle gewinnt, finden Sie unter "Grundlegendes zum Kontext des azd-Projekts".

Beheben von Erstellungsfehlern für vorhandene Ressourcen

Symptome:azd ai connection create, azd ai toolbox create, azd ai routine create oder azd ai skill create schlägt mit der Fehlermeldung „bereits vorhanden“ fehl.

Ursache:create ist standardmäßig kein Upsert. Der Standardfehlermodus verhindert, dass ein Entwickler den Status eines anderen in einem freigegebenen Foundry-Projekt im Hintergrund überschreibt.

Fehlerbehebungen:

  • Wählen Sie einen anderen Namen aus, und führen Sie den Vorgang erneut aus.
  • Übergeben Sie --force, sofern der Befehl create dies unterstützt, um die vorhandene Ressource durch einen ARM PUT zu ersetzen. Das Ersetzen ist destruktiv: Die vorhandene Ressource wird direkt überschrieben, und jegliche Abweichung durch manuelle Portalbearbeitungen, Metadaten oder Anmeldeinformationen geht verloren. Der azd ai toolbox create Befehl unterstützt --forcenicht . Löschen Sie die vorhandene Toolbox, oder verwenden Sie stattdessen einen neuen Namen.

Beheben der Anmeldeinformationsausgabe von connection show

Symptome:azd ai connection show <name> gibt den Namen, die Art, das Ziel und den Authentifizierungstyp der Verbindung zurück, aber keinen API-Schlüssel oder Anmeldeinformationswert.

Ursache: Standardmäßig werden anmeldeinformationswerte nicht zurückgegeben. Sie erfordern die explizite --show-credentials Kennzeichnung.

Lösung:

azd ai connection show tavily-conn --show-credentials

Dadurch wird die Datenebenen-API aufgerufen, und es sind Datenebenenberechtigungen für das Foundry-Projekt erforderlich, z. B. "Foundry User" oder gleichwertig. Wenn Sie nur über Management-Ebene-Reader- oder -Contributor-Zugriff verfügen, schlägt der Aufruf mit einem 403-Fehler fehl. Bitten Sie Ihren Projektbesitzer um die Datenebenenrolle.

Lesen von Agentprotokollen

Verwenden Sie azd ai agent monitor, um das Verhalten des Agenten zu überprüfen:

# Stream all recent logs
azd ai agent monitor --follow

# View system-level events (container starts, crashes, restarts)
azd ai agent monitor --type system

# Filter to a specific session
azd ai agent monitor --session-id <session-id>

Zu den allgemeinen Protokollmustern gehören:

Protokollmeldung Meaning
Listening on 0.0.0.0:8088 Agent erfolgreich gestartet.
AuthenticationError Problem mit Anmeldeinformationen oder RBAC. Überprüft die verwaltete Identität.
ModelNotFound Der Modellbereitstellungsname stimmt nicht mit azure.yaml überein.
Neustart eines Containers in Systemereignissen Absturzschleife. Überprüfen Sie Codefehler, oder erhöhen Sie ressourcengrenzwerte.

Diagnostizieren von Routinefehlern

Routinen schlagen anders als interaktive agent invoke Anrufe fehl, da kein Aufrufer vorhanden ist, um den Fehler anzuzeigen. Eine Routine ist eine zeitgesteuerte, wiederkehrende, durch ein GitHub-Issue ausgelöste oder durch ein benutzerdefiniertes Ereignis ausgelöste Ausführung eines Agenten. Verwenden Sie azd ai routine run list, um zu überprüfen, was passiert ist.

Frühere Ausführungen prüfen

# Recent runs of a routine: trigger time, agent input/output, status, trace link
azd ai routine run list daily-digest

Nach Fehlern filtern

# Failed runs only, with an OData filter
azd ai routine run list daily-digest --filter "status eq 'failed'"

Kombinieren Sie es mit --top, um das Fenster zu vergrößern oder zu verkleinern.

Ausführen eines Drilldowns in eine einzelne Ausführung

# Full detail for the most recent runs as JSON, then look up the run you care about
azd ai routine run list daily-digest --top 5 --output json

Die JSON-Ausgabe enthält die Eingabenutzlast, die Antwort des Agents und einen Deep-Link zur verteilten Ablaufverfolgung, also dieselbe Ablaufverfolgung, die Sie bei einem interaktiven Aufruf sehen würden.

Routine manuell erneut auslösen

Wenn Sie einen Fehlerfall reproduzieren oder eine Fehlerbehebung testen müssen, starten Sie die Routine bei Bedarf mit dispatch:

azd ai routine dispatch daily-digest
azd ai routine dispatch triage-issues --input '{"issue":{"number":42}}'

dispatch wird asynchron ausgeführt und druckt eine Verteiler-ID. Überprüfen Sie das Ergebnis mit azd ai routine run list <name>.

Beheben einer fehlgeschlagenen Routineausführung

azd ai routine run list zeigt die Ausführung mit status: failed. Folgen Sie dem Link zur Ablaufverfolgung, um den zugrunde liegenden Agent-Fehler anzuzeigen, z. B. einen Modellfehler, einen Toolfehler oder ein Timeout. Die agentseitigen Korrekturen sind identisch mit interaktiven Fehlern. Siehe Beheben von Authentifizierungsfehlern und Lesen von Agentprotokollen.

Beheben einer Routine, die nie ausgelöst wird

Wenn azd ai routine run list überhaupt keine Ausführungen zurückgibt, wird der Trigger selbst nicht ausgelöst:

  1. Überprüfen Sie, ob die Routine aktiviert ist: azd ai routine show <name>. Suchen Sie nach enabled: true.
  2. Überprüfen Sie bei timer-Triggern, ob --at in der Zukunft liegt und noch nicht ausgelöst wurde.
  3. Bei recurring-Triggern überprüfen Sie, ob der --cron-Ausdruck gültig ist und dass --time-zone dem entspricht, was Sie erwartet haben.
  4. Überprüfen Sie bei github-issue-Triggern, ob --connection-id in eine fehlerfreie Verbindung aufgelöst wird und ob das GitHub-Repository und --issue-event mit den vom Repository ausgegebenen Ereignissen übereinstimmen.
  5. Überprüfen Sie bei custom Triggern, ob der --provider, --event-name und --parameters Bereich mit den Ereignissen übereinstimmt, die der Anbieter veröffentlicht.

Weitere Hilfe

  • Debugmodus: Fügen Sie einem beliebigen --debug-Befehl azd hinzu, um eine ausführliche Ausgabe zu erhalten.
  • Azure Portal – Überprüfen Sie das Foundry-Projekt im Azure Portal auf Ressourcenintegrität und Diagnose.
  • Einen Fehler melden -- Melden Sie Probleme unter github.com/Azure/azure-dev/issues.

Verwandte Inhalte

  • Zuletzt aktualisiert um