Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Tervezés: Használati esetek és eszközök

3. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. Kezdd az elvárásokkal, ne az API-val
  2. A használati esetek leltára
  3. Zárj ki, és dokumentáld
  4. A használati esetektől az eszközökig
  5. Minden eszköz szerződése
  6. Leírások, amelyeket kiválasztanak
  7. Biztonsági annotációk
  8. Terv, amely tesztként is szolgál
  9. Főbb megállapítások

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-sdk csomagot és chatgpt-app.json manifesztumot 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élMit próbál elérni az illető?
Példa kérésekHogyan fogalmazná meg ezt, közvetlenül vagy közvetve?
Várt eredményMitől lenne sikeres a interakció?
Szükséges kontextusMilyen információkra, fiókhozzáférésre vagy előző állapotra van szükség?
KépességElég egy készség (skill), vagy MCP eszköz szükséges?
Biztonsági határKiszolgáltathat-e adatokat, módosíthat-e állapotot, költhet-e pénzt, vagy érinthet-e harmadik felet?
DöntésElső 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_projects a projektek megtalálásához;
  • get_project egy projekt megvizsgálásához;
  • create_project egy projekt létrehozásához;
  • update_project a részletek módosításához;
  • archive_project egy 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évStabil, műveletorientált azonosító
CímTömör, ember által olvasható művelet
LeírásA felhasználó célja és azok a feltételek, amelyeknek kiváltaniuk kell az eszközt
Bemeneti sémaKötelező és opcionális paraméterek, típusok, megengedett értékek, korlátok
Kimeneti sémaStrukturált mezők, amelyeket a modell megvizsgálhat és újra felhasználhat
JogosultságA fiók, szerep vagy hozzáférés, amelyet a szervernek ellenőriznie kell
MellékhatásokAdatok vagy külső állapot, amelyet az eszköz módosíthat
HibákOlyan 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 readOnlyHint csak akkor true, ha az eszköz nem módosíthat semmilyen állapotot;
  • A destructiveHint akkor true, ha az eszköz visszafordíthatatlan vagy nehezen visszavonható eredményt hozhat létre;
  • Az openWorldHint akkor true, 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