Debugowanie hostowanego agenta

Diagnozuj i rozwiązuj typowe problemy podczas tworzenia, uruchamiania i wdrażania agentów za pomocą azd ai agent dla Microsoft Foundry. Zacznij od poleceń diagnostycznych. Następnie skorzystaj z sekcji opartych na objawach, aby rozwiązać problemy z uwierzytelnianiem, programowaniem lokalnym, wdrażaniem, bezpośrednimi poleceniami, dziennikami i procedurami.

Wymagania wstępne

Zbieranie kontekstu diagnostycznego

Przed zagłębieniem się w określone błędy użyj tych poleceń, aby zebrać kontekst:

# 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

Aby uzyskać ustrukturyzowany raport kondycji, uruchom polecenie azd ai agent doctor. Aby uzyskać więcej informacji, zobacz Diagnozowanie projektu za pomocą narzędzia Agent Doctor.

Diagnozuj opóźnienie wywołania

Użyj nagłówków debugowania opóźnień, aby określić, czy obsługa wolnego żądania do hostowanego agenta zajęła czas na platformie, na aprowizowanie infrastruktury, na oczekiwanie na kontener czy na przetwarzanie żądania przez agenta. Te nagłówki są sygnałami diagnostycznymi, a nie wskaźnikami SLA ani wskaźnikami rozliczeniowymi.

Włącz diagnostykę dla każdego żądania, ustawiając wartość x-ms-debug-latency-enabled: true. Jeśli żądanie nie zawiera tego nagłówka, odpowiedź nie będzie zawierać x-ms-debug-latency-* nagłówków.

  1. Dodaj nagłówek opóźnień do żądania protokołu Responses lub Invocations dla hostowanego agenta. W tym przykładzie użyto protokołu Responses:

    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. Sprawdź nagłówki odpowiedzi. Wszystkie wartości opóźnienia to liczba całkowita milisekund:

    Nagłówka Meaning
    x-ms-debug-latency-session-start-type Typ uruchomienia sesji wywołanego przez żądanie: zimny start (cold), ciepły start (warm) lub wznowienie po stanie bezczynności (resume).
    x-ms-debug-latency-platform-preprocessing-ms Czas platformy na dopuszczenie, uwierzytelnianie, wyszukiwanie sesji i orkiestrację. Nie obejmuje to aprowizacji mikro maszyn wirtualnych ani opóźnień gotowości kontenera. Dostępne dla zimnych, ciepłych i wznowionych uruchomień sesji.
    x-ms-debug-latency-infra-setup-ms Czas utworzyć mikromaszynę wirtualną. Pominięto w przypadku ciepłych żądań.
    x-ms-debug-latency-container-readiness-ms Czas od utworzenia mikro maszyny wirtualnej do momentu, aż kontener będzie gotowy. Pominięto w przypadku ciepłych żądań.
    x-ms-debug-latency-container-response-ms Czas od momentu przekazania przez serwer proxy do momentu zatwierdzenia nagłówków odpowiedzi. Obejmuje przesyłanie żądań, konfigurację połączenia, obsługę agenta, ponawianie prób i buforowanie zgodnie z zasadami wyjściowymi.
    x-ms-debug-latency-response-begin-ms Całkowity czas od akceptacji usługi do momentu zatwierdzenia nagłówków odpowiedzi. Ta wartość nie oznacza czasu do otrzymania pierwszego bajtu treści odpowiedzi ani pierwszego zdarzenia przesłanego przez serwer.

    Cztery składowe czasowe sumują się do x-ms-debug-latency-response-begin-ms. W przypadku żądania uruchamianego na zimno lub wznawianego, jeśli platforma nie może uchwycić każdego etapu procesu aprowizacji, pomija nagłówki dotyczące infrastruktury i gotowości oraz wlicza ten czas do wstępnego przetwarzania przez platformę.

  3. Użyj typu rozpoczęcia sesji i najdłuższego składnika czasu, aby określić prawdopodobne źródło opóźnienia:

    Result Interpretacja Co zrobić
    x-ms-debug-latency-session-start-type jest cold lub resume, i x-ms-debug-latency-infra-setup-ms jest wysoki Platforma potrzebowała czasu na utworzenie mikromaszyny wirtualnej. Porównaj kilka zimnych lub wznowionych żądań. Jeśli opóźnienie będzie się powtarzać, zarejestruj identyfikator odpowiedzi, znacznik czasu i nagłówki opóźnienia dla żądania pomocy technicznej.
    x-ms-debug-latency-session-start-type jest cold lub resume, i x-ms-debug-latency-container-readiness-ms jest wysoki Uruchomienie kontenera i przygotowanie raportu zajęło dużo czasu. Mierz etapy inicjalizacji w logach uruchamiania, ogranicz zakres pracy, zanim endpoint gotowości stanie się dostępny, i wstępnie kompiluj kod aplikacji tam, gdzie to możliwe.
    x-ms-debug-latency-platform-preprocessing-ms jest wysoki dla dowolnego typu rozpoczęcia sesji Opóźnienie wystąpiło na platformie przed aprowizowaniem mikro-maszyn wirtualnych lub gotowością kontenera. Utwórz wniosek o pomoc techniczną. Uwzględnij identyfikator odpowiedzi, znacznik czasu, typ rozpoczęcia sesji i nagłówki opóźnienia.
    x-ms-debug-latency-container-response-ms, lub x-ms-debug-latency-first-byte-msprzyczepa first_byte_ms jest wysoka Opóźnienie wystąpiło po rozpoczęciu przekazywania przez serwer proxy. Instrumentacja procedury obsługi żądań i inspekcja dzienników agentów, wywołań modelu, wywołań narzędzi, ponownych prób i buforowania danych wyjściowych.

Skrócenie czasu gotowości kontenera

Wskaźnik gotowości kontenera obejmuje czas wymagany do uruchomienia procesu, załadowania aplikacji i zwrócenia kodu stanu HTTP 200 pod adresem /readiness. Dodaj znaczniki czasu do dzienników uruchamiania, aby zidentyfikować powolne importowanie, ładowanie zależności, wywołania sieciowe i inne zadania inicjowania.

Zastosuj te optymalizacje do wolno działających etapów, które zidentyfikujesz:

  • Zainstaluj zależności i skompiluj kod podczas kompilowania obrazu. Nie uruchamiaj instalacji, przywracania ani kompilacji pakietu podczas uruchamiania kontenera.
  • Użyj wieloestegożowego kompilowania i wykluczania narzędzi kompilacji, pamięci podręcznych pakietów, testów i innych plików programistycznych z obrazu środowiska uruchomieniowego.
  • Unikaj wywołań modelu, migracji, odnajdywania narzędzi i pobierania zasobów przed gotowością. Uruchom równolegle niezależne procesy inicjalizacji, które muszą najpierw się zakończyć.
  • Koncentruj /readiness się na tym, czy agent może akceptować żądania. Jeśli odraczasz inicjalizację, zmierz czas obsługi pierwszego żądania, aby upewnić się, że opóźnienie uruchamiania nie zostało przeniesione do obsługi żądań.

Zainstaluj zależności w środowisku wirtualnym, które kopiujesz do obrazu środowiska uruchomieniowego. Kompiluj zależności w miarę możliwości, aby plik, którego nie można sparsować, w pakiecie zewnętrznym nie powodował niepowodzenia kompilacji. Skompiluj aplikację w trybie ścisłym, aby błędy składniowe powodowały niepowodzenie kompilacji.

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"]

Wyczyszczenie PYTHONDONTWRITEBYTECODE tego kroku kompilacji umożliwia Python zapis kodu bajtowego na obrazie. Zmienna środowiskowa blokuje zapisy kodu bajtowego, a nie odczyty, więc uruchomiony kontener nadal może używać skompilowanych plików.

Informacje: compileall — Kompilowanie bibliotek języka Python do kodu bajtowego

Utwórz dowolny obraz dla architektury x86-64 wymaganej przez hostowanych agentów:

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

linux/amd64 Oto platforma Docker, a nie identyfikator środowiska uruchomieniowego .NET.

Dokumentacja: Wymagania dotyczące kontenera hostowanego agenta

Badanie opóźnienia agenta i modelu

Jeśli gotowość kontenera jest szybka, ale czas odpowiedzi kontenera lub pierwszego bajtu jest wysoki, skoncentruj się na śledztwie na ścieżce żądania po rozpoczęciu przekazywania dalej. Uruchom azd ai agent monitor --follow podczas odtwarzania żądania i dodaj śledzenie wokół wywołań modelu, wywołań narzędzi, usług zewnętrznych, ponownych prób i serializacji odpowiedzi. Aby uzyskać więcej informacji, zobacz Monitorowanie dzienników agentów hostowanych.

W przypadku agenta, który wywołuje duży model językowy, należy mierzyć opóźnienie modelu oddzielnie przed zmianą wdrożenia. Porównaj czas do wygenerowania pierwszego tokenu, czas między tokenami, wygenerowaną liczbę tokenów, rozmiar monitu wejściowego, wykorzystanie wdrożenia i dławienie. Następnie oceń wybór modelu, limity tokenów wyjściowych, przesyłanie strumieniowe i separację obciążenia. Zobacz Poprawianie wydajności interfejsu OpenAI Azure.

Jeśli pomiary wskazują na utrzymującą się presję na pojemność przy przewidywalnym obciążeniu, rozważ wdrożenie z przydzieloną przepustowością i dobierz jego rozmiar na podstawie obserwowanej liczby tokenów wejściowych, tokenów wyjściowych oraz szybkości żądań. Zobacz Przepustowość aprowizowana.

Sprawdź czasy ukończenia

W protokole HTTP/2 lub nowszym usługa może zwrócić pole końcowe odpowiedzi x-ms-debug-latency-final w miarę możliwości. Powtarza wartości nagłówka odpowiedzi i może dodać następujące pola:

Pole Meaning
first_byte_ms Czas od akceptacji usługi, aż do pierwszego bajtu odpowiedzi lub zdarzenia wysłanego przez serwer.
total_last_byte_ms Czas od akceptacji usługi do momentu zakończenia przekazywania odpowiedzi.

Zwiastun używa formatu rozdzielanego średnikami:

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

Odpowiedzi HTTP/1.1 nie obejmują tego zwiastuna. Przyczepa może być również nieobecna po anulowaniu, rozłączeniu klienta, błędzie połowy strumienia lub gdy brama lub zestaw SDK nie zachowuje przyczep. Traktuj nagłówki odpowiedzi jako gwarantowany kontrakt diagnostyczny.

Pobieranie przechowywanych wyników opóźnienia

Usługa przechowuje zarejestrowane czasy wraz z odpowiedzią lub wywołaniem. Późniejsze żądanie GET dotyczące tej samej odpowiedzi lub identyfikatora wywołania zwraca w nagłówkach odpowiedzi czasy oryginalnego żądania. Żądanie GET nie wymaga nagłówka latency i nie mierzy samego żądania GET.

Żądanie GET może również zwrócić te wartości ukończenia jako zwykłe nagłówki:

Nagłówka Meaning
x-ms-debug-latency-first-byte-ms Czas do pierwszego bajtu treści odpowiedzi.
x-ms-debug-latency-total-last-byte-ms Czas do zakończenia przekazywania odpowiedzi.

Pamięć masowa jest spójna w sposób ostateczny, więc żądanie GET wysłane bezpośrednio po pierwotnym żądaniu może jeszcze nie zawierać tych nagłówków. W przypadku odpowiedzi asynchronicznej lub wywołania dostępne są tylko wartości związane z obciążeniem platformy: typ uruchomienia sesji, wstępne przetwarzanie platformy, konfiguracja infrastruktury i gotowość kontenera. Nagłówki opóźnień nie są emitowane dla nieudanych odpowiedzi serwera proxy ani żądań Protokołu WebSocket (invocations_ws).

Naprawianie błędów uwierzytelniania

Napraw AuthenticationError

Objawy: Agent nie uruchamia się lokalnie lub zwraca błąd 401/403 podczas wywoływania modelu AI.

Przyczyny i poprawki:

  • Wygasłe poświadczenia — uruchom polecenie azd auth login , aby odświeżyć sesję Azure.
  • Nieprawidłowa subskrypcja — zweryfikuj z azd env get-values | grep AZURE_SUBSCRIPTION_ID, czy jest zgodna z subskrypcją projektu Foundry.
  • Brak ról RBAC — Twoje konto wymaga roli Foundry User lub równoważnych uprawnień w projekcie Foundry.

Ważna

Niedawno zmieniono nazwy ról RBAC w usłudze Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.

Twoja tożsamość wymaga również użytkownika OpenAI usług Cognitive Services do korzystania z wdrożeń modelu.

Napraw AuthorizationFailed w trakcie aprowizacji

Objawy:azd up lub azd provision kończy się niepowodzeniem z powodu błędu uprawnień.

Poprawka: Zażądaj roli Współautor w ramach subskrypcji Azure. W przypadku CI/CD jednostka usługi głównej wymaga również roli Foundry Owner.

Napraw SubscriptionNotRegistered

Objawy: Aprowizowanie kończy się niepowodzeniem, ponieważ wymagany dostawca zasobów nie jest zarejestrowany.

Rozwiązanie:

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

Napraw problemy z lokalnym środowiskiem programistycznym

Rozwiązano problem z odmową połączenia na porcie 8088

Objawy:azd ai agent invoke --local Nie można nawiązać połączenia.

Przyczyny i poprawki:

  • Agent nie jest uruchomiony — uruchom go za pomocą azd ai agent run w osobnym terminalu.

  • Konflikt portów — inny proces używa portu 8088. Zatrzymaj go lub użyj portu niestandardowego:

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

  • Awaria podczas uruchamiania -- sprawdź komunikaty o błędach w terminalu, w którym uruchomiono azd ai agent run. Typowe przyczyny obejmują brakujące zależności, błędy importu lub nieprawidłowe startupCommand w pliku azure.yaml.

Napraw błędy instalacji zależności

Objawy:azd ai agent run niepowodzenie podczas instalacji zależności.

Przyczyny i poprawki:

  • Nieprawidłowa wersja środowiska uruchomieniowego — upewnij się, że zainstalowano Python 3.10 lub .NET 8 lub nowszych.
  • Brak requirements.txt lub .csproj — interfejs wiersza polecenia automatycznie wykrywa typ projektu z tych plików. Sprawdź, czy istnieją one w katalogu agenta.
  • Problemy z siecią — rejestry pakietów mogą być blokowane przez firmowy serwer proxy. Sprawdź konfigurację pip lub dotnet .

Napraw ResourceNotFound lub DeploymentNotFound

Objawy: Agent uruchamia się, ale kończy się niepowodzeniem podczas próby wywołania modelu.

Przyczyny i poprawki:

  • Niezgodność punktu końcowego — uruchom polecenie azd env get-values i sprawdź, czy FOUNDRY_PROJECT_ENDPOINT jest taki sam jak punkt końcowy widoczny w portalu Foundry.
  • Niezgodność nazwy wdrożenia modelu — nazwa wdrożenia modelu skonfigurowana w azure.yaml programie musi być zgodna z nazwą wdrożenia w projekcie Foundry. Sprawdź w portalu w sekcji Wdrożenia.
  • Zasoby nie są aprowiowane — jeśli jeszcze nie uruchomiono azd up , zasoby w chmurze nie będą istnieć. Najpierw uruchom azd up, a następnie przetestuj lokalnie. Agent lokalny nadal wywołuje modele hostowane w chmurze.

Rozwiązywanie problemów z wdrażaniem

Naprawianie błędów kompilacji kontenera

Objawy:azd up kończy się niepowodzeniem w fazie kompilacji platformy Docker.

Przyczyny i poprawki:

  • Brak pliku Dockerfile — upewnij się, że w katalogu agenta znajduje się plik Dockerfile. Jeśli zainicjowano go na podstawie szablonu, jest to generowane automatycznie.
  • Błędy kontekstu budowania — Dockerfile musi znajdować się w katalogu określonym przez ścieżkę usługi project zdefiniowaną w pliku azure.yaml.
  • Instalacja zależności w Dockerze — jeśli polecenie pip lub dotnet restore kończy się niepowodzeniem w kontenerze, sprawdź, czy w requirements.txt lub .csproj wszystkie zależności są poprawnie przypięte.

Napraw problem z azd up zawieszaniem się lub przekroczeniem limitu czasu

Objawy: Aprowizowanie lub wdrażanie trwa niezwykle długo.

Przyczyny i poprawki:

  • Pierwsze wdrożenie — pierwsze azd up aprowizuje wszystkie zasoby Azure, w tym projekt Foundry, usługę ACR, tożsamość zarządzaną i wdrożenie modelu oraz może potrwać 5–10 minut. Kolejne wdrożenia są szybsze.
  • Zdalna kompilacja — domyślnie obrazy kontenerów są tworzone zdalnie w usłudze ACR. Może to być wolniejsze, ale nie wymaga platformy Docker lokalnie. Aby zamiast tego budować lokalnie, ustaw docker.remoteBuild: false w konfiguracji usługi azure.yaml.
  • Pojemność regionu — niektóre regiony mogą mieć ograniczoną pojemność dla niektórych jednostek SKU modelu. Spróbuj użyć innego regionu, jeśli aprowizacja stale kończy się niepowodzeniem.

Napraw agenta, który został wdrożony, ale nie odpowiada

Objawy:azd ai agent invoke Operacja przekracza limit czasu lub zwraca błędy po pomyślnym wdrożeniu.

Przyczyny i poprawki:

  • Sonda kondycji kończy się niepowodzeniem — kontener musi odpowiadać na GET /readiness na porcie 8088 kodem stanu 200. Sprawdź dzienniki za pomocą polecenia azd ai agent monitor --follow.
  • Niezgodność protokołu — upewnij się, że protokół zdefiniowany w azure.ai.agent usłudze jest azure.yaml zgodny z implementacją kodu. Jeśli azure.yaml wskazuje responses, ale Twój kod obsługuje tylko invocations lub odwrotnie, żądania zakończą się błędem.
  • Awarie kontenera — sprawdź dzienniki systemowe pod kątem zdarzeń ponownego uruchomienia: azd ai agent monitor --type system. Typowe przyczyny obejmują nieobsługiwane wyjątki i problemy z pamięcią. Zwiększ zasoby kontenera w azure.yaml, jeśli to konieczne.

Naprawianie błędów poleceń bezpośrednich

Te błędy pochodzą z bezpośrednich poleceń azd ai, takich jak azd ai connection, azd ai toolbox i azd ai routine, gdy są uruchamiane w projekcie Foundry.

Naprawa nierozwiązanego punktu końcowego projektu Foundry

Objawy: Bezpośrednie polecenie kończy działanie za pomocą polecenia No Foundry project endpoint resolved. Run azd ai project set to set one, or pass --project-endpoint.

Przyczyna: CLI nie mógł znaleźć punktu końcowego projektu Foundry w żadnym z obsługiwanych źródeł: flaga --project-endpoint, aktywne środowisko azd, konfiguracja globalna lub zmienna środowiskowa FOUNDRY_PROJECT_ENDPOINT.

Poprawki:

  • Uruchom polecenie azd ai project set <endpoint>, aby zapisać punkt końcowy w globalnej konfiguracji azd (~/.azd/config.json).
  • Przekaż --project-endpoint (-p) dla każdego polecenia: azd ai connection list -p https://my-proj.services.ai.azure.com/api/projects/my-project.
  • Ustaw FOUNDRY_PROJECT_ENDPOINT w środowisku shella.

Pełną kolejność rozstrzygania oraz informacje o tym, kiedy pierwszeństwo ma każde źródło, znajdziesz w artykule Opis kontekstu projektu azd.

Naprawianie błędów tworzenia istniejących zasobów

Objawy:azd ai connection create, azd ai toolbox create, azd ai routine createlub azd ai skill create kończy się niepowodzeniem z powodu błędu "już istnieje".

Przyczyna: Z założenia create nie obsługuje operacji upsert. Domyślny tryb niepowodzenia uniemożliwia jednemu deweloperowi dyskretne zastąpienie stanu innego w udostępnionym projekcie foundry.

Poprawki:

  • Wybierz inną nazwę i uruchom ponownie.
  • Przekaż parametr --force, jeśli polecenie create to obsługuje, aby zastąpić istniejący zasób za pomocą operacji ARM PUT. Zastąpienie ma charakter destrukcyjny: nadpisuje istniejący zasób w miejscu, a wszelkie rozbieżności wynikające z ręcznych zmian w portalu, metadanych lub danych uwierzytelniających zostaną utracone. Polecenie azd ai toolbox create nie obsługuje --force. Usuń istniejący przybornik lub użyj zamiast tego nowej nazwy.

Poprawianie connection show danych wyjściowych poświadczeń

Symptomy:azd ai connection show <name> Zwraca nazwę połączenia, jego rodzaj, element docelowy i typ uwierzytelniania, ale nie zwraca klucza API ani wartości poświadczeń.

Przyczyna: Domyślnie wartości danych uwierzytelniających nigdy nie są zwracane. Wymagają one jawnej --show-credentials flagi.

Rozwiązanie:

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

Spowoduje to wywołanie interfejsu API płaszczyzny danych i wymaga uprawnień płaszczyzny danych w projekcie Foundry, takich jak Użytkownik usługi Foundry lub odpowiednik. Jeśli masz tylko dostęp do płaszczyzny Reader zarządzania lub Contributor, wywołanie kończy się błędem 403. Poproś właściciela projektu o rolę płaszczyzny danych.

Odczytywanie dzienników agenta

Użyj azd ai agent monitor, aby sprawdzić zachowanie agenta:

# 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>

Typowe wzorce dzienników obejmują:

Wiadomość logu Meaning
Listening on 0.0.0.0:8088 Agent został pomyślnie uruchomiony.
AuthenticationError Problem z poświadczeniami lub mechanizmem RBAC. Sprawdź tożsamość zarządzaną.
ModelNotFound Nazwa wdrożenia modelu nie jest zgodna z azure.yaml.
Ponowne uruchomienie kontenera w zdarzeniach systemu Pętla awarii. Sprawdź błędy kodu lub zwiększ limity zasobów.

Diagnozowanie rutynowych błędów

Rutyny kończą się błędem inaczej niż interaktywne wywołania agent invoke, ponieważ nie ma podmiotu wywołującego, który mógłby ujawnić błąd. Procedura to wyzwalane przez czasomierz, cykliczne, wyzwalane przez zgłoszenie GitHub lub wyzwalane przez zdarzenie niestandardowe uruchomienie agenta. Użyj polecenia azd ai routine run list , aby sprawdzić, co się stało.

Sprawdzanie poprzednich przebiegów

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

Filtruj według niepowodzeń

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

Połącz z --top , aby poszerzyć lub zawęzić okno.

Przechodzenie do szczegółów pojedynczego przebiegu

# 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

Dane wyjściowe w formacie JSON obejmują ładunek danych wejściowych, odpowiedź agenta oraz link głęboki do śledzenia rozproszonego, czyli ten sam ślad, który można zobaczyć podczas wywołania interakcyjnego.

Ręcznie ponownie uruchom rutynę

Jeśli musisz odtworzyć błąd lub przetestować poprawkę, uruchom procedurę na żądanie za pomocą polecenia dispatch:

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

dispatch uruchamia się asynchronicznie i wyświetla identyfikator wysłania. Sprawdź wynik za pomocą polecenia azd ai routine run list <name>.

Naprawianie nieudanego uruchomienia procedury

azd ai routine run list pokazuje uruchomienie za pomocą status: failed. Kliknij link śledzenia, aby zobaczyć źródłowy błąd agenta, taki jak błąd modelu, awaria narzędzia lub przekroczenie limitu czasu. Poprawki po stronie agenta są takie same jak w przypadku błędów interakcyjnych. Zobacz Naprawianie błędów uwierzytelniania i odczytywanie dzienników agenta.

Napraw procedurę, która nigdy się nie uruchamia

Jeśli azd ai routine run list w ogóle nie zwraca żadnych uruchomień, sam wyzwalacz się nie uruchamia:

  1. Sprawdź, czy włączono procedurę: azd ai routine show <name>. Poszukaj enabled: true.
  2. W przypadku wyzwalaczy timer sprawdź, czy --at jest ustawione na przyszłość i nie zostało jeszcze uruchomione.
  3. W przypadku wyzwalaczy recurring sprawdź, czy wyrażenie --cron jest prawidłowe i czy --time-zone jest zgodne z oczekiwaniami.
  4. W przypadku wyzwalaczy github-issue sprawdź, czy element --connection-id wskazuje na sprawne połączenie oraz czy repozytorium GitHub i --issue-event odpowiadają zdarzeniom generowanym przez repozytorium.
  5. W przypadku wyzwalaczy custom sprawdź, czy zakres --provider, --event-name i --parameters odpowiada zdarzeniom publikowanym przez dostawcę.

Uzyskaj więcej pomocy

  • Tryb debugowania — Dodaj --debug do dowolnego polecenia azd, aby uzyskać szczegółowe dane wyjściowe.
  • Azure portal — sprawdź projekt Foundry w portalu Azure pod kątem kondycji zasobów i diagnostyki.
  • Zgłoś usterkę — zgłoś problemy w github.com/Azure/azure-dev/issues.

Treści powiązane

  • Ostatnia aktualizacja o