Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Návrh: Scénáře použití a nástroje

Lekce 3 z 14 Aktualizováno 3. listopadu 2026 Vývojář
Na této stránce
  1. Začni očekáváními, ne API
  2. Inventář scénářů použití
  3. Vylučuj a dokumentuj to
  4. Od scénářů použití k nástrojům
  5. Smlouva každého nástroje
  6. Popisy psané tak, aby byly vybrány
  7. Bezpečnostní anotace
  8. Plán, který slouží jako testovací plán
  9. Klíčové poznatky

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-sdk a manifest chatgpt-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:

PoleOtázka
CílČeho se osoba snaží dosáhnout?
Příkladové dotazyJak by to formulovali, přímo či nepřímo?
Očekávaný výsledekCo by učinilo interakci úspěšnou?
Požadovaný kontextJaké informace, přístup k účtu nebo předchozí stav jsou potřebné?
SchopnostStačí dovednost, nebo je vyžadován nástroj MCP?
Hranice bezpečnostiMůž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_projects k nalezení projektů;
  • get_project k prozkoumání jednoho projektu;
  • create_project k vytvoření projektu;
  • update_project k úpravě detailů;
  • archive_project pro 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

PoleDefinice
NázevStabilní identifikátor orientovaný na akci
TitulekStručný, lidsky čitelný popis akce
PopisUživatelský cíl a podmínky, které by měly nástroj spustit
Schéma vstupuPovinné a volitelné parametry, typy, povolené hodnoty, limity
Schéma výstupuStrukturovaná pole, která může model zkoumat a znovu použít
AutorizaceÚčet, role nebo přístup, který musí server ověřit
Vedlejší účinkyData 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í:

  • readOnlyHint je true pouze tehdy, pokud nástroj nemůže změnit žádný stav;
  • destructiveHint je true, pokud může nástroj způsobit nevratný nebo těžko vratný výsledek;
  • openWorldHint je true, 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