Tervezés: Használati esetek és eszközök
Ezen az oldalon
A leckét 2026. november 3-án írtuk át az OpenAI Brainstorm plugin use cases és Define tools dokumentációs oldalai alapján. Az előző lecke egy nem létező
@openai/apps-sdkcsomagot éschatgpt-app.jsonmanifesztumot telepített; a tényleges eszközök (hivatalos MCP SDK-k) telepítése a 4. leckében történik. Források: Brainstorm plugin use cases · Define tools.
Kezdd az elvárásokkal, ne az API-val
Az OpenAI dokumentációja azt javasolja, hogy még egyetlen sor kód megírása előtt kezdj el építeni egy bővítményt: sorold fel, mit várnak tőle az emberek. A bővítmény neve, leírása, készségei, eszközei és a termék, amelyhez csatlakozik, mind elvárásokat teremtenek; a megvalósításodnak meg kell felelnie ezeknek, vagy szándékos okkal kell eltérnie tőlük.
Képzeld el valakit, aki telepítette a bővítményedet anélkül, hogy elolvasta volna a dokumentációt. Mit fog kérni tőle? Hogy ezt megtudd, meríts azokból a feladatokból, amelyeket felhasználóid már most is elvégeznek a termékedben: ügyfélszolgálati jegyek, keresési lekérdezések, funkciókérések, az általuk használt szókincs, valamint azok a kerülőutak, amelyek arra kényszerítik őket, hogy adatokat másoljanak át egyik eszközből a másikba. Jegyezd fel a közvetlen kéréseket, amelyek név szerint említik a bővítményt, és a közvetett kéréseket is, amelyek csak a célt fogalmazzák meg: egy projektmenedzsment bővítménynek ugyanúgy kezelnie kell az „Mutasd az Acme indulási táblát“ kérést, mint a „Mi akadályozza az indulást?“ kérdést.
Ne korlátozd ezt a leltárt arra, amit az API-d már most is tud. Először sorold fel az elvárásokat, majd hasonlítsd össze őket azzal, amit biztonságosan és megbízhatóan nyújtani tudsz.
A használati esetek leltára
Minden egyes használati esetnél az OpenAI hét kérdés megválaszolását javasolja:
| Mező | Kérdés |
|---|---|
| Cél | Mit próbál elérni az illető? |
| Példa kérések | Hogyan fogalmazná meg ezt, közvetlenül vagy közvetve? |
| Várt eredmény | Mitől lenne sikeres a interakció? |
| Szükséges kontextus | Milyen információkra, fiókhozzáférésre vagy előző állapotra van szükség? |
| Képesség | Elég egy készség (skill), vagy MCP eszköz szükséges? |
| Biztonsági határ | Kiszolgáltathat-e adatokat, módosíthat-e állapotot, költhet-e pénzt, vagy érinthet-e harmadik felet? |
| Döntés | Első verzió, későbbi, vagy szándékos kihagyás? |
Csoportosítsd az azonos célt szolgáló kéréseket: a „Sorold fel a nyitott feladataimat“, a „Mit kell ma megcsinálnom?“ és a „Mutasd a lejárt munkákat“ valószínűleg ugyanahhoz a felülvizsgálati esethez tartoznak, különböző szűrőkkel.
Ezután ellenőrizd a lefedettséget. Minden kiválasztott használati esetnek teljes útvonallal kell rendelkeznie a kéréstől az eredményig; az írási műveleteknek tartalmazniuk kell a jogosultságot és a megerősítést; a bővítménynek pedig tudnia kell közölni, mit nem csinál, miközben hasznos következő lépést kínál. Egy olyan bővítmény, amely lehetővé teszi projektek létrehozását, de nem a listázásukat, megtekintésüket vagy szerkesztésüket, többet ígér, mint amit teljesít: vagy fejezd be, vagy szűkítsd a pozicionálását.
Zárj ki, és dokumentáld
Nem kell mindent megvalósítanod, de minden nagyobb kihagyásnak indokoltnak kell lennie: elfogadhatatlan biztonsági vagy adatvédelmi kockázat, olyan API, amely nem támogatja megbízhatóan, ellenőrizhetetlen engedélyek, hiányzó információk miatt félrevezető eredmények, vagy egy első verziós hatókör, amelyet egyértelműen feltüntetsz a bővítmény listázásában. Rögzítsd ezeket a döntéseket: ezek tájékoztatják a készségek korlátait, az eszközleírásokat, az elutasításokat, a teszteket és a nyilvános listázás szövegét.
A használati esetektől az eszközökig
Egy eszköznek egy felhasználói célt kell szolgálnia. Ne másold le változtatás nélkül a belső API-dat. Minden kiválasztott használati esethez írd le a várt eredményt, sorold fel a szükséges információkat, azonosítsd az olvasási, írási és külső műveleteket, csoportosítsd, ami egy koherens akciót alkot – és válaszd szét azt, ami az engedélyek, kockázat vagy megerősítés szükségessége miatt különbözik.
Az OpenAI példája egy projektekkel foglalkozó bővítményre:
list_projectsa projektek megtalálásához;get_projectegy projekt megvizsgálásához;create_projectegy projekt létrehozásához;update_projecta részletek módosításához;archive_projectegy nagy következményekkel járó állapotváltozáshoz.
Az olvasási és írási műveletek szétválasztása lehetővé teszi, hogy a modell és a felhasználó megkülönböztesse a konzultációt a módosítástól.
Minden eszköz szerződése
| Mező | Meghatározás |
|---|---|
| Név | Stabil, műveletorientált azonosító |
| Cím | Tömör, ember által olvasható művelet |
| Leírás | A felhasználó célja és azok a feltételek, amelyeknek kiváltaniuk kell az eszközt |
| Bemeneti séma | Kötelező és opcionális paraméterek, típusok, megengedett értékek, korlátok |
| Kimeneti séma | Strukturált mezők, amelyeket a modell megvizsgálhat és újra felhasználhat |
| Jogosultság | A fiók, szerep vagy hozzáférés, amelyet a szervernek ellenőriznie kell |
| Mellékhatások | Adatok vagy külső állapot, amelyet az eszköz módosíthat |
| Hibák | Olyan hibák, amelyeket a modell megmagyarázhat vagy helyreállíthat |
Három szabály egészíti ki ezt a táblázatot. Explicit bemenetek: ne bízd a modellre, hogy kitaláljon egy azonosítót vagy fiókhatókört. Újrafelhasználható kimenetek: adj vissza stabil azonosítókat és elegendő információt a következő híváshoz. Tiszta kimenetek: nincs titkos adat, hozzáférési token, belső diagnosztika vagy felesleges személyes adat.
Leírások, amelyeket kiválasztanak
A modell a leírások alapján választ eszközöket: írd le a felhasználó szándékát, ne a megvalósítást. Egy jó leírás elmondja, mit csinál az eszköz, mikor kell használni, miben különbözik a szomszédaitól, és mik a korlátai vagy előfeltételei. Kerüld azokat, amelyek ismétlik az eszköz nevét, vagy olyan belső zsargont használnak, amelyet a felhasználóid nem ismernek.
Biztonsági annotációk
Minden eszköz annotációkat hordoz, amelyeket a tényleges viselkedése alapján állítasz be:
- A
readOnlyHintcsak akkortrue, ha az eszköz nem módosíthat semmilyen állapotot; - A
destructiveHintakkortrue, ha az eszköz visszafordíthatatlan vagy nehezen visszavonható eredményt hozhat létre; - Az
openWorldHintakkortrue, ha az eszköz hozzáfér a nyilvános internethez vagy nyílt külső entitásokhoz, még akkor is, ha csak olvasási műveletről van szó, mint például egy webes keresés. Egy privát, korlátozott fiók vagy munkaterület nem „nyílt“ csak azért, mert máshol van hosztolva.
Az annotációk segítik a ChatGPT-t és a Codexet a megfelelő megerősítési szint kiválasztásában, de nem helyettesítik a szerveroldali jogosultságkezelést, a bemeneti validálást vagy a fontos műveletekhez szükséges megerősítést.
Terv, amely tesztként is szolgál
Tartsd meg a leltárt és az eszköztervet: ezek lesznek az ellenőrzőlistád. Adj hozzá közvetlen, közvetett, szélsőséges és hatókörön kívüli kéréseket, és ellenőrizd, hogy a kész bővítmény mindegyik esetén a várt módon viselkedik-e. Keress olyan eszközöket is, amelyek nem szolgálnak dokumentált használati esetet, hiányzó olvasási műveleteket az írás előtt, valamint túl hasonló leírásokat, amelyek összezavarhatják a modellt.
Főbb megállapítások
- Kezdd azzal, mire számítanak a felhasználók, majd hasonlítsd össze azzal, amit biztonságosan nyújtani tudsz
- Hét kérdésből álló leltár használati esetenként, beleértve a szándékos kihagyásokat is
- Egy eszköz egy koherens művelethez; az olvasás és írás szétválasztva
- Egy szerződés eszközönként: név, cím, leírás, sémák, jogosultság, mellékhatások, hibák
- Az annotációk (
readOnlyHint,destructiveHint,openWorldHint) a tényleges viselkedést követik, és nem helyettesítik a jogosultságkezelést