TeamDay.ai
Metodologie návrhu Characterů: Jak vytvořit AI agenty, kteří skutečně fungují
← Back
Claude & Jozo · 9 min read · 2026/02/12
AI AgentiNávrh CharacterůVývojMetodologie

Metodologie návrhu Characterů: Jak vytvořit AI agenty, kteří skutečně fungují

Většina tutoriálů o AI agentech začíná konfigurací nástrojů. Připoj tento MCP server. Zaregistruj tu skill. Nastav tyto prompty.

Pak se uživatelé diví, proč jejich agent „Marketingový ředitel” jeden den posílá e-maily přes SendGrid a druhý den přes Mailgun. Nebo proč „SEO analytik” někdy dotazuje Google Analytics, někdy Search Console a jindy si metriky jednoduše vymýšlí.

Agenti jsou teoreticky schopní. Mají e-mailové nástroje. Mají přístup k analytice. Ale spolehlivě nefungují.

Tady je to, co jsme se naučili při budování 14 AI Characterů pro TeamDay: problém nejsou nástroje. Problém je metodologie.

Past abstrakcí

Ekosystém AI agentů miluje taxonomie. Nástroje vs. MCP servery vs. skills vs. pluginy vs. prompty. Vývojáři tráví hodiny debatami: má být e-mail MCP nástroj nebo skill s bash skriptem?

Z pohledu business uživatele jsou tyto rozdíly bezvýznamné.

Když někdo požádá svého Marketingového ředitele, aby „odeslal týdenní update”, nezajímá ho, jestli e-mail odejde přes:

  • MCP nástroj volající Resend API
  • Skill spouštějící bash curl příkaz
  • TypeScript skript s přihlašovacími údaji z env proměnných
  • Přímé SMTP přes sendmail

Zajímá je, jestli e-mail odejde. Správně. Pokaždé.

Odstraň abstrakce a zůstanou ti přesně dva primitiva:

1. Spustitelné funkce — Kód, který se spustí a vrátí výsledek (nástroje, MCP nástroje, bash příkazy, skripty)

2. Text promptu — Instrukce, které AI čte a dodržuje (systémové prompty, skills, soubory CLAUDE.md)

Vše ostatní je jen balení a organizační struktura kolem těchto dvou primitiv.

Past abstrakcí nastane, když optimalizuješ pro taxonomii (výběr mezi typy nástrojů) místo pro spolehlivost (funguje to skutečně?).

Princip funkčního příkladu

Tady je skutečná jednotka schopnosti AI agenta:

Funkční příklad s přihlašovacími údaji.

Ne registrace nástroje. Ne konfigurace MCP serveru. Ne popis skilly.

Funkční příklad vypadá takto:

# Odeslat e-mail přes 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 zde</p>"
  }'

# Očekávaná odpověď:
# {"id": "abc-123", "status": "sent"}

# Přihlašovací údaje: RESEND_API_KEY v .env
# Naposledy otestováno: 2026-02-10
# Vlastník: Marketingový tým

Bez funkčního příkladu si Claude vybírá náhodně z 1000 možností. S funkčním příkladem pokaždé sleduje osvědčený postup.

Rozdíl mezi „teoreticky umí posílat e-maily” a „spolehlivě posílá e-maily přes Resend s našimi přihlašovacími údaji” je otestovaný, zdokumentovaný funkční příklad.

Model receptů

Recept je to, čemu říkáme otestovaný, osvědčený funkční příklad pro konkrétní úkol.

Náš Character Marketingový ředitel má tyto recepty:

  • Odeslat e-mail přes Resend (otestováno, přihlašovací údaje v env)
  • Dotazovat Search Console API (otestováno, OAuth nakonfigurováno)
  • Analyzovat klíčová slova přes Ahrefs (otestováno, API klíč v env)
  • Získat data z Google Analytics (otestováno, ID vlastnosti zdokumentováno)

Každý recept obsahuje:

  • Kdy ho použít — „Použij pro odesílání transakčních e-mailů”
  • Odkaz na přihlašovací údaje — „API klíč: RESEND_API_KEY (v .env)”
  • Funkční příklad — Skutečný curl příkaz nebo ukázka kódu, která funguje
  • Očekávaná odpověď — Jak vypadá úspěch
  • Naposledy otestováno — Datum, kdy jsme ověřili, že to skutečně funguje

Recepty nejsou abstraktní definice nástrojů. Jsou to konkrétní, otestované postupy, o nichž víme, že fungují, protože jsme je spustili.

Recepty jsou atomické stavební bloky. Characteři jsou kompozice.

Bottom-up návrh Characterů

Tady je metodologie, která skutečně funguje:

Krok 1: Kdo je tento Character?

Ne abstraktní schopnosti. Konkrétní role a účel.

Špatně: „AI asistent s marketingovými schopnostmi”

Dobře: „Marketingový ředitel, který posílá týdenní přehledy výkonu stakeholderům”

Čím jasnější role, tím snazší návrh.

Krok 2: Jaké úkoly tato role skutečně vykonává?

Ne co teoreticky mohl dělat. Co doslova dělá v úterý ráno.

Pro Marketingového ředitele:

  • Kontrola výkonu kampaní (pondělky v 9:00)
  • Přehled trendů organické návštěvnosti (denně)
  • Odeslání týdenního updatu stakeholderům (pátky ve 16:00)
  • Analýza klíčových slov (na vyžádání)

Všimni si, že jde o úkoly, ne o nástroje. „Kontrola výkonu kampaní” je práce, která se má udělat. Jestli k tomu použije Google Ads API nebo Search Console nebo oboje, je jen implementační detail.

Krok 3: Jak reální lidé tyto úkoly dělají?

Tady se specificky zajímáme o tech stack.

Pro „kontrolu výkonu kampaní”:

  • Reálný člověk se přihlásí do Google Analytics
  • Zobrazí posledních 7 dní návštěvnosti
  • Porovná s předchozím obdobím
  • Zaznamená výrazné změny

Technický překlad:

  • Dotaz na Google Analytics API
  • ID vlastnosti: 478766521
  • Metrika: sessions, pageviews, bounce rate
  • Časové rozmezí: posledních 7 dní vs. předchozích 7 dní
  • Potřebné OAuth přihlašovací údaje

Teď víš, jaký recept vytvořit.

Krok 4: Podporuje naše tech stack toto řešení?

Umíme k těmto API přistupovat z našeho runtime prostředí?

Zkontroluj:

  • Máme přihlašovací údaje? (Zkontroluj .env, zkontroluj nastavení OAuth)
  • Umíme volat API z sandboxu? (Otestuj curl příkaz)
  • Jsou nainstalovány potřebné balíčky? (Zkontroluj Docker image nebo nainstaluj za běhu)

Pokud odpověď je ne, buď:

  • Přidej schopnost do svého runtime prostředí (nainstaluj balíčky, nakonfiguruj OAuth)
  • Použij jiný přístup (MCP server při těžkých závislostech)
  • Uprav roli Characteru (přiznej omezení)

Runtime realita omezuje, co je možné. Pokud psql není nainstalován v sandboxu, žádné množství prompt engineeringu nedá Claudovi přístup k databázi.

Krok 5: Napiš a otestuj recepty

To je kritický krok, který většina lidí přeskočí.

Nepište:

Agent může dotazovat Google Analytics pomocí API.

Napište:

# Dotaz na Google Analytics — Návštěvnost 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 otestováno: 2026-02-10 (fungovalo)
# Vlastník: Marketingový tým
# Přihlašovací údaje: GA_ACCESS_TOKEN z OAuth (vyprší za 1 hod)

Pak to skutečně spusť. Ověř, že to funguje. Oprav, co nefunguje. Zdokumentuj funkční verzi.

Recept je skutečný teprve tehdy, když je otestován.

Krok 6: Sestav Character

Teď máš:

  • Jasnou roli (Marketingový ředitel)
  • Konkrétní úkoly (týdenní updaty, analýza návštěvnosti)
  • Otestované recepty (Search Console, Analytics, Resend)

Character je kompozice:

# Character: Marketingový ředitel

## Role
Jsi Marketingový ředitel TeamDay. Monitoruješ výkon,
analyzuješ trendy a komunikuješ poznatky stakeholderům.

## Klíčové odpovědnosti
- Odesílat týdenní přehledy výkonu (pátky ve 16:00)
- Denně monitorovat organickou návštěvnost
- Na vyžádání analyzovat klíčová slova

## Dostupné recepty

### Odeslat e-mail přes Resend
Kdy: Odesílání updateů stakeholderům
Recept: /recipes/send-email-resend.md

### Dotazovat Search Console
Kdy: Analýza organické návštěvnosti nebo klíčových slov
Recept: /recipes/search-console-query.md

### Získat data z Google Analytics
Kdy: Kontrola celkových trendů návštěvnosti
Recept: /recipes/google-analytics-query.md

## Komunikační styl
- Přímočarý, bez firemního žargonu
- Začínej čísly („+15 % návštěvnost vs. minulý týden")
- Vysvětluj, co se změnilo a proč na tom záleží

Character odkazuje na recepty. Recepty obsahují funkční příklady.

Takto se budují Characteři, kteří skutečně fungují.

Opakované využití díky překryvu tech stacku

Tady se model receptů vyplatí.

Marketingový ředitel potřebuje přístup k Search Console. SEO analytik potřebuje přístup k Search Console. Stejný recept.

Obchodní zástupce potřebuje odesílat e-maily. Marketingový ředitel potřebuje odesílat e-maily. Stejný recept.

Recepty přirozeně tvoří knihovnu:

/recipes/
├── send-email-resend.md
├── search-console-query.md
├── google-analytics-query.md
├── ahrefs-keyword-analysis.md
├── postgres-query.md
└── notion-page-create.md

Každý nový Character přidá možná 1–2 nové recepty. Většina se opakovaně využívá.

Ale to funguje pouze tehdy, když jsou recepty otestované funkční příklady. Pokud jsou to abstraktní definice nástrojů, opakované využití nezáleží, protože stejně spolehlivě nefungují.

Brána kvality

Schopnosti Characteru jsou jen tak reálné, jak reálné jsou jeho otestované recepty.

Otázky, které si klást:

Ne: „Má tento Character nakonfigurovaný e-mail?”

Zeptej se: „Ověřili jsme, že e-mailový recept skutečně odešle e-mail?”

Ne: „Má tento Character přístup k naší databázi?”

Zeptej se: „Otestovali jsme recept pro databázový dotaz s reálnými přihlašovacími údaji?”

Rozdíl mezi Charactery, kteří jsou fasádami, a Charactery, kteří dodávají výsledky, jsou otestované recepty.

Tohle jsme se naučili z vlastní zkušenosti. Vybudovali jsme Charactery pro stránku /team na našem marketingovém webu. Vypadali skvěle. 14 AI zaměstnanců, které si můžeš najmout. Profesionální popisy. Působivé schopnosti.

Pak jsme je zkusili použít pro reálnou práci. Většina nefungovala end-to-end. Chybějící závislosti. Neotestované recepty. Abstraktní schopnosti bez funkčních příkladů.

Brána kvality: Pokud jsme to neotestovali, nepošleme to.

Runtime realita: Co je skutečně možné

Prostředí sandboxu omezuje, co je možné. Pochopení těchto omezení formuje lepší návrh Characterů.

Co funguje všude

HTTP API přes curl:

curl -H "Authorization: Bearer $API_KEY" https://api.example.com/endpoint

Každý sandbox má curl. Pokud se umíš připojit k API přes HTTP, umíš ho integrovat.

Bash skripty:

#!/bin/bash
# Jakákoliv logika, kterou umíš skriptovat, funguje v sandboxu

Běžné CLI nástroje:

git, grep, sed, awk, jq, node, python

Co vyžaduje nastavení

Databázoví klienti:

  • Potřeba nainstalovat psql nebo mysql
  • Možnost 1: Předinstalovat v Docker image
  • Možnost 2: HTTP API wrapper (pg-gateway)
  • Možnost 3: MCP server pro složité dotazy

Těžké balíčky (Puppeteer, Playwright):

  • Velké stromy závislostí
  • Binární závislosti (Chrome)
  • Možnost 1: Předinstalovat v base image (pokud se hojně používá)
  • Možnost 2: MCP server (izolovaný, spravovaný samostatně)

OAuth toky:

  • Interaktivní autentizace
  • Logika obnovení tokenů
  • Možnost 1: Předkonfigurovat tokeny (env proměnné)
  • Možnost 2: MCP server zpracovává auth

Praktický rozhodovací strom

  1. Umíme to přes curl? → Napiš recept, otestuj, hotovo
  2. Potřebuješ balíček < 50 MB? → Nainstaluj do Docker image
  3. Potřebuješ těžké závislosti? → MCP server (poslední možnost)
  4. Potřebuješ interaktivní auth? → MCP server nebo předkonfigurované tokeny

Čím jednodušší runtime požadavky, tím spolehlivější Character.

Rozdíl oproti tomu, jak většina lidí staví

Top-down (běžný přístup):

  1. Vyber framework pro AI agenty
  2. Nakonfiguruj MCP servery
  3. Přidej skills a nástroje
  4. Napiš systémový prompt
  5. Doufej, že to funguje

Problémy:

  • Nástroje nakonfigurované, ale neotestované
  • Žádné funkční příklady, jen abstraktní schopnosti
  • Character může teoreticky dělat cokoliv, spolehlivě nedělá nic
  • První reálné použití odhalí, že to ve skutečnosti nefunguje

Bottom-up (náš přístup):

  1. Definuj konkrétní roli a úkoly
  2. Namapuj úkoly na reálné lidské pracovní postupy
  3. Otestuj a ověř každý pracovní postup (napiš recepty)
  4. Sestav Character z otestovaných receptů
  5. Brána kvality: každá schopnost je ověřena

Výsledek:

  • Každý recept je otestovaný a o jeho funkčnosti víme
  • Schopnosti Characteru odpovídají otestované realitě
  • První použití funguje, protože recepty byly ověřeny
  • Když se něco rozbije, víme, který recept opravit

Metodologie obrací proces: začínáme od ověřených pracovních postupů, skládáme nahoru k Characterům — ne konfigurujeme nástroje shora a doufáme.

Reálný příklad: Marketingový ředitel

Ukažme si skutečný proces návrhu pro jednoho z našich Characterů.

Krok 1: Definice role

Kdo: Marketingový ředitel TeamDay Účel: Monitorování marketingového výkonu a komunikace poznatků

Krok 2: Skutečné úkoly

Po pozorování reálné marketingové práce:

  • Kontrola Google Analytics pro trendy návštěvnosti (denně)
  • Monitorování Search Console pro organická klíčová slova (týdně)
  • Odesílání přehledů výkonu stakeholderům (týdně)
  • Analýza konkrétních kampaní na vyžádání

Krok 3: Reálný lidský pracovní postup

Pro „odeslání týdenního updatu”:

  1. Člověk se přihlásí do Google Analytics
  2. Zobrazí posledních 7 dní: sessions, pageviews, top stránky
  3. Porovná s předchozím týdnem
  4. Zaznamená výrazné změny
  5. Zkontroluje Search Console pro top dotazy
  6. Sestaví e-mail s výsledky
  7. Odešle přes Gmail

Krok 4: Kontrola tech stacku

Google Analytics:

  • ✅ Máme přístup k API
  • ✅ ID vlastnosti: 478766521
  • ✅ OAuth nakonfigurováno
  • ✅ Umíme dotazovat přes curl

Search Console:

  • ✅ Máme přístup k API
  • ✅ Web: teamday.ai
  • ✅ OAuth nakonfigurováno
  • ✅ Umíme dotazovat přes curl

E-mail:

  • ✅ Používáme Resend (ne Gmail)
  • ✅ API klíč v env: RESEND_API_KEY
  • ✅ Umíme odesílat přes curl

Krok 5: Napiš recepty

Recept 1: Google Analytics — Posledních 7 dní

#!/bin/bash
# Získej návštěvnost 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ýsledek testu (2026-02-10):
# {
#   "rows": [
#     {"dimensionValues": [{"value": "/"}],
#      "metricValues": [{"value": "1243"}, {"value": "892"}, ...]}
#   ]
# }

# Přihlašovací údaje: GA_ACCESS_TOKEN (OAuth, platnost 1 hod)

Otestováno: ✅ Funguje Naposledy ověřeno: 2026-02-10

Recept 2: Odeslat e-mail přes Resend

#!/bin/bash
# Odeslat e-mail přes 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ýsledek testu (2026-02-10):
# {"id": "abc-123", "status": "sent"}

# Přihlašovací údaje: RESEND_API_KEY v .env

Otestováno: ✅ Funguje Naposledy ověřeno: 2026-02-10

Krok 6: Sestav Character

# Marketingový ředitel

Jsi Marketingový ředitel TeamDay. Monitoruješ výkon
a komunikuješ poznatky.

## Úkol: Týdenní update

Každý pátek ve 16:00:

1. Dotazuj Google Analytics (posledních 7 dní vs. předchozí)
   Recept: /recipes/google-analytics-7day.sh

2. Dotazuj Search Console (top organické dotazy)
   Recept: /recipes/search-console-top-queries.sh

3. Sestav e-mail:
   - Předmět: „TeamDay Marketing Update — Týden od [datum]"
   - Formát:
     **Návštěvnost:** [sessions] ([+/-]% vs. minulý týden)
     **Top stránky:** [seznam top 3]
     **Top dotazy:** [seznam top 3]
     **Výrazné změny:** [cokoliv > 20% změna]

4. Odešli přes Resend
   Recept: /recipes/send-email-resend.sh
   Komu: jozo at teamday.ai

Výsledek: Character, který spolehlivě odesílá týdenní updaty, protože každý krok je otestovaný recept.

Co jsme se naučili z vlastní zkušenosti

1. „Otestováno” znamená skutečně otestováno

Dokumentovali jsme recepty. Vypadaly dobře. Vypustili jsme Charactery.

Pak jsme je zkusili použít. Polovina receptů nikdy nebyla spuštěna. API endpointy se změnily. Přihlašovací údaje byly špatné. ID vlastností byly zastaralé.

Řešení: Otestuj každý recept. Skutečně ho spusť. Ověř odpověď. Aktualizuj, když se API změní.

2. Recepty zastarávají

API se mění. Přihlašovací údaje expirují. Služby jsou zrušeny.

Řešení: Datuj každý recept. Když Character selže, zkontroluj data receptů. Otestuj znovu a aktualizuj.

3. Runtime mezery jsou reálné

Navrhli jsme Character SQL analytika, který dotazuje naši databázi. Pak jsme zjistili, že psql není nainstalován v sandboxu.

Řešení: Otestuj runtime schopnosti před návrhem Characterů. Pokud psql tam není, buď ho nainstaluj nebo použij HTTP API wrapper.

4. Kompozice poráží konfiguraci

Strávili jsme týdny konfigurací MCP serverů pro různé schopnosti. Složité nastavení. Mnoho pohyblivých částí.

Pak jsme napsali jednoduché bash skripty s curl příkazy. Fungovaly okamžitě.

Poznatek: Začni jednoduše. Bash skripty s curl pokryjí 80 % cesty. Přidávej složitost pouze tehdy, když jednoduché řešení nestačí.

Metapoznatek

Celá tato metodologie vznikla ze stavby AI Characterů, kteří museli skutečně fungovat — ne jen dobře vypadat v demu.

Když stavíš pro dema:

  • Abstraktní schopnosti jsou v pořádku
  • „Umí posílat e-maily” stačí
  • Screenshoty konfigurace vypadají působivě

Když stavíš pro produkci:

  • Otestované recepty jsou nutností
  • „Spolehlivě posílá e-maily přes Resend s našimi přihlašovacími údaji” je standard
  • Funkční příklady jsou důležitější než složitost konfigurace

Metodologický rozdíl: dema optimalizují pro šíři schopností, produkce optimalizuje pro hloubku spolehlivosti.

Stavíme AI týmy, kde Characteři dělají reálnou práci. To nás donutilo vyřešit problém spolehlivosti.

Bottom-up metodologie zaměřená na recepty je výsledkem.

Vyzkoušej sám

Jak vytvořit Character, který skutečně funguje:

  1. Definuj konkrétní roli Ne: „Marketingová AI” Ale: „Marketingový ředitel, který posílá týdenní updaty”

  2. Vypiš 3 skutečné úkoly Ne: „Analyzovat marketingová data” Ale: „Zkontrolovat návštěvnost za posledních 7 dní v Google Analytics”

  3. Napiš jeden funkční příklad Nedokumentuj nástroje. Napiš curl příkaz, který funguje. Otestuj ho. Ověř odpověď.

  4. Vytvoř jeden soubor s receptem Ulož funkční příklad jako /recipes/nazev-ukolu.md Zahrň: kdy použít, přihlašovací údaje, funkční kód, datum posledního testu

  5. Odkaž z Characteru Systémový prompt odkazuje na soubor s receptem Character ví, kdy ho použít, jak ho vyvolat

  6. Otestuj end-to-end Skutečně použij Character pro úkol Oprav, co nefunguje Aktualizuj recept

Začni s jedním úkolem, jedním receptem, jedním Characterem.

Jakmile vybuduješ jeden, který spolehlivě funguje, metodologie se ustálí. Pak rozšiř na více receptů a více Characterů.

Na stránce /team máme 14 AI Characterů. Vypadají profesionálně. Působivé schopnosti. Ale naučili jsme se: vypadat schopně a být schopný jsou různé věci.

Ti, kteří skutečně fungují, mají otestované recepty. Ti, kteří jsou fasádami, mají abstraktní definice nástrojů.

Metodologie není složitá: bottom-up od funkčních příkladů, skládat do Characterů, testovat end-to-end.

Ale obrací způsob, jak většina lidí buduje AI agenty. A právě to obrácení dělá Charactery spolehlivými.

Stav od receptů. Testuj vše. Dodávej to, co funguje.