Lekce 01.8: Nahlížení pod kapotu agenta bezpečně (Inspecting Agent Internals)

⏱️ 3 min čtení • Lekce 01.8

🧠 Mentální model & teoretický rozbor

Většina vývojářů vnímá kódovacího agenta jako černou skříňku: zadáte text do terminálu, na obrazovce se točí indikátor a najednou se změní kód. Jako skuteční softwaroví architekti však musíme rozumět tomu, co přesně teče přes síť:

┌─────────────────────────────────────────────────────────────┐
│ KLIENTSKÝ HARNESS (Antigravity `agy` / Claude Code `claude`)│
└──────────────────────────────┬──────────────────────────────┘
                               │ JSON Payload:
                               │ - system prompt (AGENTS.md, definice tools)
                               │ - messages array (historie, tool_use, tool_result)
                               │ - model ID, temperature, thinking budget
┌──────────────────────────────▼──────────────────────────────┐
│ POSKYTOVATEL MODELU (Google Gemini API / Anthropic API)     │
│ Zpracuje kontext a vrátí buď text, nebo JSON volání nástroje │
└─────────────────────────────────────────────────────────────┘

Co se v datech skrývá:

Systémové instrukce a mantinely: Jak harness kombinuje globální nastavení, soubory AGENTS.md a aktivované dovednosti.
Definice nástrojů (Tool Schemas): Přesná JSON schémata pro ViewFile, EditFile, Bash a Grep.
Výsledky nástrojů (Tool Results): Co přesně harness poslal modelu zpět po spuštění testu nebo kompilátoru.

🏢 Realistický scénář z praxe

Vývojář se diví, proč agent neustále ignoruje pravidlo zapsané v AGENTS.md: „Používej výhradně pnpm.“ Při inspekci debug logu zjistí, že v kořenu projektu ležel starý zapomenutý soubor package-lock.json. Harness při inicializaci automaticky detekoval npm a vložil do systémového promptu pokyn s vyšší prioritou. Jakmile byl starý lockfile smazán, agent začal pravidlo okamžitě respektovat. Bez diagnostiky by vývojář strávil hodiny marným laděním promptu.

💻 Jak bezpečně nahlížet pod kapotu (žádné vypínání TLS!)

[!CAUTION] Bezpečnostní varování: Vyhněte se rizikovým proxy návodům z internetu Některé návody doporučují instalovat síťové proxy (jako mitmproxy) a vypínat kontrolu certifikátů (NODE_TLS_REJECT_UNAUTHORIZED=0). To je obrovské bezpečnostní riziko, které otevírá váš systém man-in-the-middle útokům. Moderní harnessy nabízejí bezpečné, nativní nástroje.

1. Inspekce v Antigravity (`agy`):

Antigravity ukládá kompletní strukturované transkripty každého sezení ve formátu JSONL:

Umístění logů: ~/.gemini/antigravity-cli/brain/<sezeni-id>/.system_generated/logs/transcript.jsonl
Zde vidíte každý tah, přesné znění systémového promptu i návratové kódy nástrojů.

2. Inspekce v Claude Code:

Claude Code má vestavěný přepínač pro podrobný inženýrský výpis:

# Spuštění s podrobným výpisem volání a promptů přímo v terminálu
claude --verbose

# Nebo s detailním laděním
claude --debug

Historie sezení a surové JSON transkripty se bezpečně ukládají do: ~/.claude/projects/

⚠️ Analýza selhání & Anti-patterns

Chyba: Slepá důvěra v textový souhrn agenta

Agent vám v terminálu napíše: „Všechny testy v pořádku prošly.“

Pokud se nepodíváte na skutečný výstup nástroje (nebo nespustíte test sami), můžete přehlédnout, že test runner skončil chybou vitest: command not found a agent chybu dezinterpretoval.
Pravidlo: Vždy sledujte, jaký příkaz agent reálně spustil a jaký byl jeho Exit Code.

🛠️ Inženýrský postup krok za krokem (Playbook)

Aktivujte podrobné logování, pokud agent vykazuje neobvyklé chování nebo ignoruje pravidla.
Zkontrolujte vstupní tokeny: Zjistěte, kolik tokenů zabírají vaše instrukce AGENTS.md.
Zkontrolujte Prompt Caching: Ověřte, že při opakovaných tazích je většina systémového kontextu čtena z mezipaměti.

🧪 Praktické cvičení (Hands-on Lab)

Úkol:

Prozkoumejte velikost kontextu a ověřte poměr cachovaných tokenů.

Kroky:

Spusťte své sezení (agy nebo claude).
Zadejte diagnostický příkaz pro zobrazení stavu (např. /cost nebo /context).
Poznamenejte si poměr mezi Input tokens a Cached input tokens.
Zadejte jednoduchý dotaz a znovu zkontrolujte statistiku – sledujte, jak cachování dramaticky snižuje cenu opakovaného čtení systémových pravidel!