Lekce 02.1: Modely, harnessy, agenti a prostředí (Models, Harnesses, Agents, Environments)

⏱️ 4 min čtení • Lekce 02.1

🧠 Mentální model & teoretický rozbor

Většina nedorozumění při vývoji s AI pramení z toho, že lidé zaměňují model za agenta a harness za editor. Pokud chceme kódovat spolehlivě, musíme striktně rozlišovat čtyři vrstvy:

┌─────────────────────────────────────────────────────────────────────────┐
│ 1. MODEL (Neuronová síť na serveru)                                     │
│    Příklad: Google Gemini 2.5/3.8 Pro, Claude 3.7 Sonnet.               │
│    Co to je: Pravděpodobnostní funkce f(text) -> text. Nemá přístup k   │
│    disku, síti ani terminálu. Nemá žádnou interní paměť mezi voláními.  │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ JSON API (HTTP POST)
┌────────────────────────────────────▼────────────────────────────────────┐
│ 2. HARNESS (Běhové prostředí a kódovací postroj)                         │
│    Příklad: Google Antigravity CLI (`agy`), Claude Code (`claude`).     │
│    Co to je: Běžný program na vašem PC. Odesílá prompty, čte disky,      │
│    spouští bashové příkazy a překládá výstupy zpět do JSONu pro model. │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│ 3. AGENT (Autonomní řídicí smyčka)                                      │
│    Co to je: Architektura promptů a smyčka: Myšlenka ➔ Nástroj ➔       │
│    Pozorování výsledku ➔ Další myšlenka. Řídí se souborem AGENTS.md.    │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │
┌────────────────────────────────────▼────────────────────────────────────┐
│ 4. PROSTŘEDÍ (Environment)                                              │
│    Váš operační systém: Souborový systém, Git repozitář, běžící procesy,│
│    databáze a síťová spojení.                                           │
└─────────────────────────────────────────────────────────────────────────┘

Klíčový poznatek: Model sám o sobě nikdy nepřepíše soubor. Model pouze vrátí textový řetězec: {"name": "EditFile", "parameters": {"path": "src/index.ts", "content": "..."}}. Teprve harness tento JSON zachytí a fyzicky provede fs.writeFileSync() na vašem disku.

---

🏢 Realistický scénář z praxe

Představte si situaci, kdy model navrhne úpravu souboru, ale harness selže, protože soubor je zamčený jiným procesem nebo chybí oprávnění k zápisu.

• Nezkušený vývojář se začne hádat s modelem: „Proč jsi ten soubor neuložil? Jsi hloupý!“
• Inženýr okamžitě chápe: Model úpravu navrhl správně, ale selhal harness nebo narazil na mantinel prostředí (např. Unix oprávnění chmod 444). Problém řeší v terminálu, nikoliv v chatu.

---

💻 Konkrétní ukázky kódu & promptů

Ukázka: Jak vypadá zjednodušená smyčka kódovacího harnessu v TypeScriptu:

// mini-harness.ts - Principiální ukázka fungování harnessu
import Anthropic from '@anthropic-ai/sdk';
import fs from 'fs';
import { execSync } from 'child_process';

const anthropic = new Anthropic();
const messages: any[] = [{ role: 'user', content: 'Zkontroluj stav repozitáře a oprav linter.' }];

async function agentLoop() {
  while (true) {
    const response = await anthropic.messages.create({
      model: 'claude-3-7-sonnet-20250219',
      max_tokens: 4096,
      tools: [
        {
          name: 'bash',
          description: 'Spustí bash příkaz',
          input_schema: { type: 'object', properties: { cmd: { type: 'string' } }, required: ['cmd'] }
        }
      ],
      messages
    });

    // Uložíme odpověď asistenta do historie
    messages.push({ role: 'assistant', content: response.content });

    const toolUse = response.content.find((block) => block.type === 'tool_use');
    if (!toolUse) {
      console.log('Agent dokončil úkol:', response.content);
      break;
    }

    // HARNESS VYKONÁVÁ NÁSTROJ V PROSTŘEDÍ
    if (toolUse.name === 'bash') {
      console.log(`[HARNESS] Spouštím v bashi: ${toolUse.input.cmd}`);
      let stdout = '';
      try {
        stdout = execSync(toolUse.input.cmd, { encoding: 'utf-8' });
      } catch (err: any) {
        stdout = `ERROR: ${err.message}`;
      }

      // Výsledek vracíme modelu v dalším tahu
      messages.push({
        role: 'user',
        content: [{ type: 'tool_result', tool_use_id: toolUse.id, content: stdout }]
      });
    }
  }
}

---

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

Anti-pattern: Zaměňování schopností modelu se schopnostmi harnessu

Někteří vývojáři píší do CLAUDE.md: „Pamatuj si, že včera jsme dělali refaktoring user modulu.“

• Proč to selže: Model nemá žádnou dlouhodobou paměť. Pokud harness nenačte předchozí historii nebo specializovaný paměťový soubor (MEMORY.md), model o včerejšku neví zhola nic.
• Řešení: Všechny kontextové informace musí být explicitně uloženy v souborech repozitáře (Gitu, dokumentaci, testech).

---

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

1. Identifikujte vrstvu problému:
   • Pokud model generuje syntaktické nesmysly ➔ problém je v modelu nebo nedostatečném zadání.
   • Pokud se nespustil test ➔ problém je v harnessu (zaseknutý proces, špatný tool call).
   • Pokud chybí soubor nebo práva ➔ problém je v prostředí.
2. Udržujte prostředí v čistotě: Harness má přístup přesně k tomu, co je v prostředí. Smažte nepoužívané soubory a lockněte závislosti.

---

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

Úkol:

Ověřte si oddělení modelu a prostředí v Antigravity CLI (agy) nebo Claude Code.

Kroky:

1. Spusťte agy (nebo claude).
2. Zadejte příkaz: „Zobraz aktuální čas a datum na tomto počítači.“
3. Sledujte v terminálu, jak model vygeneruje volání nástroje Bash s příkazem date, harness ho spustí v prostředí vašeho OS a model vám teprve poté odpoví.
4. Zamyslete se: Proč model nemohl odpovědět rovnou ze svých interních vah?

---