Návrh: Scénáře použití a nástroje
Na této stránce
Lekce přepracována 3. listopadu 2026 na základě dokumentace OpenAI Brainstorm plugin use cases a Define tools. Předchozí lekce instalovala neexistující balíček
@openai/apps-sdka manifestchatgpt-app.json; instalace skutečných nástrojů (oficiální MCP SDK) proběhne v lekci 4. Zdroje: Brainstorm plugin use cases · Define tools.
Začni očekáváními, ne API
Dokumentace OpenAI radí začít s tvorbou pluginu ještě před napsáním prvního řádku kódu: sestavením seznamu toho, co od něj lidé budou očekávat. Název pluginu, popis, dovednosti, nástroje a produkt, ke kterému se připojuje, všechno vytváří očekávání; tvá implementace je musí splnit, nebo mít promyšlený důvod, proč tak nečiní.
Představ si někoho, kdo si tvůj plugin nainstaloval, aniž by četl dokumentaci. Co se ho zeptá? Abys to zjistil, vycházej z úkolů, které uživatelé ve tvém produktu již plní, z ticketů podpory, vyhledávacích dotazů, žádostí o funkce, slovníku, který používají, a z nouzových řešení, která je nutí kopírovat data z jednoho nástroje do druhého. Všímej si přímých žádostí, které jmenují plugin, i nepřímých žádostí, které uvádějí pouze cíl: plugin pro správu projektů musí zpracovat „Ukaž nástěnku spuštění Acme“ stejně jako „Co brzdí spuštění?“.
Neomezuj tento inventář pouze na to, co tvé API již umí. Nejprve sepiš očekávání a teprve poté je porovnej s tím, co můžeš poskytnout bezpečně a spolehlivě.
Inventář scénářů použití
Pro každý scénář použití OpenAI doporučuje odpovědět na sedm otázek:
| Pole | Otázka |
|---|---|
| Cíl | Čeho se osoba snaží dosáhnout? |
| Příkladové dotazy | Jak by to formulovali, přímo či nepřímo? |
| Očekávaný výsledek | Co by učinilo interakci úspěšnou? |
| Požadovaný kontext | Jaké informace, přístup k účtu nebo předchozí stav jsou potřebné? |
| Schopnost | Stačí dovednost, nebo je vyžadován nástroj MCP? |
| Hranice bezpečnosti | Může to odhalit data, změnit stav, utratit peníze nebo ovlivnit třetí stranu? |
| Rozhodnutí | První verze, později, nebo záměrné vyloučení? |
Sdruž žádosti, které sdílejí stejný cíl: „Vypiš mé otevřené úkoly“, „Co musím dnes dělat?“ a „Ukaž opožděnou práci“ pravděpodobně patří do stejného scénáře přezkoumání úkolů, liší se pouze filtry.
Následně ověř pokrytí. Každý vybraný scénář použití musí mít kompletní cestu od žádosti k výsledku; operace zápisu musí zahrnovat autorizaci a potvrzení; a plugin musí vědět, jak sdělit, co nedělá, a zároveň nabídnout užitečný další krok. Plugin, který umožňuje vytvářet projekty, ale ne vypisovat, zobrazovat ani upravovat je, slibuje více, než dodává: buď jej dokonči, nebo zúž jeho zaměření.
Vylučuj a dokumentuj to
Nemusíš implementovat všechno, ale každé zásadní vyloučení si zaslouží důvod: nepřijatelné riziko pro bezpečnost nebo soukromí, API, které to nemůže spolehlivě podpořit, neověřitelná oprávnění, zavádějící výsledky kvůli chybějícím informacím, nebo rozsah první verze jasně uvedený v seznamu pluginů. Tato rozhodnutí zaznamenej: informují o limitech dovedností, popisech nástrojů, odmítnutích, testech a textu veřejného seznamu.
Od scénářů použití k nástrojům
Nástroj musí sloužit uživatelskému cíli. Nekopíruj své interní API tak, jak je. Pro každý vybraný scénář použití napiš očekávaný výsledek, uveď požadované informace, identifikuj čtení, zápisy a externí akce, seskup to, co tvoří ucelenou akci – a odděl to, co se liší oprávněními, rizikem nebo potřebou potvrzení.
Příklad OpenAI pro plugin projektů:
list_projectsk nalezení projektů;get_projectk prozkoumání jednoho projektu;create_projectk vytvoření projektu;update_projectk úpravě detailů;archive_projectpro změnu stavu s vysokými důsledky.
Čtení a zápisy jsou odděleny, aby si model a uživatel mohli rozlišit konzultaci od modifikace.
Smlouva každého nástroje
| Pole | Definice |
|---|---|
| Název | Stabilní identifikátor orientovaný na akci |
| Titulek | Stručný, lidsky čitelný popis akce |
| Popis | Uživatelský cíl a podmínky, které by měly nástroj spustit |
| Schéma vstupu | Povinné a volitelné parametry, typy, povolené hodnoty, limity |
| Schéma výstupu | Strukturovaná pole, která může model zkoumat a znovu použít |
| Autorizace | Účet, role nebo přístup, který musí server ověřit |
| Vedlejší účinky | Data nebo externí stav, který může nástroj změnit |
| Selhání | Chyby, které může model vysvětlit nebo zotavit se z nich |
Tuto tabulku doplňují tři pravidla. Explicitní vstupy: nespoléhej se na to, že model uhodne ID nebo rozsah účtu. Opakovaně použitelné výstupy: vracej stabilní ID a dostatek informací pro další volání. Čisté výstupy: žádná tajemství, přístupové tokeny, interní diagnostika ani zbytečná osobní data.
Popisy psané tak, aby byly vybrány
Model vybírá nástroje na základě jejich popisu: popiš uživatelský záměr, nikoliv implementaci. Dobrý popis říká, co nástroj dělá, kdy jej použít, jak se liší od svých sousedů a jaké jsou jeho limity nebo předpoklady. Vyvaruj se popisů, které opakují název nástroje nebo používají interní žargon, který tvoji uživatelé neznají.
Bezpečnostní anotace
Každý nástroj nese anotace nastavené na základě jeho skutečného chování:
readOnlyHintjetruepouze tehdy, pokud nástroj nemůže změnit žádný stav;destructiveHintjetrue, pokud může nástroj způsobit nevratný nebo těžko vratný výsledek;openWorldHintjetrue, pokud nástroj přistupuje k veřejnému internetu nebo otevřeným externím entitám, dokonce i jen ke čtení, jako je webové vyhledávání. Soukromý, ohraničený účet nebo pracovní prostor není „otevřený“ jen proto, že je hostován jinde.
Anotace pomáhají ChatGPT a Codex zvolit správnou úroveň potvrzení, ale nenahrazují autorizaci na straně serveru, validaci vstupů ani potvrzení pro důležité akce.
Plán, který slouží jako testovací plán
Udržuj inventář a plán nástrojů: stanou se tvým kontrolním seznamem. Přidej přímé, nepřímé, hraniční a mimo-rozsah žádosti a ověř, že se hotový plugin chová podle očekávání pro každou z nich. Hledej také nástroje, které neslouží žádnému zdokumentovanému scénáři použití, chybějící čtení před zápisy a popisy, které jsou si příliš podobné a mohly by model zmást.
Klíčové poznatky
- Začni tím, co uživatelé budou očekávat, a poté to porovnej s tím, co můžeš bezpečně poskytnout
- Sedmiotázkový inventář pro každý scénář použití, včetně záměrných vyloučení
- Jeden nástroj na jednu ucelenou akci; čtení a zápisy odděleny
- Jedna smlouva na nástroj: název, titulek, popis, schémata, autorizace, vedlejší účinky, selhání
- Anotace (
readOnlyHint,destructiveHint,openWorldHint) vycházejí ze skutečného chování a nenahrazují autorizaci