Návrh: Prípady použitia a nástroje
Na tejto strane
Lekcia prepísaná 3. novembra 2026 na základe dokumentácie OpenAI o prípadoch použitia pluginu Brainstorm a definícii nástrojov. Predchádzajúca lekcia inštalovala neexistujúci balík
@openai/apps-sdka manifestchatgpt-app.json; inštalácia skutočných nástrojov (oficiálne MCP SDK) prebieha v lekcii 4. Zdroje: Prípady použitia pluginu Brainstorm · Definícia nástrojov.
Začni očakávaniami, nie API
Dokumentácia OpenAI hovorí, aby si začal stavať plugin ešte pred napísaním jediného riadku kódu: zostavením zoznamu toho, čo od neho ľudia budú očakávať. Názov pluginu, popis, zručnosti, nástroje a produkt, ku ktorému sa pripája, vytvárajú očakávania; tvoja implementácia ich musí splniť, alebo mať úmyselný dôvod, prečo nie.
Predstav si niekoho, kto si nainštaloval tvoj plugin bez prečítania dokumentácie. O čo ho požiada? Aby si to zistil, čerpaj z úloh, ktoré tvoji používatelia už vo svojom produkte vykonávajú, z ticketov podpory, vyhľadávacích dopytov, žiadostí o funkcie, slovnej zásoby, ktorú používajú, a obchádzaní problémov, ktoré ich nútia kopírovať údaje z jedného nástroja do druhého. Všimni si priame žiadosti, ktoré menujú plugin, aj nepriame žiadosti, ktoré uvádzajú iba cieľ: plugin na riadenie projektov musí spracovať „Zobraziť spúšťaciu tabuľu Acme“ rovnako ako „Čo brzdí spustenie?“.
Neobmedzuj tento inventár len na to, čo tvoje API už robí. Najprv vypíš očakávania a potom ich porovnaj s tým, čo môžeš poskytnúť bezpečne a spoľahlivo.
Inventár prípadov použitia
Pre každý prípad použitia OpenAI odporúča odpovedať na sedem otázok:
| Pole | Otázka |
|---|---|
| Cieľ | Čo sa osoba snaží dosiahnuť? |
| Príkladové žiadosti | Ako by to sformulovali, priamo alebo nepriamo? |
| Očakávaný výsledok | Čo by urobilo interakciu úspešnou? |
| Potrebný kontext | Aké informácie, prístup k účtu alebo predchádzajúci stav sú potrebné? |
| Schopnosť | Stačí zručnosť, alebo je potrebný nástroj MCP? |
| Hranica bezpečnosti | Mohlo by to odhaliť údaje, zmeniť stav, minúť peniaze alebo ovplyvniť tretiu stranu? |
| Rozhodnutie | Prvá verzia, neskoršia verzia alebo úmyselné vylúčenie? |
Zoskup žiadosti, ktoré zdieľajú cieľ: „Vypíš moje otvorené úlohy“, „Čo musím dnes urobiť?“ a „Ukáž oneskorenú prácu“ pravdepodobne patria do rovnakého prípadu použitia revízie úloh, len s rôznymi filtrami.
Potom over pokrytie. Každý vybraný prípad použitia musí mať úplnú cestu od žiadosti po výsledok; zápisy musia zahŕňať autorizáciu a potvrdenie; a plugin musí vedieť povedať, čo nerobí, pričom ponúkne užitočný ďalší krok. Plugin, ktorý ti umožňuje vytvárať projekty, ale nie ich vypisovať, zobrazovať alebo upravovať, sľubuje viac, než dodáva: buď ho dokonči, alebo zúž jeho pozíciu na trhu.
Vylúčenie a jeho zdokumentovanie
Nemusíš implementovať všetko, ale každé veľké vylúčenie si vyžaduje dôvod: neprijateľné riziko bezpečnosti alebo súkromia, API, ktoré to nedokáže spoľahlivo podporiť, neoveriteľné povolenia, zavádzajúce výsledky kvôli chýbajúcim informáciám alebo rozsah prvej verzie jasne uvedený v zozname pluginov. Zaznamenaj tieto rozhodnutia: informujú o limitoch zručností, popisoch nástrojov, odmietnutiach, testoch a texte verejného zoznamu.
Od prípadov použitia k nástrojom
Nástroj musí slúžiť cieľu používateľa. Nekopíruj svoje interné API tak, ako je. Pre každý vybraný prípad použitia napíš očakávaný výsledok, vypíš potrebné informácie, identifikuj čítania, zápisy a externé akcie, zoskup to, čo tvorí súdržnú akciu – a oddel to, čo sa líši podľa povolení, rizika alebo potreby potvrdenia.
Príklad OpenAI pre plugin na projekty:
list_projectsna nájdenie projektov;get_projectna preskúmanie jedného projektu;create_projectna vytvorenie projektu;update_projectna úpravu detailov;archive_projectpre zmenu stavu s vysokými dôsledkami.
Čítania a zápisy sú oddelené, aby model a používateľ mohli rozlíšiť konzultáciu od úpravy.
Zmluva každého nástroja
| Pole | Definícia |
|---|---|
| Názov | Stabilný identifikátor orientovaný na akciu |
| Titulok | Stručná, čitateľná akcia pre človeka |
| Popis | Cieľ používateľa a podmienky, ktoré by mali spustiť nástroj |
| Schéma vstupu | Povinné a voliteľné parametre, typy, povolené hodnoty, limity |
| Schéma výstupu | Štruktúrované polia, ktoré môže model skontrolovať a znovu použiť |
| Autorizácia | Účet, rola alebo prístup, ktorý musí server overiť |
| Vedľajšie účinky | Údaje alebo externý stav, ktorý môže nástroj zmeniť |
| Zlyhania | Chyby, ktoré môže model vysvetliť alebo z ktorých sa môže zotaviť |
Túto tabuľku dopĺňajú tri pravidlá. Explicitné vstupy: nespoliehaj sa na to, že model uhádne ID alebo rozsah účtu. Opätovne použiteľné výstupy: vráť stabilné ID a dostatok informácií pre ďalšie volanie. Čisté výstupy: žiadne tajomstvá, prístupové tokeny, interná diagnostika ani zbytočné osobné údaje.
Popisy písané tak, aby boli vybrané
Model vyberá nástroje na základe ich popisu: opíš zámer používateľa, nie implementáciu. Dobrý popis hovorí, čo nástroj robí, kedy ho použiť, ako sa líši od svojich susedov a aké sú jeho limity alebo predpoklady. Vyhnite sa tým, ktoré opakujú názov nástroja alebo používajú interný žargón, ktorý tvoji používatelia nepoznajú.
Anotácie bezpečnosti
Každý nástroj nesie anotácie nastavené na základe jeho skutočného správania:
readOnlyHintjetrueiba vtedy, ak nástroj nemôže zmeniť žiadny stav;destructiveHintjetrue, ak môže nástroj spôsobiť nezvratný alebo ťažko vratný výsledok;openWorldHintjetrue, ak nástroj pristupuje k verejnému internetu alebo otvoreným externým entitám, dokonca aj pri čítaní, ako je webové vyhľadávanie. Súkromný, ohraničený účet alebo pracovný priestor nie je „otvorený“ len preto, že je hostený inde.
Anotácie pomáhajú ChatGPT a Codex vybrať správnu úroveň potvrdenia, ale nenahrádzajú autorizáciu na strane servera, validáciu vstupu ani potvrdenie pre dôležité akcie.
Plán, ktorý slúži ako testovací plán
Udržuj inventár a plán nástrojov: stanú sa tvojím kontrolným zoznamom. Pridaj priame, nepriame, hraničné a mimo-rozsahové žiadosti a over, či sa dokončený plugin správa podľa očakávaní pre každú z nich. Hľadaj aj nástroje, ktoré neslúžia žiadnemu zdokumentovanému prípadu použitia, chýbajúce čítania pred zápismi a popisy, ktoré sú príliš podobné a mohli by model zmiasť.
Kľúčové poznatky
- Začni tým, čo používatelia očakávajú, a potom to porovnaj s tým, čo môžeš bezpečne poskytnúť
- Sedemotázkový inventár pre každý prípad použitia vrátane úmyselných vylúčení
- Jeden nástroj na jednu súdržnú akciu; čítania a zápisy oddelené
- Jedna zmluva na nástroj: názov, titulok, popis, schémy, autorizácia, vedľajšie účinky, zlyhania
- Anotácie (
readOnlyHint,destructiveHint,openWorldHint) nasledujú skutočné správanie a nenahrádzajú autorizáciu