Väčšina tutoriálov o AI agentoch začína konfiguráciou nástrojov. Pripoj tento MCP server. Zaregistruj tú skill. Nastav tieto prompty.
Potom sa používatelia čudujú, prečo ich agent „Marketingový riaditeľ” jeden deň posiela e-maily cez SendGrid a na druhý deň cez Mailgun. Alebo prečo „SEO analytik” niekedy dopytuje Google Analytics, niekedy Search Console a niekedy si metriky jednoducho vymýšľa.
Agenti sú teoreticky schopní. Majú e-mailové nástroje. Majú prístup k analytike. Ale spoľahlivo nefungujú.
Toto sme sa naučili pri budovaní 14 AI Characterov pre TeamDay: problém nie sú nástroje. Problém je metodológia.
Pasca abstrakcií
Ekosystém AI agentov miluje taxonómie. Nástroje vs. MCP servery vs. skills vs. pluginy vs. prompty. Vývojári trávia hodiny debatami: má byť e-mail MCP nástroj alebo skill s bash skriptom?
Z pohľadu business používateľa sú tieto rozdiely bezvýznamné.
Keď niekto požiada svojho Marketingového riaditeľa, aby „odoslal týždenný update”, nezaujíma ho, či e-mail odíde cez:
- MCP nástroj volajúci Resend API
- Skill spúšťajúcu bash curl príkaz
- TypeScript skript s prihlasovacími údajmi z env premenných
- Priame SMTP cez sendmail
Zaujíma ich, či e-mail odíde. Správne. Vždy.
Odstráň abstrakcie a zostanú ti presne dve primitíva:
1. Spustiteľné funkcie — Kód, ktorý sa spustí a vráti výsledok (nástroje, MCP nástroje, bash príkazy, skripty)
2. Text promptu — Inštrukcie, ktoré AI číta a dodržiava (systémové prompty, skills, súbory CLAUDE.md)
Všetko ostatné je len balenie a organizačná štruktúra okolo týchto dvoch primitív.
Pasca abstrakcií nastane, keď optimalizuješ pre taxonómiu (výber medzi typmi nástrojov) namiesto pre spoľahlivosť (funguje to skutočne?).
Princíp funkčného príkladu
Tu je skutočná jednotka schopnosti AI agenta:
Funkčný príklad s prihlasovacími údajmi.
Nie registrácia nástroja. Nie konfigurácia MCP servera. Nie popis skilly.
Funkčný príklad vyzerá takto:
# Odoslať e-mail cez Resend
curl -X POST https://api.resend.com/emails \
-H "Authorization: Bearer $RESEND_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from": "[email protected]",
"to": "[email protected]",
"subject": "Týždenný update",
"html": "<p>Obsah tu</p>"
}'
# Očakávaná odpoveď:
# {"id": "abc-123", "status": "sent"}
# Prihlasovacie údaje: RESEND_API_KEY v .env
# Naposledy otestované: 2026-02-10
# Vlastník: Marketingový tímBez funkčného príkladu si Claude vyberá náhodne z 1000 možností. S funkčným príkladom zakaždým sleduje osvedčený postup.
Rozdiel medzi „teoreticky vie posielať e-maily” a „spoľahlivo posiela e-maily cez Resend s našimi prihlasovacími údajmi” je otestovaný, zdokumentovaný funkčný príklad.
Model receptov
Recept je to, čomu hovoríme otestovaný, osvedčený funkčný príklad pre konkrétny úlohu.
Náš Character Marketingový riaditeľ má tieto recepty:
- Odoslať e-mail cez Resend (otestované, prihlasovacie údaje v env)
- Dopytovať Search Console API (otestované, OAuth nakonfigurované)
- Analyzovať kľúčové slová cez Ahrefs (otestované, API kľúč v env)
- Získať dáta z Google Analytics (otestované, ID vlastnosti zdokumentované)
Každý recept obsahuje:
- Kedy ho použiť — „Použiť na odosielanie transakčných e-mailov”
- Odkaz na prihlasovacie údaje — „API kľúč: RESEND_API_KEY (v .env)”
- Funkčný príklad — Skutočný curl príkaz alebo ukážka kódu, ktorá funguje
- Očakávaná odpoveď — Ako vyzerá úspech
- Naposledy otestované — Dátum, kedy sme overili, že to skutočne funguje
Recepty nie sú abstraktné definície nástrojov. Sú to konkrétne, otestované postupy, o ktorých vieme, že fungujú, pretože sme ich spustili.
Recepty sú atomické stavebné bloky. Characteri sú kompozície.
Bottom-up návrh Characterov
Tu je metodológia, ktorá skutočne funguje:
Krok 1: Kto je tento Character?
Nie abstraktné schopnosti. Konkrétna rola a účel.
Zle: „AI asistent s marketingovými schopnosťami”
Dobre: „Marketingový riaditeľ, ktorý posiela týždenné prehľady výkonu stakeholderom”
Čím jasnejšia rola, tým jednoduchší návrh.
Krok 2: Aké úlohy táto rola skutočne vykonáva?
Nie čo by teoreticky mohol robiť. Čo doslova robí v utorok ráno.
Pre Marketingového riaditeľa:
- Kontrola výkonu kampaní (pondelky o 9:00)
- Prehľad trendov organickej návštevnosti (denne)
- Odoslanie týždenného updatu stakeholderom (piatky o 16:00)
- Analýza kľúčových slov (na požiadanie)
Všimni si, že ide o úlohy, nie o nástroje. „Kontrola výkonu kampaní” je práca, ktorá sa má urobiť. Či na to použije Google Ads API alebo Search Console alebo oboje, je len implementačný detail.
Krok 3: Ako skutoční ľudia tieto úlohy robia?
Tu sa konkrétne zaoberáme tech stackom.
Pre „kontrolu výkonu kampaní”:
- Skutočný človek sa prihlási do Google Analytics
- Zobrazí posledných 7 dní návštevnosti
- Porovná s predchádzajúcim obdobím
- Zaznamená výrazné zmeny
Technický preklad:
- Dopyt na Google Analytics API
- ID vlastnosti: 478766521
- Metrika: sessions, pageviews, bounce rate
- Časové rozmedzie: posledných 7 dní vs. predchádzajúcich 7 dní
- Potrebné OAuth prihlasovacie údaje
Teraz vieš, aký recept vytvoriť.
Krok 4: Podporuje náš tech stack toto riešenie?
Vieme pristupovať k týmto API z nášho runtime prostredia?
Skontroluj:
- Máme prihlasovacie údaje? (Skontroluj .env, skontroluj nastavenie OAuth)
- Vieme volať API zo sandboxu? (Otestuj curl príkaz)
- Sú nainštalované potrebné balíčky? (Skontroluj Docker image alebo nainštaluj za behu)
Ak je odpoveď nie, buď:
- Pridaj schopnosť do svojho runtime prostredia (nainštaluj balíčky, nakonfiguruj OAuth)
- Použi iný prístup (MCP server pri ťažkých závislostiach)
- Uprav rolu Charactera (priznej obmedzenie)
Runtime realita obmedzuje, čo je možné. Ak psql nie je nainštalovaný v sandboxe, žiadne množstvo prompt engineeringu nedá Claudovi prístup k databáze.
Krok 5: Napíš a otestuj recepty
To je kritický krok, ktorý väčšina ľudí preskočí.
Nepíšte:
Agent môže dopytovať Google Analytics pomocou API.Napíšte:
# Dopyt na Google Analytics — Návštevnosť za posledných 7 dní
curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
"https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
-d '{
"dateRanges": [{"startDate": "7daysAgo", "endDate": "today"}],
"metrics": [{"name": "sessions"}]
}'
# Naposledy otestované: 2026-02-10 (fungovalo)
# Vlastník: Marketingový tím
# Prihlasovacie údaje: GA_ACCESS_TOKEN z OAuth (vyprší za 1 hod)Potom to skutočne spusti. Over, že to funguje. Oprav, čo nefunguje. Zdokumentuj funkčnú verziu.
Recept je skutočný až vtedy, keď je otestovaný.
Krok 6: Zostav Character
Teraz máš:
- Jasnú rolu (Marketingový riaditeľ)
- Konkrétne úlohy (týždenné updaty, analýza návštevnosti)
- Otestované recepty (Search Console, Analytics, Resend)
Character je kompozícia:
# Character: Marketingový riaditeľ
## Rola
Si Marketingový riaditeľ TeamDay. Monitoruješ výkon,
analyzuješ trendy a komunikuješ poznatky stakeholderom.
## Kľúčové zodpovednosti
- Odosielať týždenné prehľady výkonu (piatky o 16:00)
- Denne monitorovať organickú návštevnosť
- Na požiadanie analyzovať kľúčové slová
## Dostupné recepty
### Odoslať e-mail cez Resend
Kedy: Odosielanie updateov stakeholderom
Recept: /recipes/send-email-resend.md
### Dopytovať Search Console
Kedy: Analýza organickej návštevnosti alebo kľúčových slov
Recept: /recipes/search-console-query.md
### Získať dáta z Google Analytics
Kedy: Kontrola celkových trendov návštevnosti
Recept: /recipes/google-analytics-query.md
## Komunikačný štýl
- Priamočiary, bez firemného žargónu
- Začínaj číslami („+15 % návštevnosť vs. minulý týždeň")
- Vysvetľuj, čo sa zmenilo a prečo na tom záležíCharacter odkazuje na recepty. Recepty obsahujú funkčné príklady.
Takto sa budujú Characteri, ktorí skutočne fungujú.
Opakované využitie vďaka prekryvu tech stacku
Tu sa model receptov vypláca.
Marketingový riaditeľ potrebuje prístup k Search Console. SEO analytik potrebuje prístup k Search Console. Rovnaký recept.
Obchodný zástupca potrebuje odosielať e-maily. Marketingový riaditeľ potrebuje odosielať e-maily. Rovnaký recept.
Recepty prirodzene tvoria knižnicu:
/recipes/
├── send-email-resend.md
├── search-console-query.md
├── google-analytics-query.md
├── ahrefs-keyword-analysis.md
├── postgres-query.md
└── notion-page-create.mdKaždý nový Character pridá možno 1–2 nové recepty. Väčšina sa opakovane využíva.
Ale to funguje len vtedy, keď sú recepty otestované funkčné príklady. Ak sú to abstraktné definície nástrojov, opakované využitie nezáleží, pretože rovnako spoľahlivo nefungujú.
Brána kvality
Schopnosti Charactera sú len tak reálne, ako sú reálne jeho otestované recepty.
Otázky, ktoré si klásť:
Nie: „Má tento Character nakonfigurovaný e-mail?”
Opýtaj sa: „Overili sme, že e-mailový recept skutočne odošle e-mail?”
Nie: „Má tento Character prístup k našej databáze?”
Opýtaj sa: „Otestovali sme recept pre databázový dopyt s reálnymi prihlasovacími údajmi?”
Rozdiel medzi Charactermi, ktorí sú fasádami, a Charactermi, ktorí dodávajú výsledky, sú otestované recepty.
Toto sme sa naučili z vlastnej skúsenosti. Vybudovali sme Characterov pre stránku /team na našom marketingovom webe. Vyzerali skvele. 14 AI zamestnancov, ktorých si môžeš najať. Profesionálne popisy. Pôsobivé schopnosti.
Potom sme ich skúsili použiť pre reálnu prácu. Väčšina nefungovala end-to-end. Chýbajúce závislosti. Neotestované recepty. Abstraktné schopnosti bez funkčných príkladov.
Brána kvality: Ak sme to neotestovali, nepošleme to.
Runtime realita: Čo je skutočne možné
Prostredie sandboxu obmedzuje, čo je možné. Pochopenie týchto obmedzení formuje lepší návrh Characterov.
Čo funguje všade
HTTP API cez curl:
curl -H "Authorization: Bearer $API_KEY" https://api.example.com/endpointKaždý sandbox má curl. Ak sa vieš pripojiť k API cez HTTP, vieš ho integrovať.
Bash skripty:
#!/bin/bash
# Akákoľvek logika, ktorú vieš skriptovať, funguje v sandboxeBežné CLI nástroje:
git, grep, sed, awk, jq, node, pythonČo vyžaduje nastavenie
Databázoví klienti:
- Potreba nainštalovať
psqlalebomysql - Možnosť 1: Preinštalovať v Docker image
- Možnosť 2: HTTP API wrapper (pg-gateway)
- Možnosť 3: MCP server pre zložité dopytovanie
Ťažké balíčky (Puppeteer, Playwright):
- Veľké stromy závislostí
- Binárne závislosti (Chrome)
- Možnosť 1: Preinštalovať v base image (ak sa hojne používa)
- Možnosť 2: MCP server (izolovaný, spravovaný samostatne)
OAuth toky:
- Interaktívna autentifikácia
- Logika obnovy tokenov
- Možnosť 1: Predkonfigurovať tokeny (env premenné)
- Možnosť 2: MCP server spracováva auth
Praktický rozhodovací strom
- Vieme to cez curl? → Napíš recept, otestuj, hotovo
- Potrebuješ balíček < 50 MB? → Nainštaluj do Docker image
- Potrebuješ ťažké závislosti? → MCP server (posledná možnosť)
- Potrebuješ interaktívny auth? → MCP server alebo predkonfigurované tokeny
Čím jednoduchšie runtime požiadavky, tým spoľahlivejší Character.
Rozdiel oproti tomu, ako väčšina ľudí stavia
Top-down (bežný prístup):
- Vyber framework pre AI agentov
- Nakonfiguruj MCP servery
- Pridaj skills a nástroje
- Napíš systémový prompt
- Dúfaj, že to funguje
Problémy:
- Nástroje nakonfigurované, ale neotestované
- Žiadne funkčné príklady, len abstraktné schopnosti
- Character môže teoreticky robiť čokoľvek, spoľahlivo nerobí nič
- Prvé reálne použitie odhalí, že to v skutočnosti nefunguje
Bottom-up (náš prístup):
- Definuj konkrétnu rolu a úlohy
- Namapuj úlohy na reálne ľudské pracovné postupy
- Otestuj a over každý pracovný postup (napíš recepty)
- Zostav Character z otestovaných receptov
- Brána kvality: každá schopnosť je overená
Výsledok:
- Každý recept je otestovaný a o jeho funkčnosti vieme
- Schopnosti Charactera zodpovedajú otestovanej realite
- Prvé použitie funguje, pretože recepty boli overené
- Keď sa niečo pokazí, vieme, ktorý recept opraviť
Metodológia obracia proces: začíname od overených pracovných postupov, skladáme nahor k Characterom — nie konfigurujeme nástroje zhora a dúfame.
Reálny príklad: Marketingový riaditeľ
Ukážme si skutočný proces návrhu pre jedného z našich Characterov.
Krok 1: Definícia roly
Kto: Marketingový riaditeľ TeamDay Účel: Monitorovanie marketingového výkonu a komunikácia poznatkov
Krok 2: Skutočné úlohy
Po pozorovaní reálnej marketingovej práce:
- Kontrola Google Analytics pre trendy návštevnosti (denne)
- Monitorovanie Search Console pre organické kľúčové slová (týždenne)
- Odosielanie prehľadov výkonu stakeholderom (týždenne)
- Analýza konkrétnych kampaní na požiadanie
Krok 3: Reálny ľudský pracovný postup
Pre „odoslanie týždenného updatu”:
- Človek sa prihlási do Google Analytics
- Zobrazí posledných 7 dní: sessions, pageviews, top stránky
- Porovná s predchádzajúcim týždňom
- Zaznamená výrazné zmeny
- Skontroluje Search Console pre top dopytov
- Zostaví e-mail s výsledkami
- Odošle cez Gmail
Krok 4: Kontrola tech stacku
Google Analytics:
- ✅ Máme prístup k API
- ✅ ID vlastnosti: 478766521
- ✅ OAuth nakonfigurované
- ✅ Vieme dopytovať cez curl
Search Console:
- ✅ Máme prístup k API
- ✅ Web: teamday.ai
- ✅ OAuth nakonfigurované
- ✅ Vieme dopytovať cez curl
E-mail:
- ✅ Používame Resend (nie Gmail)
- ✅ API kľúč v env: RESEND_API_KEY
- ✅ Vieme odosielať cez curl
Krok 5: Napíš recepty
Recept 1: Google Analytics — Posledných 7 dní
#!/bin/bash
# Získaj návštevnosť za posledných 7 dní z Google Analytics
curl -H "Authorization: Bearer $GA_ACCESS_TOKEN" \
"https://analyticsdata.googleapis.com/v1beta/properties/478766521:runReport" \
-d '{
"dateRanges": [
{"startDate": "7daysAgo", "endDate": "today"},
{"startDate": "14daysAgo", "endDate": "8daysAgo"}
],
"metrics": [
{"name": "sessions"},
{"name": "totalUsers"},
{"name": "screenPageViews"}
],
"dimensions": [{"name": "pagePath"}]
}'
# Výsledok testu (2026-02-10):
# {
# "rows": [
# {"dimensionValues": [{"value": "/"}],
# "metricValues": [{"value": "1243"}, {"value": "892"}, ...]}
# ]
# }
# Prihlasovacie údaje: GA_ACCESS_TOKEN (OAuth, platnosť 1 hod)Otestované: ✅ Funguje Naposledy overené: 2026-02-10
Recept 2: Odoslať e-mail cez Resend
#!/bin/bash
# Odoslať e-mail cez Resend API
TO="$1"
SUBJECT="$2"
BODY="$3"
curl -X POST https://api.resend.com/emails \
-H "Authorization: Bearer $RESEND_API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"from\": \"[email protected]\",
\"to\": \"$TO\",
\"subject\": \"$SUBJECT\",
\"html\": \"$BODY\"
}"
# Výsledok testu (2026-02-10):
# {"id": "abc-123", "status": "sent"}
# Prihlasovacie údaje: RESEND_API_KEY v .envOtestované: ✅ Funguje Naposledy overené: 2026-02-10
Krok 6: Zostav Character
# Marketingový riaditeľ
Si Marketingový riaditeľ TeamDay. Monitoruješ výkon
a komunikuješ poznatky.
## Úloha: Týždenný update
Každý piatok o 16:00:
1. Dopytuj Google Analytics (posledných 7 dní vs. predchádzajúce)
Recept: /recipes/google-analytics-7day.sh
2. Dopytuj Search Console (top organické dopyty)
Recept: /recipes/search-console-top-queries.sh
3. Zostav e-mail:
- Predmet: „TeamDay Marketing Update — Týždeň od [dátum]"
- Formát:
**Návštevnosť:** [sessions] ([+/-]% vs. minulý týždeň)
**Top stránky:** [zoznam top 3]
**Top dopyty:** [zoznam top 3]
**Výrazné zmeny:** [čokoľvek > 20% zmena]
4. Odošli cez Resend
Recept: /recipes/send-email-resend.sh
Komu: jozo at teamday.aiVýsledok: Character, ktorý spoľahlivo odosieľa týždenné updaty, pretože každý krok je otestovaný recept.
Čo sme sa naučili z vlastnej skúsenosti
1. „Otestované” znamená skutočne otestované
Dokumentovali sme recepty. Vyzerali dobre. Vypustili sme Characterov.
Potom sme ich skúsili použiť. Polovica receptov nikdy nebola spustená. API endpointy sa zmenili. Prihlasovacie údaje boli zlé. ID vlastností boli zastarané.
Riešenie: Otestuj každý recept. Skutočne ho spusti. Over odpoveď. Aktualizuj, keď sa API zmení.
2. Recepty zastarávajú
API sa menia. Prihlasovacie údaje expirujú. Služby sú zrušené.
Riešenie: Datuj každý recept. Keď Character zlyhá, skontroluj dátumy receptov. Otestuj znova a aktualizuj.
3. Runtime medzery sú reálne
Navrhli sme Character SQL analytika, ktorý dopytuje našu databázu. Potom sme zistili, že psql nie je nainštalovaný v sandboxe.
Riešenie: Otestuj runtime schopnosti pred návrhom Characterov. Ak psql tam nie je, buď ho nainštaluj alebo použi HTTP API wrapper.
4. Kompozícia poráža konfiguráciu
Strávili sme týždne konfiguráciou MCP serverov pre rôzne schopnosti. Zložité nastavenie. Veľa pohyblivých častí.
Potom sme napísali jednoduché bash skripty s curl príkazmi. Fungovali okamžite.
Poznatek: Začni jednoducho. Bash skripty s curl pokryjú 80 % cesty. Pridávaj zložitosť len vtedy, keď jednoduché riešenie nestačí.
Metapoznatok
Celá táto metodológia vznikla zo stavby AI Characterov, ktorí museli skutočne fungovať — nie len dobre vyzerať v deme.
Keď stavíš pre demá:
- Abstraktné schopnosti sú v poriadku
- „Vie posielať e-maily” stačí
- Screenshoty konfigurácie vyzerajú pôsobivo
Keď stavíš pre produkciu:
- Otestované recepty sú nevyhnutnosťou
- „Spoľahlivo posiela e-maily cez Resend s našimi prihlasovacími údajmi” je štandard
- Funkčné príklady sú dôležitejšie než zložitosť konfigurácie
Metodologický rozdiel: demá optimalizujú pre šírku schopností, produkcia optimalizuje pre hĺbku spoľahlivosti.
Stavíme AI tímy, kde Characteri robia reálnu prácu. To nás donútilo vyriešiť problém spoľahlivosti.
Bottom-up metodológia zameraná na recepty je výsledkom.
Vyskúšaj sám
Ako vytvoriť Character, ktorý skutočne funguje:
-
Definuj konkrétnu rolu Nie: „Marketingová AI” Ale: „Marketingový riaditeľ, ktorý posiela týždenné updaty”
-
Vypíš 3 skutočné úlohy Nie: „Analyzovať marketingové dáta” Ale: „Skontrolovať návštevnosť za posledných 7 dní v Google Analytics”
-
Napíš jeden funkčný príklad Nedokumentuj nástroje. Napíš curl príkaz, ktorý funguje. Otestuj ho. Over odpoveď.
-
Vytvor jeden súbor s receptom Ulož funkčný príklad ako
/recipes/nazov-ulohy.mdZahrň: kedy použiť, prihlasovacie údaje, funkčný kód, dátum posledného testu -
Odkazuj z Charactera Systémový prompt odkazuje na súbor s receptom Character vie, kedy ho použiť a ako ho vyvolať
-
Otestuj end-to-end Skutočne použi Character pre úlohu Oprav, čo nefunguje Aktualizuj recept
Začni s jednou úlohou, jedným receptom, jedným Characterom.
Keď vybuduješ jeden, ktorý spoľahlivo funguje, metodológia sa ustáli. Potom rozšír na viac receptov a viac Characterov.
Na stránke /team máme 14 AI Characterov. Vyzerajú profesionálne. Pôsobivé schopnosti. Ale naučili sme sa: vyzerať schopne a byť schopný sú rozdielne veci.
Tí, ktorí skutočne fungujú, majú otestované recepty. Tí, ktorí sú fasádami, majú abstraktné definície nástrojov.
Metodológia nie je zložitá: bottom-up od funkčných príkladov, skladať do Characterov, testovať end-to-end.
Ale obracia spôsob, akým väčšina ľudí buduje AI agentov. A práve toto obrátenie robí Characterov spoľahlivými.
Stav od receptov. Testuj všetko. Dodávaj to, čo funguje.