Felsöka en värdbaserad agent

Diagnostisera och åtgärda vanliga problem när du skapar, kör och distribuerar agenter med azd ai agent för Microsoft Foundry. Börja med diagnostikkommandona. Använd sedan de symptombaserade avsnitten för att felsöka autentisering, lokal utveckling, distribution, direkta kommandon, loggar och rutiner.

Förutsättningar

Samla in diagnostisk kontext

Innan du går in på specifika fel använder du dessa kommandon för att samla in kontext:

# 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

Kör azd ai agent doctor för en strukturerad hälsorapport. Mer information finns i Diagnostisera ett projekt med agentläkare.

Diagnostisera svarstid för anrop

Använd felsökningshuvudena för svarstid för att avgöra om en långsam begäran till en värdbaserad agent har tillbringat tid i plattformen, på att etablera infrastrukturen, på att vänta på containern eller på att bearbeta begäran i agenten. Dessa rubriker är diagnostiska signaler, inte serviceavtal eller faktureringsmått.

Aktivera diagnostiken för varje begäran genom att ange x-ms-debug-latency-enabled: true. Om begäran inte innehåller den här rubriken innehåller svaret inte heller rubrikerna x-ms-debug-latency-*.

  1. Lägg till latensrubriken i en begäran till protokollet Responses eller Invocations för en värdhanterad agent. I det här exemplet används protokollet Svar:

    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. Granska svarshuvudena. Alla svarstidsvärden är heltals millisekunder:

    Sidhuvud Meaning
    x-ms-debug-latency-session-start-type Typ av sessionsstart som begäran utlöste: kallstart (cold), varmstart (warm) eller återupptagning från viloläge (resume).
    x-ms-debug-latency-platform-preprocessing-ms Plattformstid för åtkomstkontroll, autentisering, sessionsuppslagning och orkestrering. Det omfattar inte provisionering av mikro-VM:ar eller fördröjningar innan containrar är redo. Tillgänglig för kalla, varma och återupptagna sessionsstarter.
    x-ms-debug-latency-infra-setup-ms Dags att provisionera mikro-VM:n. Utelämnas för varma begäranden.
    x-ms-debug-latency-container-readiness-ms Tiden från att mikro-VM:en skapas tills containern rapporterar att den är klar. Utelämnas för varma begäranden.
    x-ms-debug-latency-container-response-ms Tid från proxyvidarebefordran tills svarshuvuden har fastställts. Innehåller överföring av begäranden, upprättande av anslutning, agenthantering, återförsök och buffring enligt utdatapolicy.
    x-ms-debug-latency-response-begin-ms Total tid från att tjänsten godtas tills svarshuvudena skickas. Det här värdet är inte tiden till den första byten i svarstexten eller den första server-skickade händelsen.

    De fyra tidskomponenterna summerar till x-ms-debug-latency-response-begin-ms. Vid en kall eller återupptagen begäran, om plattformen inte kan registrera alla gränser för provisioneringen, utelämnar den huvudena för infrastruktur och redohet och räknar in den tiden i plattformens förbearbetning.

  3. Använd starttypen för sessionen och den största tidskomponenten för att identifiera den troliga fördröjningskällan:

    Result Tolkning Vad du bör göra
    x-ms-debug-latency-session-start-type är cold eller resume, och x-ms-debug-latency-infra-setup-ms är hög Plattformen lade tid på att provisionera mikro-VM:n. Jämför flera kalla eller återupptagna begäranden. Om fördröjningen kvarstår registrerar du svars-ID, tidsstämpel och svarstidshuvuden för en supportbegäran.
    x-ms-debug-latency-session-start-type är cold eller resume, och x-ms-debug-latency-container-readiness-ms är hög Containern tog lång tid på sig att starta och rapportera att den var klar. Mät initieringsstegen i startloggarna, minska arbetet innan beredskapsslutpunkten blir tillgänglig och förkompilera programkoden där det är möjligt.
    x-ms-debug-latency-platform-preprocessing-ms är hög för alla starttyper för sessioner Fördröjningen inträffade i plattformen innan provisionering av mikro-VM eller innan containern var klar. Skapa en supportbegäran. Inkludera svars-ID, tidsstämpel, sessionsstarttyp och sidhuvuden för svarstid.
    x-ms-debug-latency-container-response-ms, x-ms-debug-latency-first-byte-ms, eller trailerns first_byte_ms är hög Fördröjningen inträffade efter att vidarebefordran via proxy hade påbörjats. Instrumentera begärandehanteraren och inspektera agentloggar, modellanrop, verktygsanrop, återförsök och utdatabuffertning.

Minska containerberedskapstiden

Värdet för containerberedskap innehåller den tid som krävs för att starta processen, läsa in programmet och returnera HTTP 200 från /readiness. Lägg till tidsstämplar i startloggar för att identifiera långsam import, beroendeinläsning, nätverksanrop och annat initieringsarbete.

Tillämpa dessa optimeringar på de långsamma steg som du identifierar:

  • Installera beroenden och kompilera kod när du skapar avbildningen. Kör inte paketinstallation, återställning eller kompilering vid start av container.
  • Använd en flerstegsversion och exkludera byggverktyg, paketcacheminnen, tester och andra utvecklingsfiler från körningsavbildningen.
  • Undvik modellanrop, migreringar, verktygsidentifiering och tillgångsnedladdningar före beredskap. Kör oberoende initialiseringar parallellt som först måste slutföras.
  • Fokusera /readiness på om agenten kan acceptera begäranden. Om du skjuter upp initieringen mäter du den första begäran så att du inte flyttar startfördröjningen till hantering av begäranden.

Installera beroenden i en virtuell miljö som du kopierar till runtime-avbildningen. Kompilera beroenden i möjligaste mån så att en fil i ett tredjepartspaket som inte kan tolkas inte orsakar att builden misslyckas. Kompilera applikationen med strikt kontroll så att syntaxfel gör att bygget misslyckas.

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

Om du rensar PYTHONDONTWRITEBYTECODE för det här byggsteget kan Python skriva bytekoden till avbildningen. Miljövariabeln blockerar bytekodsskrivningar, inte läsningar, så den container som körs kan fortfarande använda de kompilerade filerna.

Referens: compileall – Bytekompilera Python bibliotek

Skapa någon av avbildningarna för x86-64-arkitekturen som krävs av värdbaserade agenter:

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

Här är linux/amd64 en Docker-plattform, inte ett .NET-körnings-ID.

Referens: Krav för värdbaserad agentcontainer

Undersöka agentens och modellens svarstid

Om containerberedskapen är snabb men containersvaret eller första bytetiden är hög fokuserar du din undersökning på begärandesökvägen när vidarebefordran har påbörjats. Kör azd ai agent monitor --follow medan du återskapar begäran och lägg till spårning runt modellanrop, verktygsanrop, externa tjänster, återförsök och svarsserialisering. Mer information finns i Övervaka värdbaserade agentloggar.

För en agent som anropar en stor språkmodell mäter du modellens svarstid separat innan du ändrar distributionen. Jämför tid till första token, tid mellan token, antal genererade token, promptstorlek, distributionsutnyttjande och strypning. Utvärdera sedan modellval, gränser för utdatatoken, strömning och arbetsbelastningsavgränsning. Se Förbättra Azure OpenAI-prestanda.

Om mätningarna visar ett ihållande kapacitetstryck för en förutsägbar arbetsbelastning utvärderar du en etablerad distribution och storleksanpassar den för de observerade indatatoken, utdatatoken och begärandefrekvensen. Se Etablerad dataflödeskapacitet.

Kontrollera tidpunkter för slutförande

På HTTP/2 eller senare kan tjänsten returnera bästa möjliga x-ms-debug-latency-final svarstrailer. Den upprepar värdena för svarsrubriken och kan lägga till följande fält:

Fält Meaning
first_byte_ms Tid från att tjänsten godtas tills den första byten i svarsinnehållet eller en serverutskickad händelse tas emot.
total_last_byte_ms Tid från godkännande av tjänsten tills vidarebefordran av svar har slutförts.

Trailern använder ett versionshanterat, semikolonavgränsat 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-svar inkluderar inte den här trailern. En trailer kan också saknas efter annullering, när klienten kopplas från, vid ett fel mitt i dataflödet eller när en gateway eller SDK inte bevarar trailers. Behandla svarshuvudena som det garanterade diagnostikkontraktet.

Hämta lagrade latensresultat

Tjänsten lagrar insamlade tidsvärden tillsammans med svaret eller anropet. En senare GET-begäran om samma svar eller anrops-ID returnerar den ursprungliga begärans tidsinställningar som svarshuvuden. GET-begäran kräver inte svarstidshuvudet och mäter inte själva GET-begäran.

GET-begäran kan också returnera dessa slutförandevärden som vanliga rubriker:

Sidhuvud Meaning
x-ms-debug-latency-first-byte-ms Tid till den första byten i svarstexten.
x-ms-debug-latency-total-last-byte-ms Tid tills vidarebefordran av svar har slutförts.

Lagringen är så småningom konsekvent, så en GET-begäran omedelbart efter den ursprungliga begäran kanske inte innehåller rubrikerna ännu. För ett asynkront svar eller anrop är endast värdena för plattformskostnader tillgängliga: sessionsstarttyp, plattformsförbearbetning, infrastrukturkonfiguration och containerberedskap. Svarstidshuvuden genereras inte för misslyckade proxysvar eller WebSocket-begäranden (invocations_ws).

Åtgärda autentiseringsfel

Åtgärda AuthenticationError

Symtom: Agenten startar inte lokalt eller returnerar 401/403 när ai-modellen anropas.

Orsaker och korrigeringar:

  • Utgångna autentiseringsuppgifter – Kör azd auth login för att uppdatera din Azure session.
  • Fel prenumeration – Verifiera med azd env get-values | grep AZURE_SUBSCRIPTION_ID och jämför med Foundry-projektets prenumeration.
  • RBAC-roller saknas -- Din identitet behöver Foundry User eller motsvarande åtkomst på Foundry-projektet.

Viktigt

Foundrys RBAC-roller har nyligen namnändrats. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

Din identitet måste också ha användarrollen Cognitive Services OpenAI-användare för att kunna använda modelldistributioner.

Korrigering AuthorizationFailed under etablering

Symtom:azd up eller azd provision misslyckas med ett behörighetsfel.

Fixa: Begär deltagarroll i din Azure-prenumeration. För CI/CD behöver tjänsthuvudnamnet också ha Foundry Owner.

Åtgärda SubscriptionNotRegistered

Symptom: Provisioneringen misslyckas eftersom en obligatorisk resursleverantör inte är registrerad.

Lösningen

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

Åtgärda problem med lokal utveckling

Åtgärda nekad anslutning på port 8088

Symtom:azd ai agent invoke --local misslyckas med att ansluta.

Orsaker och korrigeringar:

  • Agenten körs inte – Starta den med azd ai agent run i en separat terminal.

  • Portkonflikt – En annan process använder port 8088. Stoppa den eller använd en anpassad port:

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

  • Krasch vid start -- Kontrollera terminalen där azd ai agent run körs för felutdata. Vanliga orsaker är saknade beroenden, importfel eller felaktiga startupCommand i azure.yaml.

Åtgärda installationsfel för beroenden

Symtom:azd ai agent run misslyckas under beroendeinstallationen.

Orsaker och korrigeringar:

  • Fel körningsversion – Kontrollera att Python 3.10+ eller .NET 8+ är installerat.
  • Saknas requirements.txt eller .csproj – CLI identifierar automatiskt projekttypen från dessa filer. Kontrollera att de finns i agentkatalogen.
  • Nätverksproblem – Paketregister kan blockeras av din företagsproxy. Kontrollera din pip eller dotnet konfigurationen.

Åtgärda ResourceNotFound eller DeploymentNotFound

Symtom: Agenten startar men misslyckas när den försöker anropa modellen.

Orsaker och korrigeringar:

  • Slutpunkten stämmer inte – Kör azd env get-values och kontrollera att FOUNDRY_PROJECT_ENDPOINT matchar slutpunkten som visas i Foundry-portalen.
  • Matchningsfel för modelldistributionsnamn – Det modelldistributionsnamn som konfigurerats i azure.yaml måste matcha distributionsnamnet i ditt Foundry-projekt. Kontrollera i portalen under Distributioner.
  • Resurser som inte har skapats -- Om du inte har kört azd up ännu finns inte molnresurserna. Kör azd up först och testa sedan lokalt. Den lokala agenten anropar fortfarande molnbaserade modeller.

Åtgärda distributionsproblem

Åtgärda fel vid containerbygge

Symtom:azd up misslyckas under Docker-byggfasen.

Orsaker och korrigeringar:

  • Dockerfile saknas – Kontrollera att agentkatalogen har en Dockerfile. Om du initierade från en mall genereras detta automatiskt.
  • Fel i byggkontext -- Dockerfile måste finnas i katalogen som anges av sökvägen för tjänsten project i azure.yaml.
  • Beroendeinstallation i Docker – Om det inte går att återställa pip/dotnet i containern kontrollerar du att dina requirements.txt eller .csproj har alla beroenden korrekt fästa.

Åtgärda azd up låsningar eller tidsgränsöverskridanden

Symtom: Etablering eller distribution tar ovanligt lång tid.

Orsaker och korrigeringar:

  • Första distributionen – Den första azd up etablerar alla Azure resurser, inklusive Foundry-projekt, ACR, hanterad identitet och modelldistribution, och kan ta 5–10 minuter. Efterföljande distributioner går snabbare.
  • Fjärrbygge – Som standard byggs containeravbildningar via fjärranslutning på ACR. Detta kan vara långsammare men kräver inte Docker lokalt. Om du vill skapa lokalt i stället anger du docker.remoteBuild: false i tjänstkonfigurationen azure.yaml .
  • Regionkapacitet – Vissa regioner kan ha begränsad kapacitet för vissa modell-SKU:er. Prova en annan region om provisioneringen misslyckas upprepade gånger.

Åtgärda en agent som distribuerar men inte svarar

Symtom:azd ai agent invoke överskrider tidsgränsen eller returnerar fel efter en lyckad distribution.

Orsaker och korrigeringar:

  • Hälsokontrollen misslyckades -- Containern måste svara på GET /readiness på port 8088 med statuskoden 200. Kontrollera loggar med azd ai agent monitor --follow.
  • Protokollmatchningsfel – Kontrollera att protokollet som definierats i azure.ai.agent tjänsten i azure.yaml matchar vad koden implementerar. Om azure.yaml det står responses men koden bara hanterar invocations, eller vice versa, misslyckas begäranden.
  • Container kraschar – Kontrollera systemloggarna för omstartshändelser: azd ai agent monitor --type system. Vanliga orsaker är ohanterade undantag och problem med minnesbrist. Öka containerresurserna i azure.yaml om det behövs.

Åtgärda fel med direktkommandon

Dessa fel kommer från direktkommandona azd ai , till exempel azd ai connection, azd ai toolboxoch azd ai routine, när de körs mot ett Foundry-projekt.

Åtgärda att slutpunkten för Foundry-projektet inte kan lösas

Symtom: Ett direktkommando avslutas med No Foundry project endpoint resolved. Run azd ai project set to set one, or pass --project-endpoint.

Orsaka: CLI kunde inte hitta en Foundry-projektslutpunkt i någon av de källor som stöds: --project-endpoint flaggan, den aktiva azd miljön, den globala konfigurationen FOUNDRY_PROJECT_ENDPOINT eller miljövariabeln.

Korrigeringar:

  • Kör azd ai project set <endpoint> för att lagra slutpunkten i din globala azd konfiguration (~/.azd/config.json).
  • Skicka --project-endpoint (-p) på varje kommando: azd ai connection list -p https://my-proj.services.ai.azure.com/api/projects/my-project.
  • Ange FOUNDRY_PROJECT_ENDPOINT i shell-miljön.

Information om den fullständiga prioritetsordningen och när respektive källa har företräde finns i Förstå azd-projektkontext.

Åtgärda fel vid skapande för befintliga resurser

Symptom:azd ai connection create, azd ai toolbox create, azd ai routine create, eller azd ai skill create misslyckas med ett "finns redan"-fel.

Orsak: Enligt designen är create inte upsert. Standardfelläget hindrar en utvecklare från att tyst skriva över en annans tillstånd i ett delat Foundry-projekt.

Korrigeringar:

  • Välj ett annat namn och kör igen.
  • Skicka --force, om kommandot create har stöd för det, för att ersätta den befintliga resursen med en ARM PUT-begäran. Ersättning är destruktiv: den skriver över den befintliga resursen direkt, och alla ändringar som gjorts manuellt i portalen, metadata eller autentiseringsuppgifter går förlorade. Kommandot azd ai toolbox create stöder inte --force. Ta bort den befintliga verktygslådan eller använd ett nytt namn i stället.

Åtgärda connection show utmatningen av autentiseringsuppgifter

Symtom:azd ai connection show <name> returnerar anslutningens namn, typ, mål och autentiseringstyp, men inget API-nyckel- eller autentiseringsvärde.

Orsak: Autentiseringsvärden returneras aldrig som standard. De kräver den explicita --show-credentials flaggan.

Lösningen

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

Detta anropar data plane-API:et och kräver behörigheter för dataplanet i Foundry-projektet, till exempel Foundry User eller motsvarande. Om du bara har åtkomst till hanteringsplanet Reader eller Contributor, misslyckas anropet med ett 403-fel. Be projektägaren om dataplansrollen.

Läs agentloggar

Använd azd ai agent monitor för att kontrollera agentbeteendet:

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

Vanliga loggmönster är:

Loggmeddelande Meaning
Listening on 0.0.0.0:8088 Agenten har startats utan problem.
AuthenticationError Problem med autentiseringsuppgifter eller RBAC. Kontrollera den hanterade identiteten.
ModelNotFound Namnet på modelldistribution stämmer inte överens med azure.yaml.
Omstart av container i systemhändelser Kraschloop. Kontrollera kodfel eller öka resursgränserna.

Diagnostisera rutinfel

Rutiner misslyckas annorlunda än interaktiva agent invoke anrop eftersom det inte finns någon anropare som visar felet. En rutin är en körning av en agent som utlöses av en timer, återkommer, utlöses av ett GitHub-ärende eller utlöses av en anpassad händelse. Använd azd ai routine run list för att kontrollera vad som hände.

Granska tidigare körningar

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

Filtrera efter fel

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

Kombinera med --top för att bredda eller begränsa fönstret.

Öka detaljnivån i en enda körning

# 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

JSON-utdata innehåller indatanyttolasten, agentens svar och en djup länk till den distribuerade spårningen, samma spårning som du skulle se för ett interaktivt anrop.

Utlös en rutin manuellt igen

Om du behöver återskapa ett fel eller testa en korrigering kan du utlösa rutinen på begäran med dispatch:

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

dispatch körs asynkront och skriver ut ett sändnings-ID. Kontrollera resultatet med azd ai routine run list <name>.

Åtgärda en misslyckad rutinkörning

azd ai routine run list visar körningen med status: failed. Följ spårningslänken för att se det underliggande agentfelet, till exempel modellfel, verktygsfel eller tidsgräns. Korrigeringarna på agentsidan är desamma som för interaktiva fel. Se Åtgärda autentiseringsfel och Läsa agentloggar.

Åtgärda en rutin som aldrig utlöses

Om azd ai routine run list inte returnerar några körningar alls utlöses inte själva utlösaren:

  1. Kontrollera att rutinen är aktiverad: azd ai routine show <name>. Leta efter enabled: true.
  2. För timer-utlösare kontrollerar du att --at ligger i framtiden och inte redan har utlösts.
  3. För recurring utlösare kontrollerar du att --cron uttrycket är giltigt och att --time-zone det är det du förväntade dig.
  4. För utlösare av typen github-issue, kontrollera att --connection-id resulterar i en fungerande anslutning och att GitHub-lagringsplatsen och --issue-event matchar de händelser som lagringsplatsen skickar.
  5. För utlösare av typen custom kontrollerar du att omfången --provider, --event-name och --parameters motsvarar de händelser som leverantören publicerar.

Få mer hjälp

  • Felsökningsläge – Lägg till --debug i alla azd kommandon för utförliga utdata.
  • Azure portal – Kontrollera foundry-projektet i Azure-portalen för resurshälsa och diagnostik.
  • Skapa en bugg – Rapportera problem med github.com/Azure/azure-dev/issues.

Relaterat innehåll

  • Last updated on