Een falende test debuggen met een agent

Deze gids laat zien hoe je een agent een debugger laat gebruiken voor een fout die printinstructies niet verklaren.

De tool debug stuurt een echte Debug Adapter Protocol-sessie aan. Een gestopt frame beantwoordt elke vraag over dat moment in één keer — elke local, elke aanroeper, en een expressie die in de eigen scope van het frame wordt geëvalueerd — waar een printinstructie alleen de vraag beantwoordt die je vóór het draaien bedacht had.

Voordat je begint

De tool blijft aan het oppervlak, zodat de agent kan vragen waarom niets bruikbaar is in plaats van te gokken. Een adapter kan pas echt starten wanneer aan beide voorwaarden is voldaan:

• een projectmarker in de checkout, en
• de binary van de adapter die te vinden is.

Vraag de agent om dit te controleren:

debug(op: "adapters")

Hij antwoordt met wat hij heeft gevonden, of legt uit dat een adapter beide helften nodig heeft.

Taal	Adapter	Marker	Installatie
Dart / Flutter	dart debug_adapter	pubspec.yaml	Zit bij de SDK — niets te doen
Python	python3 -m debugpy.adapter	pyproject.toml, setup.py, requirements.txt	pip install debugpy
Rust / C / C++	lldb-dap	Cargo.toml, CMakeLists.txt	Zit bij LLVM
Go	dlv dap	go.mod	go install github.com/go-delve/delve/cmd/dlv@latest

Python kiest de interpreter van het project

debugpy wordt gezocht in .venv/bin of venv/bin voordat $PATH wordt geraadpleegd. Een python uit $PATH is een andere omgeving, en verbinden vanuit de verkeerde omgeving mislukt op een manier die leest als kapotte code in plaats van als de verkeerde interpreter.

Eerst het breakpoint, dan starten

De volgorde is belangrijk en de tool dwingt die af: breakpoints mogen voordat er een sessie bestaat worden ingesteld, omdat het protocol die volgorde vereist.

Vraag de agent zoiets als:

De functie compute in bin/main.dart geeft de verkeerde waarde terug. Zet een breakpoint op de regel die product toewijst, start het onder de debugger en vertel me wat a en b werkelijk zijn.

Hij voert ongeveer dit uit:

debug(op: "breakpoints", file: "bin/main.dart", lines: [7])
debug(op: "launch", program: "bin/main.dart")

De start meldt waar hij is gestopt:

Launched bin/main.dart on dart (session dart-1). Stopped: breakpoint. Use `stack` to see where.

Als hij in plaats daarvan meldt dat het programma is afgesloten

Het breakpoint is niet gebonden. Een regel die leeg is, commentaar is, of niet in de build is gecompileerd, kan er geen bevatten. Als je breakpoints op een levende sessie aanroept, meldt die hoeveel van de ingestelde breakpoints daadwerkelijk zijn geplaatst.

Het frame lezen

debug(op: "stack")
→ #1 compute (bin/main.dart:7:3)
  #2 main (bin/main.dart:2:18)

Ga er dan in:

debug(op: "scopes", frame_id: 1)
→ Locals (reference 12)

debug(op: "variables", reference: 12)
→ a (int) = 6
  b (int) = 7
  product (int) = 42

Een object met onderliggende waarden meldt [expand: reference N] — maar alleen wanneer er werkelijk iets achter zit, zodat een uitklapping die de agent niet kan gebruiken nooit wordt aangeboden.

Voor alles wat niet als local zichtbaar is:

debug(op: "evaluate", expression: "config.timeout.inSeconds", frame_id: 1)

Door de code stappen

Wat je wilt	Op
Doorlopen naar het volgende stopmoment	continue
Volgende regel, hetzelfde frame	step_over
De aanroep in	step_in
Uit naar de aanroeper	step_out
Een draaiend programma stoppen	pause

Verbinden met iets dat al draait

Voor een vastgelopen proces in plaats van een proces dat je zelf start:

debug(op: "attach", port: 5858)

Afronden

debug(op: "terminate")

Beëindig de sessie altijd. Een debugadapter bezit een gestopt proces dat vasthoudt wat dat proces ook vasthoudt — een poort, een lock, een databaseverbinding.

De sessie kan niet aan je ontsnappen

Elke sessie heeft een harde TTL die hij niet kan verlengen, er is er precies één per gesprek, en alles wordt afgebroken wanneer de server stopt. Een tweede launch wordt geweigerd in plaats van de eerste te vervangen: een agent die er een start zonder de andere te beëindigen, is de eerste vrijwel zeker kwijtgeraakt.

Begrensde uitvoer

Een variables-uitklapping op een diepe objectgraaf is van nature onbegrensd — één Flutter-widget reikt tot de hele elementenboom. Het aantal onderliggende waarden per scope is gemaximeerd op 50, waarden op 400 tekens en stackframes op 30. Een toolresultaat dat het contextvenster vult, is een tool die de run beëindigt die hij aan het helpen was.

Gerelateerd

• Code-intelligentie — waarom een debugger, een compiler en een matcher verschillende vragen beantwoorden
• Ingebouwde agenttools — elke debug-bewerking en elk argument
• Een agent diagnosticeren — wanneer het probleem de agent is, niet de code